How to reset a multi-service test environment between runs

Keep each test run isolated by capturing a known starting state, applying it before every run, and asserting the final state instead of trusting the sequence. AgentTwin's CLI can replay a captured failure with the original seed and unchanged checks, which is the practical form of resetting state between runs for a multi-service workflow.

Reset the environment before each run

The reliable pattern has four parts:

1. Declare the starting state once. Put the seed records for every service in a world or scenario fixture instead of ad-hoc setup code that drifts between tests.
2. Apply that fixture before every run. A clean plan re-applies the seed set; nothing important is carried over from the previous test.
3. Capture the run. Record the service events, final state and assertion results. The receipt is what proves the reset happened.
4. Replay to verify. Re-run the captured receipt. If the reproduction has the same events, final state and check results, the fixture defines the starting point rather than the previous test's leftovers.

Why not reset by hand

Rolling back by hand means remembering which records were created, which messages were sent and which external IDs were assigned. A missing undo silently changes the next result. A declared starting state makes every run start from the same inputs whether the previous run passed or failed.

A run executed for this article

The synthetic reference ships with a support workflow that writes a ticket and sends a message.

npx agenttwin example --out ./ex
npx agenttwin run --file ./ex/agenttwin.world.json

The clean run passed. Running the same world with --fault timeout-after-write exited 1 and left two tickets instead of one. Replaying that receipt reopened the recorded state and reproduced the same events, final state and checks. Replaying is a test of the starting state; it is not a factory reset of your machine.

To restore a saved world to its declared starting records before the next run, use the world lifecycle commands:

npx agenttwin world reset --id WORLD_ID
npx agenttwin world run --id WORLD_ID

Tradeoffs

• Time to reset grows with the size of the fixture. Prefer a small declared starting state over serialising an entire database.
• A service that reads state written by another service still needs that write in the starting fixture, or the reset leaves the workflow in an unexpected condition.
• Local execution runs as a process on your machine and can reach the host filesystem and network. Reset here means the test's own starting state, not a security boundary or a promise that external systems are untouched.

See the CLI reference for reset and replay commands and the world lifecycle guide for reusing a prepared world.