# Write tests first, then implement

Have Claude Code write tests that describe a feature before any implementation, confirm they fail, then write code until they all pass.

Paste into: **Claude Code**, started in your project folder

## Prompt template

How the builder on the page fills in this template, so you can do the same:

- `{{key}}` becomes the text entered for that field, exactly as typed. Empty text, or text that is only whitespace (spaces, tabs or line breaks), counts as empty: a required field then becomes `[fill in: <label>]` with its label, and an optional field becomes nothing.
- For a choice field, `{{key}}` becomes the text of the chosen option, or of the default when none is chosen.
- Text between `{{#key}}` and `{{/key}}` stays only when that field is not empty; a choice field always counts as filled. The markers themselves are removed, and a marker that stands alone on its line takes its line break with it.
- Each value is inserted once, as it is: `{{…}}` inside a value stays as typed.

```text
Use test-driven development for this feature:
{{feature}}
{{#cases}}

The tests must cover at least:
{{cases}}
{{/cases}}

Work in this order:
1. Read the existing tests and match their framework, file layout and style.
2. Write the tests first. Do not write any implementation code yet. If the expected result for a case is not clear from my description, list those cases and ask me instead of choosing one.
3. Run them and show me that they fail for the expected reason, not because of a typo or a missing import.
4. Write the smallest implementation that makes the tests pass.
5. Run the full relevant test suite{{#command}} with: {{command}}{{/command}}. Keep going until it passes.

Mocks: {{mocks}}.
Do not change or delete a test just to make it pass. If you think a test is wrong, stop and explain why before changing it.

Finish with the final test output and a short list of the tests and code you added.
```

## Fields

- `{{feature}}` (required): Feature or behavior to build.
- `{{cases}}`: Cases the tests must cover. Optional. Concrete inputs and expected results, especially the ones that are easy to forget.
- `{{command}}`: Test command. Optional. Leave empty and Claude will find how the project runs its tests.
- `{{mocks}}`: Mocks. Choose one:
  - Avoid mocks where a real implementation or a simple fake works (default)
  - Mocks are fine where they keep the tests fast

This site doesn't run Claude or show model output. Results depend on your input and the model you use.

## When to use this template

- You can state what the feature must do in concrete cases, and you want those cases written down as tests before the code takes shape.
- The behavior has edge cases that are easy to get subtly wrong, such as expiry times, limits, permissions or repeated requests.
- You want Claude to have a clear finish line: the work is done when the agreed tests pass, not when the code looks complete.

## When not to use it

- You are still exploring what the feature should do. Writing tests for requirements you have not settled locks in guesses; run a spec interview first.
- The work is mostly visual, such as layout or styling. Unit tests say little there; compare screenshots against the design instead.
- The code is existing and untested and you only want coverage for it. Use the unit test template, which covers code that already exists.

## Why this structure

- Tests come before implementation, as a separate numbered step with an explicit "do not write any implementation code yet". This keeps the tests describing the requirement rather than whatever the first implementation happens to do.
- Step 3 asks Claude to run the new tests and show that they fail for the expected reason. A test that fails because of a typo, or passes before any code exists, proves nothing.
- Step 1 points Claude at the existing tests, so the new ones use the same framework, file layout and helpers instead of a second testing style.
- The rule against changing a test to make it pass protects the agreement you made in step 2. If a test is wrong, you hear about it and decide.
- The full test suite run in step 5, with your command when you give one, gives Claude a pass or fail signal to iterate against and catches breakage elsewhere.
- The mocks setting is explicit because it changes what the tests prove. Fewer mocks means tests that exercise more of the real code.

## Example input (fictional)

Feature or behavior to build:

```
The password reset flow: a user requests a reset link, the link works once, and it expires after 30 minutes.
```

Cases the tests must cover:

```
An expired link is rejected. A used link cannot be used again. Requesting a link for an unknown address shows the same message as for a known one.
```

Test command:

```
npm test -- auth
```

Mocks:

```
Avoid mocks where a real implementation or a simple fake works
```

## Follow-ups to send Claude

- Show me the tests before you implement anything. I want to review the cases first.
- Add a test for two reset requests in a row: only the newest link should work. Then make it pass.
- Which parts of the implementation are not covered by any of the new tests?

## Common mistakes

- Letting implementation and tests be written in the same step. The tests then tend to confirm the implementation instead of the requirement.
- Accepting failing tests without reading why they fail. The expected reason is "the feature does not exist yet", not an import error.
- Describing the feature in general words only. Two or three concrete cases with expected results do more to pin down behavior than a paragraph of description.

## Related templates

- [Write unit tests](https://awesomeclaudeprompts.com/prompts/write-unit-tests/): Get unit tests for a function or module in your framework, covering normal cases, edge cases and errors, with each test explained.
- [Write a spec by interview](https://awesomeclaudeprompts.com/prompts/spec-by-interview/): Let Claude Code interview you about a feature, covering implementation, UX, edge cases and tradeoffs, then write a self-contained spec to a file.
- [Build something new from an existing pattern](https://awesomeclaudeprompts.com/prompts/follow-code-pattern/): Point Claude Code at code that already works the way you want, so the new feature matches its structure, naming, tests and error handling.

## Sources

- [Claude Code docs: Prompt library](https://code.claude.com/docs/en/prompt-library) (Anthropic documentation)
- [Claude Code best practices: Give Claude a way to verify its work](https://code.claude.com/docs/en/best-practices#give-claude-a-way-to-verify-its-work) (Anthropic documentation)
- [Claude Code docs: Common workflows, work with tests](https://code.claude.com/docs/en/common-workflows#work-with-tests) (Anthropic documentation)

---

Awesome Claude Prompts is an independent project. It is not affiliated with, endorsed by, or sponsored by Anthropic. Claude is a trademark of Anthropic, PBC.