Writing Tests

Once your project is configured with /twd:setup, you can start writing tests using the /twd skill. This is the core of the TWD + AI workflow — the agent writes tests, runs them against your real app, and iterates until they pass.

How It Works

The twd skill doesn't just generate test code — it also runs the tests with twd-cli, which drives a headless Chrome against your running dev server. Only the dev server has to be up; there is no tab for you to keep open.

1. Probes your dev server with one curl. If nothing answers, it tells you the dev command from .claude/twd-patterns.md and stops — it never asks you to open a tab.
2. Writes flow tests that follow your project patterns.
3. Runs the new file first, scoped with npx twd-cli run --test "<describe>".
4. Fixes failures one at a time, re-running only the failing test.
5. Checks your branch with npx twd-cli run --changed-since origin/main.
6. Closes with the full suite, npx twd-cli run, and reports.

The token usage stays low: every run writes a run report, and the agent reads its run.json — the outcome, each failed test with its error and mock diagnostics, and every retry. No screenshots, no DOM dumps, no scraping console output. A test that only passed on a retry is reported as a finding, not hidden in a green run. When the agent is done, it points you at the closing run's .twd/report/index.html to open in a browser.

When it's done, the agent offers to record the tests it wrote, so you can watch them instead of reading them:

npx twd-cli run --record --test "<test title>"

Want to watch the tests run live in your own browser while the agent works? That is opt-in with twd-relay.

Test-First Approach

We recommend running /twd before implementing a feature. Write the tests first, then build the implementation to make them pass. This gives you:

• A clear specification of what the feature should do
• Immediate feedback as you implement
• Confidence that the feature works when the tests go green

See It in Action

Here's a video showing the workflow — from writing tests to executing them:

What's Next

With tests in place, the next step is setting up CI so your tests run automatically on every push.

CI Setup →