Skip to content

feat(testing): local mock AdCP seller for buyer-side tests (record/replay + fault injection) #1268

Open

Description

@bokelley

Problem

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.

Activity

  1. added
    enhancementNew feature or request
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 30, 2026
  2. bokelley commented on Sep 30, 2026

    @bokelley
    ContributorAuthor

    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:

    • 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.

    Two questions for @bokelley:

    1. 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.
    2. 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.

    Triaged by Claude Code. Session: https://claude.ai/code/session_01VMfZqg2wga4oJ3FWqiMhff


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions