docs: add example tests a2a by cchinchilla-dev · Pull Request #240 · a2aproject/a2a-go

cchinchilla-dev · 2026-02-24T22:36:18Z

Description

Ref #209 🦕

Motivation

The a2a/ core types package does not include testable examples (Example_* functions). Usage snippets exist in the README and doc.go, but they are not executable, not validated by go test, and do not render as function-level examples on pkg.go.dev.

Changes

Add a2a/example_test.go using package a2a_test (external test package), following Go's ExampleXxx / ExampleType_Method naming convention.

Examples added for the following public API surface:

Function / Type	Example demonstrates
`NewMessage`	Creating a basic user message with text parts
`NewMessageForTask`	Creating a message referencing an existing task
`NewSubmittedTask`	Initializing a task from an initial message
`TaskState.Terminal()`	Checking whether a state is terminal
`UnmarshalEventJSON`	Deserializing a streaming event using the kind discriminator
`UnmarshalEventJSON` (Message)	Deserializing a message event variant
`NewError` / `Error.WithDetails`	Constructing structured A2A errors
`NewStatusUpdateEvent`	Creating a status update event
`NewArtifactEvent`	Creating an artifact update event
`Message.MarshalJSON` / `Task.MarshalJSON`	Verifying the `kind` discriminator in JSON output

All examples include // Output: comments and are validated by go test.

Tests

The examples themselves are tests — validated through output matching. All 12 pass. Existing tests are unaffected.

go test ./a2a/ -v -run Example

Additional context

Scoped to the a2a/ core package to keep the review focused. If this aligns with the project's direction, I'm planning follow-up PRs for a2aclient/ and a2asrv/.

Let me know if you'd like any changes — happy to iterate.

gemini-code-assist · 2026-02-24T22:36:32Z

Summary of Changes

Hello @cchinchilla-dev, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the a2a/ core types package by integrating comprehensive, testable examples directly into the codebase. This initiative aims to improve the discoverability and reliability of usage documentation, ensuring that code snippets are always up-to-date and functionally correct, particularly for rendering on pkg.go.dev.

Highlights

New Testable Examples: Introduced a2a/example_test.go to provide executable and validated usage examples for the a2a core types package, improving documentation on pkg.go.dev.
API Coverage: Added examples for key public API elements including message creation (NewMessage, NewMessageForTask), task management (NewSubmittedTask, TaskState.Terminal()), event unmarshaling (UnmarshalEventJSON), error handling (NewError, Error.WithDetails), event creation (NewStatusUpdateEvent, NewArtifactEvent), and JSON marshaling (Message.MarshalJSON, Task.MarshalJSON).
Test Validation: All new examples include // Output: comments, ensuring they are automatically validated by go test and confirm expected behavior.

Changelog

a2a/example_test.go
- Added a new file to host Example functions for the a2a package.

Activity

The author confirmed that all 12 new examples pass their respective tests.
Existing tests were verified to be unaffected by these changes.
The scope was intentionally limited to the a2a/ core package, with plans for follow-up PRs for a2aclient/ and a2asrv/ if this approach is approved.
The author expressed openness to feedback and iteration on the proposed changes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

The pull request introduces valuable example tests for the a2a core package, significantly enhancing documentation and providing executable usage snippets. The examples cover various core types and functions, which is a great addition to the project. There are a couple of minor improvements related to error handling in JSON unmarshaling and adherence to the repository's guideline for using constructor functions when creating core types.

a2a/example_test.go

cchinchilla-dev · 2026-02-24T22:43:23Z

Applied all suggestions — switched to constructor usage and added explicit error handling for json.Unmarshal. Thanks for the catch.

yarolegovich · 2026-02-27T12:48:51Z

Hi, sorry for not responding on the issue. I think that'd be a great contribution, but we're about to promote release/spec-v1 to main with tons of changes. Can you please merge and check if things work after that.
Thanks

cchinchilla-dev · 2026-02-27T16:51:57Z

Hi @yarolegovich! No worries at all — completely understand the pace with the spec v1 transition. Rebased on latest main and all 12 examples pass against the v1 module.
If this looks good to you, I'd like to continue with follow-up PRs adding examples for other packages. Let me know if there's anything you'd like adjusted here first.

