You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(testing): local mock AdCP seller for buyer-side tests (record/replay + fault injection) #1268
Buyer-side implementers (agencies, DSP-side agents, orchestrators) have no local AdCP seller they can script. Today they have two options:
The hosted test-agent.adcontextprotocol.org (src/adcp/testing/test_helpers.py). It's remote and the behavior is fixed: it can't inject a timeout, a malformed response, a submitted → working → completed sequence, or a specific error code. It can't run offline or in CI without network access.
mocker.patch on the client adapter (docs/testing-guide.md). This skips transport and serialization entirely, which hides exactly the bugs buyers hit in production.
The JS adcp mock-server <specialism> doesn't fill this role either. It mocks upstream platforms (GAM-like, auction-like, social, etc.) for seller adapter testing. Its scenario controller (scripted responses, delay_ms, times) is the right shape, but it's aimed at the upstream API, not an AdCP MCP/A2A surface. examples/hello_mock_seller.py points Python users at it.
Proposal
A local mock AdCP seller that buyers run in their tests. It would:
speak MCP and A2A, with responses validated against the pinned AdCP schema version (so the mock can't drift from the spec)
serve canned responses per tool from config (inline, file, template, or sequence), with defaults generated from schema examples or fixtures
inject faults per tool or per call: latency, timeout, transport error, malformed JSON, schema-invalid response, AdCP error envelope with a chosen code, async task status sequences, and webhook delivery (including bad signatures)
record/replay: proxy to a real seller, record a cassette with credentials redacted, and replay it deterministically in CI
provide a pytest fixture (adcp_mock_seller) plus a CLI to run it standalone
Decision needed: where it lives
(a) Python-native, built on adcp.server + comply_test_controller machinery. The best fit for pytest users.
(b) Extend the JS mock-server with an AdCP-surface mode, and give Python a thin fixture that spawns it. One implementation to maintain, but it needs Node in the buyer's CI.
Either is acceptable. Pick whichever gets record/replay and fault injection to buyers soonest, and keep the fault/config format shared so the other SDK can adopt it later.
Prior art
adcp-test (third-party, Go) ships a config-driven mock seller with sequences, latency models, fault rates and a record-mode proxy. Worth borrowing the config ergonomics from. Note that its canned payloads don't follow AdCP schemas, which is why schema-validated responses are a hard requirement here.
Acceptance
A buyer test can: start the mock, script create_media_buy to return submitted then completed, inject a timeout on the next get_media_buy_delivery, and assert their client's retry/polling behavior. All of this runs offline.
A cassette recorded against the hosted test-agent replays byte-identically with credentials redacted.
Every mock response passes adcp.validation in strict mode for the configured AdCP version.
Classification: Feature request Bucket(s): client/testing (adcp.testing) — no exact bucket label in this repo; gap noted Status: ready-for-human Milestone: (omitted — no target version named)
What the experts said:
ad-tech-protocol-expert: Python-native option (a) is clearly correct — TestControllerStore, UpstreamRecorder, and WebhookDedupStore already provide most of the machinery; three protocol-level points must be nailed down: idempotency bypass on replay (mock must skip the IdempotencyStore on the replay path), webhook HMAC re-signing at emit time (not raw replay of recorded signatures), and task-ID injection via the existing force_create_media_buy_arm mechanism.
dx-expert: Builder pattern (MockSeller().on_create_media_buy(raises=...)) over SellerTestClient is the right fixture shape; four acceptance-criteria gaps: capabilities declaration, auth surface (accept-any vs require-token vs always-401), A2A task state sequences (not just terminal responses), and fixture URL exposure for AgentConfig.agent_uri in HTTP-bound mode.
adtech-product-expert: Epic-shaped — 4 natural sequential PRs (scripted responses → fault injection → record/replay → CLI); no cross-SDK config alignment needed in v1; implementation-defined cassette format is correct.
My take: All three experts converge strongly on Python-native option (a) — the existing TestControllerStore + build_asgi_app + UpstreamRecorder surface already covers most of the proposal. Two scoping questions need your call before coding starts, and the work should be tracked as an epic with sequential PRs rather than one large PR.
Transport mode: Should adcp_mock_seller run in-process (SellerTestClient, no port/auth middleware) or HTTP-bound (build_test_client, full auth stack exercised)? This determines the entire fixture API shape.
Cassette portability: Is Python↔JS cassette replay a goal for this milestone? Experts recommend implementation-defined format if not — cross-SDK alignment requires spec governance and would block delivery.
Activity
bokelley commentedon Sep 30, 2026
Triage
Classification: Feature request
Bucket(s): client/testing (adcp.testing) — no exact bucket label in this repo; gap noted
Status: ready-for-human
Milestone: (omitted — no target version named)
What the experts said:
TestControllerStore,UpstreamRecorder, andWebhookDedupStorealready provide most of the machinery; three protocol-level points must be nailed down: idempotency bypass on replay (mock must skip theIdempotencyStoreon the replay path), webhook HMAC re-signing at emit time (not raw replay of recorded signatures), and task-ID injection via the existingforce_create_media_buy_armmechanism.MockSeller().on_create_media_buy(raises=...)) overSellerTestClientis the right fixture shape; four acceptance-criteria gaps: capabilities declaration, auth surface (accept-any vs require-token vs always-401), A2A task state sequences (not just terminal responses), and fixture URL exposure forAgentConfig.agent_uriin HTTP-bound mode.My take: All three experts converge strongly on Python-native option (a) — the existing
TestControllerStore+build_asgi_app+UpstreamRecordersurface already covers most of the proposal. Two scoping questions need your call before coding starts, and the work should be tracked as an epic with sequential PRs rather than one large PR.Two questions for @bokelley:
adcp_mock_sellerrun in-process (SellerTestClient, no port/auth middleware) or HTTP-bound (build_test_client, full auth stack exercised)? This determines the entire fixture API shape.Triaged by Claude Code. Session: https://claude.ai/code/session_01VMfZqg2wga4oJ3FWqiMhff
Generated by Claude Code