Vibe coding with Claude Code course Β· Module 11: Spotify clone

Tests as a Handrail: Claude Is Done When They Pass

11 min read
In this lesson10

Ahoy! Sea Shanty Sounds plays, has playlists and a search, and the project holds more than twenty tests from lessons 10_1 to 10_3. Each of them exists because you added a done criterion to the request. Tomorrow you will ask for a small thing, forget the criterion, and Claude will stop when the code looks finished. In this lesson tests stop being something you remember to put into a request and become a handrail that Claude holds on to with every change.

What you will learn

  • write into CLAUDE.md the commands Claude uses to check its own work;
  • tell a behavior test from a test that peeks into how the code is built;
  • break the code on purpose to check that a test guards anything at all;
  • spot a weakened test and a test that checks nothing in a diff;
  • pick the level of rigor: a criterion in the request, /goal, a Stop hook, a fresh reviewer and /verify at the end.

The most valuable line of CLAUDE.md

Claude Code best practices say it plainly: if the project has something that answers "pass" or "fail", the most valuable line in CLAUDE.md is the command that runs it. Sea Shanty Sounds has four such checks: tests, lint, types and build. Written in CLAUDE.md, they reach every session, tomorrow's too, without you reminding anyone.

Request for Claude Code:

Add a "Check commands" section to @CLAUDE.md: tests in a single run,
lint, types and build, each on its own line. Below them a sentence
saying the work is done when all of them pass and that I want to see
the commands with their results. In the pitfalls add a ban on changing
test files without my consent. Run every command and show the result.

The request names the file, says what has to be in it, and demands proof, not a promise.

What Claude wrote: commands in CLAUDE.md

Open CLAUDE.md in Cursor. Below the @AGENTS.md import there are two short sections:

# Check commands
- Tests: npm run test -- --run (Vitest, a single run without watch mode)
- Lint: npm run lint
- Types: npx tsc --noEmit
- Build: npm run build
The work is done when all four pass. Show the commands and their results.

# Pitfalls
- A failing test is fixed in the code. Do not change *.test.ts and *.test.tsx files without my consent.

You know the --run flag from lesson 4_1: it turns off watch mode, so the command ends by itself and Claude can read the result. For us the tests reported Test Files 7 passed (7) and Tests 22 passed (22), and lint, types and build passed with no errors. Remember from lesson 1_7 that CLAUDE.md is a request, not a lock: the model almost always follows it, but it gives no guarantee.

Test the behavior, not the details

Not every green test is a handrail. Testing Library, which the component tests in the project use, rests on a simple principle: the more a test resembles the way a person uses the app, the more confidence it gives. A behavior test clicks what a pirate clicks and checks what a pirate sees. A details test peeks into how the code is built: it counts list elements, checks classes or whether an internal function was called.

Request for Claude Code:

In components/Queue.test.tsx write a behavior test of the queue:
a click on Remove next to "Island Shanty" removes exactly that track,
"Battle Drums" stay on the list, and what is playing does not change.
Find elements by role and name, like in @components/MusicPlayer.test.tsx.

Open components/Queue.test.tsx. The most important part of the test looks like this:

render(<MusicPlayer tracks={tracks} />);
fireEvent.click(screen.getByRole("button", { name: "Remove Island Shanty from queue" }));
expect(screen.queryByRole("button", { name: "Remove Island Shanty from queue" })).toBeNull();
expect(screen.getByRole("button", { name: "Remove Battle Drums from queue" })).toBeTruthy();
expect(screen.getByText("Pirate Hymn, Captain Redbeard")).toBeTruthy();

The test imports render, screen and fireEvent from @testing-library/react. They work thanks to the set from lesson 4_1: Vitest, the @vitejs/plugin-react plugin that understands JSX, and jsdom, a pretend browser switched on in vitest.config.mts by environment: "jsdom". render draws the player in that browser and fireEvent.click simulates the click of a pirate. getByRole looks for a button by the role and name that a screen reader would read aloud, that is by the aria-label from the queue of lesson 10_1. queryByRole returns null when the button is missing, while getByRole throws an error in that situation, which is why the first one is used to check absence. The test knows nothing about useState or filter, so it survives every rebuild of the code that does not change the behavior.

An agent likes to write a shorter version: expect(container.querySelectorAll("ol > li")).toHaveLength(2). We checked both versions on a bug where Remove always removes the first track of the Up next list. The version with counting passed, because two elements were left, just not the right ones. The behavior test failed with AssertionError: expected <button type="button" …(2)></button> to be null, and lint reported only a warning about an unused id.

Break the code on purpose

A test you have never seen red may have guarded nothing. The check of a check is simple: break the code for a moment and watch whether the test raises the alarm.

Break formatTime in @lib/format.ts for a moment: return seconds
without padStart. Run the tests and show the result. Then restore
the code and run the tests once more.

For us the result with the broken function contained these lines:

 FAIL  lib/format.test.ts > formatTime > formats minutes and seconds
AssertionError: expected '2:5' to be '2:05' // Object.is equality
      Tests  2 failed | 21 passed (23)

Two formatter tests failed, because they expect "2:05" and got "2:5". After the code was restored all 23 passed again. Such a break is a change made with Claude's editing tool, so if anything went wrong you would undo it with /rewind from lesson 0_6.

Two agent mistakes visible in the diff

The first is a weakened test. An agent that wants a green result changes the expectation instead of the code. This is the diff after which the broken formatter passed all 23 tests:

-    expect(formatTime(125)).toBe("2:05");
+    expect(formatTime(125)).toMatch(/^\d+:\d+$/);
     expect(formatTime(59)).toBe("0:59");
-    expect(formatTime(60)).toBe("1:00");
+    expect(formatTime(60)).toMatch(/^\d+:\d+$/);

The regular expression /^\d+:\d+$/ checks only the shape: digits, a colon, digits. The string "2:5" satisfies it too, so the test stopped guarding the leading zero. The agent did the same with the line for 3600 and with the fractions test.

The second is a test that checks nothing. Both cases below passed for us with the broken formatter:

it("formats the track time", () => {
  expect(formatTime(125)).toBeTruthy();
});
it("formats a long track", () => {
  formatTime(3600);
});

toBeTruthy lets through every non-empty string, and the second test has no expect at all. For that second case Vitest has a setting: according to the documentation expect.requireAssertions works as if every test started by checking that it will run at least one assertion. Claude added one line to vitest.config.mts:

  test: {
    environment: "jsdom",
    expect: { requireAssertions: true },
  },

The empty test then failed with Error: expected any number of assertion, but got none, and the test with toBeTruthy still passed. The setting catches a test without assertions, but an assertion that is too weak only you will see. That is why after every turn you look into Source Control: a change in a .test.ts or .test.tsx file that you did not ask for is a signal to stop and ask why.

Levels of rigor

Best practices list four levels of making sure the work is finished, from the loosest to one enforced by the program itself.

  1. A criterion in the request, like "Done when" from lesson 10_1. Claude decides on its own when it is satisfied.
  2. /goal sets a completion condition. After every turn a separate model checks it against the conversation, and Claude keeps working until the condition is met. That model does not run commands or read files, so the condition must be readable from the results Claude shows. The documentation advises adding a constraint, for example that other test files do not change, and a turn limit.
  3. The Stop hook from location 7: a command that Claude Code runs on every attempt to end a turn. Exit code 2 sends Claude back to work, and the text from the error output reaches it as the reason.
  4. A reviewer who did not write the code: /code-review from lesson 2_9 reads the diff in a fresh subagent that did not see your conversation.

You type the condition for /goal in one line:

/goal npm run test -- --run ends with no failures, npm run lint and npx tsc --noEmit pass, and git diff --stat shows no changes in .test.ts or .test.tsx files; or stop after 15 turns

Setting a goal starts a turn right away, and /goal clear removes it. A goal does not change the permission mode: in Manual mode Claude still asks about commands you have no rule for. The documentation honestly adds that in a session you are watching it is rarely needed; it pays off in long work without you.

You add the Stop hook to .claude/settings.json in the shape you know from location 7:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "npm run test -- --run 1>&2 || exit 2" }] }
    ]
  }
}

1>&2 sends the test output to the error output so that Claude sees it, and || exit 2 ends the command with code 2 when the tests fail. For us this command ended with code 0 on green tests and with code 2 on the broken formatter, with the failures on the error output. According to the documentation, after eight such blocks in a row Claude Code ends the turn anyway. Remember the cost: the tests will run after every turn, also after an answer to a plain question. For everyday work I recommend commands in CLAUDE.md and a criterion in the request, /goal for long work without supervision, a hook when green tests must be law without exceptions, and /code-review before a commit.

/verify: the app, not just the tests

Tests check functions and components in a pretend browser. According to the documentation the built-in /verify skill makes Claude build and run the app and then look at the result, and it catches what tests and types do not see. You run it yourself when Claude reports the work finished. It works with no configuration: it guesses how to start the app from package.json and the README. When it had to work that out, it saves the recipe in .claude/skills/verify/SKILL.md. The project then has its own skill named verify, and the documentation says that a session that starts with such a skill gets an instruction in its commit guidance to run it before every commit, except for changes to documentation or tests only. On its own Claude does not run the built-in /verify before a commit.

One limit at the end. The Next.js documentation says that Vitest does not yet support async Server Components, and recommends E2E tests in a browser for them. Jest stands in that documentation next to Vitest as an equal option; from lesson 4_1 the course sticks to Vitest.

Captain's review

  1. The commands work. In Claude's answer you see the four commands from CLAUDE.md and their results, not the sentence "everything passes".
  2. The test diff. Every change in .test.ts and .test.tsx files is a change you asked for. A typical agent mistake is an expectation loosened so that broken code passes.
  3. Red at least once. You saw every new test red after breaking the code on purpose.
  4. Role and name. Component tests look for elements the way a pirate does, not by the number of elements or by classes.

Next step

Ask for a commit, for example "Check commands in CLAUDE.md and the queue test". Then a small step in the same loop: "Add a behavior test: the Shuffle button does not change the track that is playing. Show it red after breaking shuffled on purpose, then green". In the editor below a small test deck with formatTime is waiting: break the function, switch on the agent mistake with a weakened test and compare the result with what the diff shows.

Remember: a handrail holds only when nobody has quietly unscrewed it, and green tests count only together with the diff of the test files.

Code for this lesson: App.jsx
// Test deck: formatTime, Vitest tests in miniature and two agent mistakes
import { useState } from 'react';