yarolegovich · 2026-02-28T15:45:53Z

a2a/example_test.go

+	"errors"
+	"fmt"
+
+	"github.com/a2aproject/a2a-go/a2a"


this is a legacy package now, should be github.com/a2aproject/a2a-go/v1/a2a.
the old name is still available because I imported it for compatibility layer (a2acompat)

You're right, thanks! Updated the import path and made a few adjustments to align with the v1 API. All 12 examples pass.

🤖 I have created a release *beep* *boop* --- ## [1.0.0](v1.0.0-alpha.3...v1.0.0) (2026-03-17) ### Features * implement the new rest error handling ([#282](#282)) ([a3bda30](a3bda30)) * use v2 suffix for module ID and provide compat support ([#270](#270)) ([dd1b6ba](dd1b6ba)), closes [#250](#250) ### Bug Fixes * a2asrv jsonrpc Content-Type ([#265](#265)) ([2568a46](2568a46)) * bugs before going from alpha ([#279](#279)) ([b1f055c](b1f055c)) * GetTaskRequest nil pointer assignment check ([#258](#258)) ([440bb79](440bb79)) * inject headers into service params ([#277](#277)) ([d33f3bd](d33f3bd)), closes [#275](#275) * propagate cancelation signal using task store ([#272](#272)) ([5e1d462](5e1d462)), closes [#245](#245) * regenerate spec and fix returnImmediately ([#284](#284)) ([2eee0b9](2eee0b9)) * task modified after save ([#266](#266)) ([c15febe](c15febe)) * taskupdater result mutable ([#274](#274)) ([6038d92](6038d92)) * update pushsender ([#256](#256)) ([5f7a594](5f7a594)) * use enum values as in the spec ([#261](#261)) ([eb98981](eb98981)), closes [#251](#251) ### Documentation * **a2asrv:** add Example_* test functions for pkg.go.dev documentation ([#262](#262)) ([7888e37](7888e37)) * add example tests a2a ([#240](#240)) ([4fe08a9](4fe08a9)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

gemini-code-assist bot reviewed Feb 24, 2026

View reviewed changes

a2a/example_test.go Outdated Show resolved Hide resolved

a2a/example_test.go Show resolved Hide resolved

a2a/example_test.go Show resolved Hide resolved

cchinchilla-dev added 2 commits February 27, 2026 17:45

docs: add example tests a2a

bab1706

apply review feedback: use constructors and handle unmarshal errors

3616064

cchinchilla-dev force-pushed the docs/add-example-tests-a2a branch from eff6a21 to 3616064 Compare February 27, 2026 16:49

yarolegovich reviewed Feb 28, 2026

View reviewed changes

docs: update to v1

9d94914

yarolegovich approved these changes Mar 1, 2026

View reviewed changes

yarolegovich merged commit 4fe08a9 into a2aproject:main Mar 1, 2026
4 checks passed

a2a-bot mentioned this pull request Mar 1, 2026

chore(main): release 1.0.0 #252

Merged

This was referenced Mar 3, 2026

[Feat]: Add Example_* test functions for a2aclient/ and a2asrv/ packages #257

Closed

[Feat]: Add Example_* test functions for pkg.go.dev documentation #209

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add example tests a2a#240

docs: add example tests a2a#240
yarolegovich merged 3 commits intoa2aproject:mainfrom
cchinchilla-dev:docs/add-example-tests-a2a

cchinchilla-dev commented Feb 24, 2026

Uh oh!

gemini-code-assist bot commented Feb 24, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cchinchilla-dev commented Feb 24, 2026

Uh oh!

yarolegovich commented Feb 27, 2026

Uh oh!

cchinchilla-dev commented Feb 27, 2026

Uh oh!

yarolegovich Feb 28, 2026

Uh oh!

cchinchilla-dev Feb 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

cchinchilla-dev commented Feb 24, 2026

Description

Motivation

Changes

Tests

Additional context

Uh oh!

gemini-code-assist bot commented Feb 24, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cchinchilla-dev commented Feb 24, 2026

Uh oh!

yarolegovich commented Feb 27, 2026

Uh oh!

cchinchilla-dev commented Feb 27, 2026

Uh oh!

yarolegovich Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

cchinchilla-dev Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants