Get Test-Ready

​

The three surfaces the runner needs

​

Step 1 — Declare capabilities honestly

{
  "supported_protocols": ["media_buy", "creative"],
  "specialisms": ["sales-guaranteed"],
  "media_buy": {
    "supports_proposals": true
  },
  "account": {
    "sandbox": true,
    "require_operator_auth": false
  }
}

• supported_protocols — Pulls in the matching protocol storyboards from /compliance/{version}/protocols/.
• specialisms — Pulls in opt-in specialism storyboards (see the Compliance Catalog for the full enumeration).
• account.sandbox: true — Signals that you honor sandbox semantics (no real spend, no production side effects).
• account.require_operator_auth — Determines your sandbox bootstrap path (step 2).

​

Step 2 — Pick your sandbox bootstrap path

​

Step 3 — Implement the compliance test controller

​

Wiring the SDK scaffold

npm install @adcp/sdk

import { createComplyController, TestControllerError } from '@adcp/sdk/testing';
// `server` is your AdcpServer or MCP server instance — see `createAdcpServer` in
// `@adcp/sdk/server` if you need a reference setup.

const controller = createComplyController({
  seed: {
    product: async ({ product_id, fixture }) => {
      await productRepo.upsert(product_id, fixture);
    },
    creative: async ({ creative_id, fixture }) => {
      await creativeRepo.upsert(creative_id, fixture);
    },
    // Add pricing_option, plan, media_buy as your claimed storyboards require.
  },

  force: {
    creative_status: async ({ creative_id, status, rejection_reason }) => {
      const previous = await creativeRepo.getStatus(creative_id);
      if (previous == null) {
        throw new TestControllerError('NOT_FOUND', `creative ${creative_id} not found`);
      }
      const result = await creativeRepo.transition(creative_id, status, rejection_reason);
      if (result.kind === 'invalid_transition') {
        throw new TestControllerError('INVALID_TRANSITION', result.message, previous);
      }
      return { success: true, previous_state: previous, current_state: result.status };
    },
    // Add account_status, media_buy_status, session_status as needed.
  },

  // simulate: { delivery, budget_spend } — add if you claim reporting/budget specialisms.
});

// Primary gate: register the tool only in sandbox deployments, so it never
// appears in production `tools/list`.
if (process.env.ADCP_SANDBOX === '1') {
  controller.register(server);
}

• Tool registration and schema. controller.toolDefinition stays in sync with the published spec version.
• Dispatch and UNKNOWN_SCENARIO. Scenarios you do not register return UNKNOWN_SCENARIO automatically — never a schema error.
• Param validation. Invalid params produce INVALID_PARAMS with a readable error_detail without reaching your adapter.
• Seed idempotency. Calling seed_product twice with the same product_id and an equivalent fixture returns previous_state: "existing"; a divergent fixture returns INVALID_PARAMS. Your adapter is only invoked on the first seed.
• Typed error envelopes. Throw TestControllerError(code, message, currentState?) with code from the controller error-code table. Common adapter codes are 'INVALID_TRANSITION' | 'NOT_FOUND' | 'FORBIDDEN' | 'INVALID_PARAMS'; digest-mode query_upstream_traffic implementations may also return JCS_NON_FINITE_NUMBER when RFC 8785/JCS canonicalization encounters a non-finite numeric value.

​

Two layers of sandbox gating

1. Registration gate (primary). Wrap controller.register(server) in an environment check. This is what keeps comply_test_controller out of production tools/list entirely. Without it, a leaked sandbox credential on a production endpoint exposes seller-side state-forcing.
2. Per-request gate (defense-in-depth). Pass a sandboxGate: (input) => boolean to createComplyController. The scaffold calls it on every request and returns FORBIDDEN when it returns false. Use this on shared-process deployments where the tool IS registered but some requests might still reference a production account.

sandboxGate: async (input) => {
  const params = input.params as { account_id?: string; media_buy_id?: string } | undefined;
  const accountRef = params?.account_id
    ?? (params?.media_buy_id && await mediaBuyRepo.getAccountId(params.media_buy_id));
  return typeof accountRef === 'string' && await accountRepo.isSandbox(accountRef);
}

​

Step 4 — Run the storyboard runner

npx @adcp/sdk@latest --save-auth my-agent http://localhost:3001/mcp
npx @adcp/sdk@latest storyboard run my-agent

​

Avoiding the teach-to-test trap

1. Implement seed scenarios generically. seed_product accepts any product_id and persists a product with that ID in your sandbox data layer. Your adapter is a thin wrapper over a real upsert against your sandbox store.
2. The fixture object is the contract, the ID is not. Storyboard authors set fixture to the minimum shape the test needs. Everything beyond that — discovery, filtering, authorization — is your normal code path, exercised on fixture-seeded data the same way it runs on production data.

​

Readiness checklist

• get_adcp_capabilities returns only protocols and specialisms you actually implement
• account.sandbox: true is declared and honored — sandbox requests produce no real spend, no production platform calls, no persisted production state
• sync_accounts (implicit) or list_accounts (explicit) handles sandbox requests per step 2
• comply_test_controller is absent from tools/list on any production endpoint
• Requests that reference a non-sandbox account are rejected with FORBIDDEN
• Every seed scenario your claimed storyboards depend on persists fixtures generically, with no ID special-cases
• Every force scenario uses the same state-transition rules as production, returning typed errors on invalid transitions
• A full storyboard sweep still passes when fixture IDs are swapped for random UUIDs

​

What’s next

• Validate Your Agent — CLI, Addie workflows, and multi-instance verification
• Compliance test controller reference — Full scenario-by-scenario spec
• Sandbox mode — The two account model paths in depth
• Conformance — What “conformant” and “verified” mean once your runs pass