proposal: public a2atest testing package

[hairglasses]

Proposal: Public a2atest package for SDK consumers

Motivation

The a2a-go SDK has excellent internal test infrastructure in internal/testutil/
and internal/testutil/testexecutor/. However, these packages are not accessible
to SDK consumers, which means everyone building A2A agents in Go must create
their own test mocks, in-process servers, and assertion helpers from scratch.

This is the single most common pain point reported by Go SDK adopters. The
Python SDK provides a2a.testing with mock servers and test clients. The JS SDK
has similar utilities. The Go SDK is the only major A2A SDK without public test
helpers.

Current internal test infrastructure

The SDK already has well-designed test utilities that cover the core testing needs:

Internal package	Contents	Consumers
internal/testutil	TestTaskStore, TestPushConfigStore, TestPushSender, TestEventQueue, TestQueueManager, TestWorkQueue, test logger	a2asrv handler tests, internal/taskexec tests
internal/testutil/testexecutor	TestAgentExecutor with control channels, event generators, functional constructors	e2e tests, handler tests

These utilities follow a consistent pattern: they embed the real implementation
and allow individual method overrides via function fields. This is a clean,
composable design that SDK consumers would benefit from directly.

Proposed public API

A new top-level a2atest package (following the convention of a2aclient,
a2asrv, a2aext):

package a2atest

// --- In-process test server ---

// Server is an in-process A2A server for integration testing.
// It starts an httptest.Server with JSON-RPC and REST handlers wired up.
type Server struct { /* ... */ }

// NewServer creates an in-process A2A test server with the given executor
// and options. The server is automatically cleaned up when the test finishes.
func NewServer(t testing.TB, executor a2asrv.AgentExecutor, opts ...ServerOption) *Server

// URL returns the base URL of the test server.
func (s *Server) URL() string

// Card returns the AgentCard for the test server.
func (s *Server) Card() *a2a.AgentCard

// Client returns a pre-configured client connected to the test server.
func (s *Server) Client(t testing.TB) *a2aclient.Client

// Handler returns the underlying RequestHandler for direct handler testing.
func (s *Server) Handler() a2asrv.RequestHandler

// ServerOption configures the test server.
type ServerOption func(*serverConfig)

// WithTaskStore configures the test server with a custom task store.
func WithTaskStore(store taskstore.Store) ServerOption

// WithCapabilities sets the agent capabilities on the test server's AgentCard.
func WithCapabilities(caps a2a.AgentCapabilities) ServerOption

// WithSkills sets the skills on the test server's AgentCard.
func WithSkills(skills []a2a.AgentSkill) ServerOption

// WithCallInterceptors adds call interceptors to the test server.
func WithCallInterceptors(interceptors ...a2asrv.CallInterceptor) ServerOption

// --- Mock executor ---

// Executor is a configurable mock AgentExecutor for testing.
// It embeds the internal TestAgentExecutor functionality.
type Executor struct { /* ... */ }

// NewExecutor creates a mock executor. Without configuration, it returns
// an empty event sequence.
func NewExecutor() *Executor

// FromFunc creates an Executor from a function.
func FromFunc(fn func(ctx context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error]) *Executor

// FromEvents creates an Executor that emits a fixed sequence of events.
func FromEvents(fn func(execCtx *a2asrv.ExecutorContext) []a2a.Event) *Executor

// Emitted returns all events emitted by the executor (thread-safe).
func (e *Executor) Emitted() []a2a.Event

// WithControlChannels returns an Executor with channels for controlling
// execution timing in race condition tests.
func WithControlChannels() (*Executor, *ControlChannels)

// ControlChannels provides channels for controlling executor behavior.
type ControlChannels struct {
    ReqCtx         <-chan *a2asrv.ExecutorContext
    ExecEvent      chan<- a2a.Event
    CancelCalled   <-chan struct{}
    ContinueCancel chan<- struct{}
}

// --- Mock task store ---

// TaskStore is a mock task store that delegates to InMemory by default.
// Individual operations can be overridden.
type TaskStore struct { /* ... */ }

// NewTaskStore creates a mock task store backed by in-memory storage.
func NewTaskStore() *TaskStore

// SetSaveError overrides Create and Update to return the given error.
func (s *TaskStore) SetSaveError(err error) *TaskStore

// SetGetOverride overrides Get to return the given task and error.
func (s *TaskStore) SetGetOverride(task *taskstore.StoredTask, err error) *TaskStore

// WithTasks seeds the store with the given tasks.
func (s *TaskStore) WithTasks(t testing.TB, tasks ...*a2a.Task) *TaskStore

// --- Test logger ---

// NewLogger returns an slog.Logger that directs output to t.Log().
// Output is only printed for failed tests or when running with -v.
func NewLogger(t testing.TB) *slog.Logger

// SetDefaultLogger calls slog.SetDefault with a test logger and restores
// the original logger on test cleanup.
func SetDefaultLogger(t testing.TB)

Design principles

1. Export what already works: The internal test infrastructure is battle-tested.
   The public API should be a thin wrapper, not a rewrite.
2. Zero configuration for common cases: a2atest.NewServer(t, executor) should
   work with no options for the 80% case.
3. Composable for advanced cases: Options for custom stores, interceptors,
   and capabilities cover the remaining 20%.
4. Test cleanup via t.Cleanup(): All resources are automatically cleaned up
   when the test finishes. No manual defer server.Close() needed.
5. Follow the SDK's own patterns: Use t.Helper(), cmp.Diff(),
   t.Parallel(), and the same error formatting conventions documented in AGENTS.md.

Relationship to existing internal packages

