---
title: "Design reproducible scenarios"
description: "Seed linked identities, version fixtures and keep a stable baseline for retests."
canonical: "https://agenttwin.si/docs/scenarios/"
---

# Design reproducible scenarios

Seed linked identities, version fixtures and keep a stable baseline for retests.


## World versus scenario

The world specification defines executable files, command, services, faults and checks. A scenario supplies versioned starting records for those services. The scenario does not replace the application's code or prove provider fidelity.

Use a named scenario when several tests need the same customer, order or channel identities. Choose synthetic data that captures the failure conditions. The same identifier alone is not enough: record the relationship and validate that each selector resolves to one record.

## Complete linked fixture

```json
{
  "schema": "agenttwin/scenario-v1",
  "id": "support_customer",
  "version": 1,
  "description": "One synthetic customer linked to a support channel",
  "services": [
    {"name": "crm", "adapter": "json-collection", "collections": [
      {"path": "/customers", "seed": [{"id": "customer_1", "channel": "C_TEST"}]}
    ]},
    {"name": "slack", "adapter": "slack", "collections": [
      {"path": "/channels", "seed": [{"id": "C_TEST", "name": "support"}]},
      {"path": "/messages", "seed": []}
    ]}
  ],
  "entities": [{
    "id": "customer_1",
    "refs": [
      {"service": "crm", "path": "/customers", "where": {"id": "customer_1"}},
      {"service": "slack", "path": "/channels", "where": {"id": "C_TEST"}}
    ]
  }]
}
```

The world using this scenario must declare the same services, adapter types and collection paths. Entity references must cover at least two services; zero or multiple matching records are invalid. The shared entity is a validated seed relationship, not automatic ongoing synchronization between unrelated adapters.

## Store and reuse

```sh
npx agenttwin scenario save --file support.scenario.json --json
npx agenttwin scenario list --json
npx agenttwin scenario show --scenario support_customer@1 --json
npx agenttwin run --file agenttwin.world.json --scenario support_customer@1 --json
```

Saving the same version with identical content is repeatable. Saving changed content under that version fails. Increment `version` when changing seeds, then create a new world for the new baseline. Stored scenarios live under `.agenttwin/scenarios/`; keep the source JSON in version control if the team needs to recreate them elsewhere.

## Choose useful test data

Start with the smallest fixture that reproduces the incident: one affected identity, the relevant existing records and explicit empty collections for expected new effects. Include boundary conditions deliberately, such as a duplicate key or an existing notification. More synthetic records do not automatically mean better coverage.

For a source-fix comparison, keep the same scenario ID, version and digest. For a new business requirement, version the fixture and explain why checks changed. Receipts preserve scenario provenance so these two kinds of comparison can be distinguished.

Automatic production-data import, consistent redaction and live cross-service mutation propagation remain additional work. Current fixtures are reviewed files. See [reusable worlds](/docs/worlds/) for reset and expiry behavior.