function formatTimeGood(seconds) {
  if (!Number.isFinite(seconds) || seconds < 0) return '0:00';
  const whole = Math.floor(seconds);
  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, '0')}`;
}

// Broken version: seconds without padStart
function formatTimeBroken(seconds) {
  if (!Number.isFinite(seconds) || seconds < 0) return '0:00';
  const whole = Math.floor(seconds);
  return `${Math.floor(whole / 60)}:${whole % 60}`;
}

const SHAPE = /^\d+:\d+$/;

// Every test: name, input, expectation (toBe) or weakened (toMatch)
const CASES = [
  { name: 'formats 125 seconds', input: 125, expected: '2:05', weakened: true },
  { name: 'formats 59 seconds', input: 59, expected: '0:59', weakened: false },
  { name: 'formats a full minute', input: 60, expected: '1:00', weakened: true },
  { name: 'formats an hour', input: 3600, expected: '60:00', weakened: true },
  { name: 'unknown length gives 0:00', input: NaN, expected: '0:00', weakened: false },
];

function runCase(c, fn, weaken) {
  const value = fn(c.input);
  if (weaken && c.weakened) {
    return { pass: SHAPE.test(value), detail: `toMatch(/^\\d+:\\d+$/) got "${value}"` };
  }
  const pass = value === c.expected;
  return { pass, detail: pass ? `toBe("${c.expected}")` : `expected '${value}' to be '${c.expected}'` };
}

export default function App() {
  const [broken, setBroken] = useState(false);
  const [weaken, setWeaken] = useState(false);
  const [emptyTest, setEmptyTest] = useState(false);
  const [requireAssertions, setRequireAssertions] = useState(false);
  const [result, setResult] = useState(null);

  function runTests() {
    const fn = broken ? formatTimeBroken : formatTimeGood;
    const rows = CASES.map((c) => ({ name: c.name, ...runCase(c, fn, weaken) }));
    if (emptyTest) {
      // A test without expect: it passes unless you turn on requireAssertions
      rows.push({
        name: 'formats a long track (no expect)',
        pass: !requireAssertions,
        detail: requireAssertions ? 'expected any number of assertion, but got none' : 'no assertions, nothing was checked',
      });
    }
    setResult(rows);
  }

  const failed = result ? result.filter((r) => !r.pass).length : 0;
  const testsChanged = weaken || emptyTest;

  return (
    <div className="min-h-screen bg-gray-950 p-4 text-white">
      <div className="mx-auto max-w-xl space-y-4">
        <h1 className="text-lg font-semibold">Test deck: formatTime</h1>

        <div className="space-y-1 rounded-xl bg-gray-900 p-3 text-sm">
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={broken} onChange={(e) => setBroken(e.target.checked)} />
            Break formatTime on purpose (no padStart)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={weaken} onChange={(e) => setWeaken(e.target.checked)} />
            Agent mistake: a weakened test (toBe replaced with toMatch)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={emptyTest} onChange={(e) => setEmptyTest(e.target.checked)} />
            Agent mistake: a test with no expect at all
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={requireAssertions} onChange={(e) => setRequireAssertions(e.target.checked)} />
            vitest.config.mts: expect.requireAssertions = true
          </label>
        </div>

        <button type="button" onClick={runTests} className="rounded-full bg-white px-4 py-2 font-semibold text-black">
          npm run test -- --run
        </button>

        {result && (
          <div className="rounded-xl bg-black p-3 font-mono text-xs">
            {result.map((r) => (
              <p key={r.name} className={r.pass ? 'text-green-400' : 'text-red-400'}>
                {r.pass ? 'βœ“' : 'Γ—'} {r.name}: {r.detail}
              </p>
            ))}
            <p className="mt-2 text-gray-300">
              Tests {failed > 0 ? `${failed} failed | ` : ''}{result.length - failed} passed ({result.length})
            </p>
          </div>
        )}

        <div className="rounded-xl bg-gray-900 p-3 text-sm">
          <p className="text-gray-400">Source Control: changed files</p>
          {broken && <p>M lib/format.ts</p>}
          {testsChanged ? <p className="text-amber-400">M lib/format.test.ts</p> : null}
          {!broken && !testsChanged && <p className="text-gray-500">No changes.</p>}
          {weaken && (
            <pre className="mt-2 overflow-x-auto text-xs">
              <span className="text-red-400">{'-    expect(formatTime(125)).toBe("2:05");'}</span>{'\n'}
              <span className="text-green-400">{'+    expect(formatTime(125)).toMatch(/^\\d+:\\d+$/);'}</span>
            </pre>
          )}
        </div>

        {result && failed === 0 && broken && (
          <p className="rounded-xl bg-red-900 p-3 text-sm font-semibold">
            The code is broken and the tests are green. Someone unscrewed the handrail: read the diff of the test file.
          </p>
        )}
        {result && failed === 0 && !broken && testsChanged && (
          <p className="rounded-xl bg-amber-900 p-3 text-sm">
            Green, but the test file changed. Break formatTime and check whether the test still guards anything.
          </p>
        )}
        {result && failed > 0 && (
          <p className="rounded-xl bg-gray-800 p-3 text-sm">Red: the handrail holds. Fix the code, not the test.</p>
        )}
      </div>
    </div>
  );
}

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. What does a Next.js project need for Vitest to run a component test, such as the queue test?

  2. 2. What does fireEvent.click(...) do in the queue test?

Hands-on tasks in the game

  • Click in order

    Click the elements to build the import of the tools the queue test uses:

  • Vertical ordering

    Order the steps of a behavior test that checks the Remove button in the queue:

  1. QuestionTest kit for components
  2. QuestionThe fireEvent.click function
  3. Click in orderBuild the testing-library import
  4. Put in orderQueue test steps

Useful articles