The a2atest package would import from internal/testutil initially via
package-level delegation, then gradually replace the internal package as the
public API stabilizes. The internal package can eventually become a thin re-export
or be removed entirely once all internal tests migrate to the public API.

Alternatively, if the maintainers prefer, the internal utilities can be moved
directly to the public package in a single refactor. I am happy to go either
direction.

Implementation plan

I am happy to implement this. Proposed approach:

Phase 1 (1 PR): Create a2atest/ package with:

• Server (in-process server with JSON-RPC handler)
• Executor (wrapping testexecutor.TestAgentExecutor)
• TaskStore (wrapping testutil.TestTaskStore)
• NewLogger and SetDefaultLogger
• Tests and doc.go with package documentation
• Example test showing the full pattern

Phase 2 (follow-up PR): Add:

• REST transport support in test server
• Assertion helpers (AssertTaskState, AssertArtifacts, AssertEvents)
• Push notification test infrastructure (PushConfigStore, PushSender)
• Migration of select internal tests to use the public API

Phase 3 (optional, based on feedback): Add:

• gRPC transport support in test server
• Test fixtures (pre-built AgentCards, common event sequences)
• Benchmarking helpers

Backward compatibility

This is a purely additive change. No existing APIs are modified. The new package
can be imported independently:

import "github.com/a2aproject/a2a-go/v2/a2atest"

Context

I have an open PR (#309) fixing a race condition in task execution cleanup, which gave me familiarity with the internal test infrastructure and motivated this proposal.

Questions for maintainers

1. Does this align with your vision for the SDK's public API surface?
2. Do you prefer the public package to delegate to internal/testutil or to
   directly move the internal code?
3. Are there additional test utilities you've wished existed when writing the
   SDK's own tests?
4. Any naming preferences? (a2atest vs testutil vs testing)

[yarolegovich]

This is an excellent topic and we indeed should address the lack of test utilities.
a2atest will probably be the easiest to use.

I think the package should also expose some kind of a conformance test suite so that dependency implementers (taskstore, eventqueue, workqueue) are able to exercise their implementation and verify how SDK invokes their implementation.

But I'm still thinking about maybe exposing conformance tests from individual packages like eventqueue/eventqueuetest, taskstoretest, workqueuetest.

[kuangmi-bit]

I would like to pick this up.

I recently contributed #360 (eventqueue.Message JSON roundtrip fix — merged) and #358 (security scheme interop), so I have hands-on experience with the eventqueue/taskstore test patterns and the serialization layer.

On the design question: I think combining both approaches works best:

1. a2atest top-level package — Server, Executor, TaskStore (the in-process integration test server from the proposal). This is what most Go SDK adopters need for 80% of testing.

2. Per-package conformance suites (eventqueue/eventqueuetest, taskstore/taskstoretest, workqueue/workqueuetest) — these are what you described: dependency implementers can run these against their custom stores/queues to verify they meet the SDK contract.

The two layers compose naturally: a custom TaskStore implementation would first run taskstoretest.Conformance(t, myStore) to verify correctness, then use it with a2atest.NewServer(t, executor, a2atest.WithTaskStore(myStore)) for integration testing.

Proposed starting point: Phase 1 focused on eventqueue/eventqueuetest (simplest contract, I know it well from #360) + the a2atest.Server and a2atest.Executor. The taskstore suite can follow in Phase 2 since it has more surface area.

@yarolegovich — does this direction look right? Happy to start with a small PR scoped to eventqueue conformance + basic server.

[yarolegovich]

@kuangmi-bit sgtm. Conformance suite packages should ideally "cover" all the invocation cases of the SDK. This involves locating calls of functions from the package and understanding what inputs are legit once and what values the SDK expects in return (both errors and non-error responses).

For the a2atest package the focus should be on identifying a minimalistic set of most commonly needed utilities for test writers. These can be broadly divided into helpers for dependency implementation and data accessor utilities (for example a2atest.GetTextParts(a2a.Event) []string or a2atest.MustToTask(t, a2a.Event)). My suggestion is to start from a small surface and extend it iteratively. The most important thing is consistency of methods and patterns.

Will gladly help with the review.

[kuangmi-bit]

@yarolegovich here is the PR implementing the direction we discussed: #364.

What it covers

a2atest package (154 lines of helpers + 168 lines of server):

• GetTextParts(event) — the accessor you suggested
• MustToTask/MustToMessage/MustToStatusUpdate/MustToArtifactUpdate — type-safe assertions
• FormatEvent(event) — human-readable formatting for test output
• Server — in-process A2A test server with sensible defaults
• Executor — re-exported test executor helpers
• SubscribeToTask — subscription helper with wait + collect

Per-package conformance suites (887 lines across 4 packages):

• eventqueue/eventqueuetest — 3 conformance tests covering Add, Iterate, and Ack for both message and notification types
• taskstore/taskstoretest — 2 conformance tests covering SaveMessage + GetTask (all task states)
• workqueue/workqueuetest — 2 conformance tests covering Enqueue + Dequeue lifecycle
• push/pushtest — 2 conformance tests covering store + config conformance

In-memory conformance tests proving the suites work against real implementations (5 tests total).

The layers compose as discussed: dependency implementers run their per-package conformance suite first, then plug the verified implementation into a2atest.NewServer() for integration testing.

Ready for review.

[kuangmi-bit]

Quick update: the a2atest package PR (#364) and eventqueue conformance suite are ready for review. The package is designed to be usable by any A2A implementation (not just Go) — it reads Agent Cards over HTTP and validates wire-level conformance against the spec. Feedback welcome on the API surface before we merge.