Testing with Claude Code

Use Claude Code for contract-driven unit, integration and Playwright tests, then create and verify browser acceptance tests with ContextQA MCP.

Quick answer

Claude Code can help design tests, edit test files and run the test tools already installed in your repository. Start with an independently defined expected result, generate the smallest useful test, and inspect the actual runner output. Add ContextQA MCP when you want to create and execute managed browser tests against a reachable application. ContextQA MCP does not replace your Jest, Vitest or pytest runner.

This walkthrough uses an illustrative invoice-discount change: a discount is allowed through its expiry time, cannot make the total negative, and must appear correctly in the saved invoice. Adapt the contract and paths to your application; the examples are instructions, not recorded test results.

Before you start

Have Claude Code working in the correct repository, its dependencies installed, the feature's acceptance criteria, and a disposable test environment. Identify the branch, application version and test-data reset procedure. Use test accounts and approved secret storage; do not paste production credentials into prompts.

Choose the lowest test level that can prove each behavior:

Question	Appropriate test
Does the discount calculation handle boundaries?	Unit test
Does invoice creation persist the correct total?	Integration test
Can a user apply and remove a valid discount?	Functional test
Does creating, saving and reopening an invoice preserve it?	End-to-end test

1. Establish the commands and current baseline

Start Claude Code in your repository:

cd /path/to/your/repository
claude

Claude Code supports inspecting existing tests and following repository conventions. See its official testing workflow.

Give it a bounded discovery task before requesting edits:

Read this repository's instructions, package/build configuration and the
existing invoice tests. Identify the test runner, exact focused test command,
fixture setup and cleanup. Run the existing focused suite and record its
result. Do not install a second framework or change application code.
Separate pre-existing failures from the tests we add next.

Keep the baseline output. A missing database or unavailable browser is an environment blocker; it is not evidence that the feature passes or fails.

2. Turn the requirement into independent examples

Agree the currency rounding and expiry rules before asking the agent to write assertions. If the requirement is silent, label the assumption for review rather than letting the current implementation become the specification.

Our accepted contract is: totals use integer minor units; a discount cannot
reduce an invoice below zero; expiry is inclusive at the stated UTC timestamp.
Create a decision table for a normal discount, an excessive discount, expiry
one second before/at/after the boundary, and an invalid discount identifier.
Calculate expected totals from this contract, not by calling the production
calculator. Identify any remaining ambiguity before writing test files.

A valuable assertion checks the amount owed. Checking only that the calculator was called, or that an object exists, does not prove pricing behavior. Control the test clock so tomorrow's date does not change the verdict.

3. Write unit and integration tests in small increments

Ask Claude to add the approved cases using the existing runner. Unit tests should isolate the calculation; integration tests should exercise the persistence boundary with a disposable database or the repository's existing test service.

Implement the approved decision table in the existing test files. Use fixed
time and deterministic input data. Keep unit tests independent of network
services. For the integration test, save and reload an invoice and assert the
stored total and discount identifier. Clean up only this test's records.
Run the focused commands. Show assertions and results before proposing a fix.
Do not weaken expectations, update snapshots blindly, or skip failing cases.

For a confirmed defect, the new regression test should expose that defect before a repair and pass after it. For new behavior, an initial failure may instead mean the feature is not implemented yet. Keep the distinction in the review.

4. Add one browser journey where it adds evidence

Use the repository's browser framework. If it uses Playwright, follow the Playwright testing guide for fixtures, locators and traces.

Add one browser test for our disposable invoice account. Open a new invoice,
apply the approved discount, assert the exact visible total, save, then reopen
the invoice and assert persistence. In a separate test with a fresh invoice,
test an expired discount and verify the original total remains unchanged.
Reuse existing fixtures and user-facing locators.
Run against the specified test URL. Report the runner command, exit status,
test counts and failure artifacts. Do not treat a screenshot alone as a pass.

Check which services were real and which were mocked. An intercepted save response verifies UI behavior; it does not prove that the backend stored the invoice.

5. Connect Claude Code to ContextQA MCP

For managed browser execution, add the hosted server:

claude mcp add --transport http contextqa https://mcp.contextqa.com/mcp
claude mcp list

In an interactive Claude Code session, open /mcp, select ContextQA and complete OAuth sign-in. Wait for the browser callback to finish. The command and authentication flow follow Claude Code's MCP documentation and the ContextQA server setup. The account must have access to the intended ContextQA workspace.

The MCP connection gives Claude tools for ContextQA. It does not make your laptop's files or localhost application reachable by a remote test runner. Use a reachable test deployment or an organization-approved network setup for your application. Confirm the actual target environment before execution.

6. Discover, create, review, execute and inspect

First make a read-only request:

Using ContextQA, inspect the connected tool names and schemas. List available
test environments and search for existing invoice-discount tests. Show matching
test IDs and steps. Do not create, update or execute anything yet.

Then supply the approved target URL and criteria:

Prepare the missing browser cases in our designated test workspace for the
invoice-discount scenario above. Use [approved test URL] and the configured
test account. Keep the valid-discount and expired-discount cases separate,
each with a fresh invoice and explicit starting total.
Reuse matching cases where they exist. Return case IDs and complete steps
for review. Do not execute it until the steps and environment are confirmed.

After review, ask Claude to execute that specific case. The documented flow is execute_test_case, get_execution_status, then get_test_case_results and get_execution_step_details, using the IDs returned by the tools. Follow the connected schema and execution reference; do not guess IDs or reuse an older result.

Record the case ID, execution/result ID, target build, verdict, failed assertion and evidence links. A completed execution still needs a pass/fail result. A correctly rejected expired discount is a passing negative test, not a test failure.

Export the reviewed test

Ask for supported export options for that case, then choose the required framework. Inspect the returned artifact location before assuming a hosted export wrote to your laptop. Follow export and portability, review generated code, and run it in your own CI before accepting equivalence. Export is a starting point for repository ownership, not proof that every fixture or assertion transfers unchanged.

Troubleshooting and FAQ

Claude wrote tests but did not run them. Request the exact command and output. If execution is blocked, report the blocker and leave the result unverified.

The tests pass only after retries. Preserve the first failure, compare timing and fixture state, and investigate before increasing retries.

MCP is connected but finds no tests. Confirm the account, workspace and search scope. An empty search is not a connection failure. Use connection troubleshooting.

Can ContextQA run my local unit suite? Run that suite through Claude Code's repository tools. Use ContextQA for the application tests exposed by its connected tools.

Try the workflow

Connect ContextQA MCP and run your first reviewed test. To evaluate shared suites, evidence retention or team workflows, book a ContextQA demo with one representative application journey.