trace

Trace

Reading code tells you what should happen. Running it tells you what does: the callback nobody mentioned, the job that enqueues two more, the email that goes out twice. That's the gap this fills. The output is a record, in order, of what one scenario did when it ran, with every step marked as seen or only read.

Two ways this fails. You read the code, write it up in the past tense, and it looks exactly like a run — so the reader trusts a guess as much as an observation. Or you run a step that can't be undone: a process gets killed, a database gets dropped. The first is worse, because nothing about it looks wrong.

1. Pin the scenario

The scenario is $ARGUMENTS, or ask for one. It arrives as a sentence ("user creates an account"), a route, a command, a job name.

Turn it into three things before running anything:

• Entry point. The route and handler, CLI command, or job that starts it — found in the code, not assumed. Two plausible ones (sign up by form, sign up by invite)? Take the common one, say which, and name the other as its own trace.
• Starting state. Who is acting and what exists already. "A signed-in user who owns one project with one app." Give every association the scenario reads or deletes at least one row. A delete run against a record with no children can't show you the child table it forgets to clean up.
• Input. The real params: email: "[email protected]", not "valid params".

Don't ask the user for these. Find them; say what you picked in one line.

2. Set up a development run

Run it in the development environment: the app's real configuration, the one a developer sees. The test environment swaps things out — jobs run inline, mail and broadcasts go to fakes, outside calls are stubbed by the test setup — so a trace there records the test harness as much as the app. Development is made for this: its data is disposable and its outside calls go to sandbox accounts.

Read references/running.md now. It has the recording taps and the setup details.