Writing and running tests with Claude Code

What an automated test is

An automated test is a small program that checks your main program. Example: "When I add a task titled 'Buy milk', the open-task count goes up by one." If a future change breaks that behaviour, the test fails and you find out before a user does.

Tests are not about distrusting the agent. They are about distrusting complexity. Every new feature can quietly break an old one. Tests act as guardrails inside your codebase, the same way Shield acts as guardrails around it.

Ask Claude Code to add tests

Claude Code can pick a runner, install it, write tests, and wire it into npm test in one go. From inside your project session:

Read the proposed plan. Approve each step. When it asks to install packages, glance at the names (you should see vitest and maybe @testing-library/something). Approve.

Run them in the same terminal

You never left the terminal, so there is nothing new to open. From your project root:

npm test

Reading the output

• Green or the word PASS means the checks succeeded.
• Red or FAIL means at least one check broke. The first failing test usually prints a short diff between expected and actual values, plus the file and line where the assertion ran.

If npm test prints npm error Missing script: "test", open package.json and look at the scripts block. Claude probably named the script differently. Run the exact command from the README it wrote, or ask:

Show me the test command you actually wired up, and update the README so it matches.

Run tests as part of your loop

Make this a habit, not a special occasion:

1. Ask Claude for a change.
2. Read the diff. Approve.
3. Run npm test.
4. If green, commit. If red, paste the failing output back into Claude and ask "fix this without changing what the test asserts."

That fourth step is where the agent earns its keep. Failed tests are a precise description of what went wrong, and Claude is good at reading that signal.

When a test fails right after a change

It can be hard to tell whether the code is wrong or the test is wrong. Ask:

The test "deletes a task" failed after the last change. Read the test and the code it covers. Tell me whether the test or the implementation is wrong, and explain why.

Then make the call yourself. The agent gives you the analysis; you decide what to fix.

Good habits

• Run tests before you declare a feature done.
• Keep test names plain English. "deletes a completed task from the list" beats "test_handler_2".
• When you fix a real bug, ask Claude to add a test that fails before the fix and passes after. That is how a one-time bug becomes a permanent guardrail.

What is next

You now have a local app you can change with words, edit with confidence, extend with MCP tools, and check with tests. The last lesson zooms out: what you actually built, and how Course 3 picks up from here.

Next: You have a working local app