Building Test Scenarios with Claude Code (Claude CLI)

What determines the quality of development delegated to an AI agent is not so much its ability to generate code as the "verification mechanism" in place. Based on research into official and practical English-language blogs, this article explains how to build test scenarios with Claude Code (Claude CLI).

This article summarizes, in English, the key points of English-language official documentation and technical blogs that we researched. The source for each technique is listed in the "References" section at the end of the article. Please be sure to check the original articles for full details.

The core: "a verification loop Claude can run on its own"

The top principle Anthropic emphasizes officially is to "give Claude a way to verify its work." Verification refers to "anything that returns a signal Claude can read within the conversation — test suites, build exit codes, linters, scripts that compare output against expected values, screenshots compared against a design." Claude "works, runs checks, reads the results, and iterates until they pass" (Source 1).

For this reason, it is effective to include concrete test cases in your prompt. For example, rather than "implement an email validation function," write something like the following.

Write a validateEmail function. Example test cases: user@example.com → true, invalid → false, user@.com → false. Run the tests after implementing it.

Enforce TDD "explicitly"

Left to its own devices, Claude tends to write the implementation first. So explicitly instruct it to follow the RED → GREEN → REFACTOR order. The Shipyard blog states that "the process of writing tests before writing the feature produces higher-quality results," and recommends having Claude write E2E tests with Cypress or Playwright (Source 4).

alexop.dev introduces a "TDD skill" that separates each phase into a subagent and structurally prevents skipped steps with blocking instructions such as "do not proceed to the GREEN phase until you have confirmed the test fails." The test-authoring agent is required to ensure that "the test must fail when run — confirm this before returning" (Source 5).

Unit tests alone are not enough — E2E verification

Anthropic's engineering blog clearly points out an easily overlooked failure mode: "Claude would make code changes and even verify with unit tests or curl, yet fail to recognize that the feature did not work end to end."

The solution is to give it a browser automation tool. When the agent was set up to test the app by operating it like a real user, they report that "it became able to identify and fix bugs that cannot be seen from the code alone, dramatically improving performance." They also describe a technique where, at the start of each session, the development server is started and an initial health check (send a chat and check whether a response comes back) is run to detect a broken state (Source 2).

Long-running autonomous execution: state files and retry limits

When running many scenarios autonomously, use a state file to track the result of each test. In Nathan Onn's "Ralph Loop," a status.json records the state of each test case (pending / pass / fail / knownIssue) and the number of fix attempts, serving as Claude's persistent memory. The loop proceeds as "select a test → run it in the browser → move on if it passes, fix and re-test if it fails," and fixes are capped at three attempts; beyond that the case is marked known_issue to prevent infinite loops. Completion is only declared via an explicit signal such as <promise>ALL_TESTS_RESOLVED</promise> (Source 3).

Separate the grader from the implementer

A classic way to raise quality is "not letting the agent that wrote the code grade its own work." Have a verification subagent, or a separate session with fresh context (the Writer/Reviewer pattern), challenge the results to catch overfitting to the tests. That said, the official guidance cautions that "a reviewer instructed to look for gaps tends to report something even for sound work. Tell it to raise only gaps related to correctness or requirements" (Source 1).

A checklist for building test scenarios

• Include concrete test cases (inputs and expected values) in your prompt
• Explicitly enforce TDD by making RED confirmation mandatory
• Do E2E verification with browser automation, not just unit tests
• Put a rule in place that prohibits deleting or altering tests
• Control autonomous execution with a state file + retry limit + completion signal
• Separate the implementer from the verifier, and use hooks to reliably trigger verification