Testing patterns in Cursor

Testing patterns in Cursor are prompts and checks that make Cursor’s agent write tests from specified behaviour instead of from the code it just read. They cover existing and legacy code, error paths, production bugs, coverage gaps, test data, browser tests and flaky tests. Each pattern ends with evidence that the tests can fail.

You shipped a payment service with no automated tests. You ask Cursor’s agent for a suite, it writes 30 tests, all green, and coverage jumps to 85%. Two weeks later a refactor breaks refunds and nothing goes red, because every assertion restated what the code already did. This page is for the developer who writes the prompts and the tech lead who decides what a test-bearing pull request must prove.

Documentation freshness

Covers the Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor’s release notes). Cursor’s docs list four agent modes, Agent, Ask, Plan and Debug, and Shift+Tab cycles through them; Cmd+I (Ctrl+I on Windows and Linux) opens the Agent panel. Its run modes are Auto-review, Allowlist and Run Everything, and Cursor names no single default model (all checked 2026-10-12). Rules, Hooks, MCP and the Run modes page were first verified against cursor.com on 28 August 2026. @playwright/mcp 0.0.82 was checked with npm view on 26 September 2026.

What you’ll walk away with from these Cursor testing patterns

• A project rule and run-mode setup that lets the agent run tests on its own without running anything destructive
• Eight copy-paste prompts: behaviour-first suites, async and error paths, characterization tests, bug-to-failing-test, coverage gaps, test data factories, Playwright end-to-end tests, and flaky-test triage
• A five-item evidence checklist that tells you whether agent-written tests can catch a bug, without reading every test
• A table of the ways agent-written tests fail and how to recover from each

Which testing pattern fits your code?

Pick the pattern by what you know about the correct behaviour. The source of “correct” (the oracle) decides what the tests may assert.

Your situation	Pattern	Where “correct” comes from
New feature or behaviour change	Test-driven development in Cursor	Your spec, written before the code
Working code, few or weak tests, known rules	Behaviour-first suite	Business rules you state in the prompt
Legacy code nobody fully understands	Characterization tests	Current behaviour, recorded before you change it
A bug reached production	Bug to failing test	The bug report
Coverage report shows untested branches	Coverage gaps	The rules behind each uncovered branch
A user journey spans pages and services	Playwright MCP end-to-end tests	Acceptance criteria for the journey
A test fails one run in ten	Flaky-test triage	The test’s own intent, made deterministic

Set up Cursor so the agent can run tests safely

Every pattern below depends on the agent running the suite, reading the failure, and trying again. Set this up once per repository.

1. Let test commands run without a prompt. Cursor decides which terminal commands the agent runs unasked through its run modes (the Run modes page under Agent security in Cursor’s docs, verified 28 August 2026). Cursor’s docs name three modes, Auto-review (the recommended default since Cursor 3.6), Allowlist and Run Everything, under Settings > Agents > Approvals & Execution (checked 2026-10-12). Choose the mode that runs test, type-check and lint commands freely and still asks before anything that deletes data or touches a remote. Do not use Run Everything, which runs every command unattended, outside a disposable, network-restricted sandbox.

2. Write the testing conventions into a project rule. A rule keeps the conventions in every session, so you stop repeating them in each prompt. See project rules for scopes and file placement.

3. Commit before the agent starts. A clean commit makes git diff --stat show exactly which files the agent touched, which is how you catch an edited assertion.

4. Make the test command obvious. Name it in the rule (for example npx vitest run) so the agent does not guess between npm test, jest and a stale script.

Copy-paste project rule: testing conventions

Testing conventions for this repository:
- Framework: Vitest. Run the suite with `npx vitest run`; run one file with
  `npx vitest run <path>`.
- Tests live next to the code in __tests__/ folders and are named
  "should <behaviour> when <condition>".
- Unit tests never use real timers, random values, the network or a real
  database. Use vi.useFakeTimers(), fixed seeds and the factories in
  src/test-utils/factories.ts.
- A failing test is evidence, not an obstacle. Never weaken, delete or skip
  an assertion to make a test pass. If you think a test is wrong, stop and say
  which one and why.
- When asked to implement or fix code, do not edit files under __tests__/.
- After any change, run the affected test files, then `npx tsc --noEmit`
  and `npm run lint`, and report the results.

A rule is an instruction, not a lock. To make the “do not edit tests” line enforceable, Cursor’s hooks can “observe, block, or modify behavior” at stages of the agent loop (cursor.com/docs/hooks, verified 28 August 2026). Protect the oracle shows the blocking logic and CI checks that sit outside the agent’s reach.

Generate tests for existing code from behaviour, not implementation

The common failure is a suite that describes the code rather than the requirement. When the agent reads payment-service.ts and writes tests from it, every test passes on the first run, including on the bugs. State the rules yourself and treat the code as a suspect.

Copy-paste prompt: behaviour-first test suite

Write a Vitest suite for @src/services/payment-service.ts in
src/services/__tests__/payment-service.test.ts. Do not edit anything under src/
except that test file.

Treat the implementation as possibly wrong. Derive tests from these rules:
1. A payment amount is a positive integer in cents; zero, negative and
   fractional amounts are rejected with INVALID_AMOUNT.
2. A refund never exceeds the captured amount minus earlier refunds.
3. The same idempotency key never creates two charges.
4. A Stripe error or a database timeout leaves no partial payment row.
5. Only the payment's owner or an admin can refund it.

For every public function also cover: validation errors, external service
failures (mock the Stripe SDK, the database and the email service), boundary
values, and authorization errors. Use the factories in
@src/test-utils/factories.ts and the style of
@src/services/__tests__/user-service.test.ts.

Run the suite. List every test that fails on the current code and say whether
the test or the code looks wrong. Do not change a failing assertion.

A test that fails here is the most valuable output of the session: either the rule you stated is wrong, or the code has a bug you just found. Decide which before anyone edits anything.

The same prompt shape works at other layers. Name the conventions file so the agent matches your queries and matchers instead of inventing new ones.

React component

Write Vitest + React Testing Library tests for @src/components/UserProfile.tsx.
Cover: renders the name and avatar from props, falls back to initials when
the avatar is missing, calls onEdit once when the edit button is clicked, and
disables the edit button while `saving` is true. Query by role and label,
never by class name. Follow @src/components/__tests__/Card.test.tsx.

Node API endpoint

Write supertest + Vitest tests for POST /api/users in @src/routes/users.ts.
Cover: 201 with a body containing `id` on valid input, 400 with an error
mentioning "email" on a malformed email, 409 on a duplicate email, and 401
without a session. Mock the database layer; do not hit a real database.

Test the async and error paths that coverage hides

A green happy-path test hides the retry, the timeout and the rejected promise. Name each one, and ask for call-count assertions, because “it eventually returned data” does not prove the retry logic ran.

Copy-paste prompt: async retries and failures

Write Vitest tests for fetchUserData(id) in @src/api/users.ts. Cover four cases:
1. Returns parsed data on a successful response.
2. Retries once and succeeds when the first call rejects with a network error.
3. Throws a typed FetchUserError after exhausting retries.
4. Does not retry on a 4xx response.
Stub fetch with vi.stubGlobal('fetch', vi.fn()) and assert the number of calls
in every case. Use fake timers for any backoff delay.

it('does not retry on a 4xx response', async () => {
  const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 404 });
  vi.stubGlobal('fetch', fetchMock);
  await expect(fetchUserData(1)).rejects.toThrow(FetchUserError);
  expect(fetchMock).toHaveBeenCalledOnce();
});

The toHaveBeenCalledOnce() line is the one that catches a bug. Without it, a client that retries a 404 three times still passes.

Pin legacy behaviour with characterization tests

For code nobody fully understands, you cannot state the rules yet. Characterization tests record what the code does today, including behaviour that looks wrong, so a refactor that changes behaviour turns a test red. They are the prerequisite for a legacy refactor in Cursor; the tool-neutral method is in characterization tests.

Copy-paste prompt: characterization tests

@src/services/legacy-pricing-engine.ts has no tests and complex business logic.
Write characterization tests in
src/services/__tests__/legacy-pricing-engine.test.ts. Do not edit the source.

1. List every exported function and the inputs that change its result.
2. For each, choose inputs that hit each branch: typical values, zero, negative,
   empty lists, very large numbers, and each discount tier boundary.
3. Run the real function and assert its actual output, even where it looks wrong.
4. Mark each surprising result with a comment starting "// SUSPECT:" and one
   sentence on why.
5. Run the suite twice. Every test must pass both times; if one does not, the
   code is nondeterministic and you must report where.

These tests capture behaviour so we can refactor safely. They do not judge it.

Review the SUSPECT: comments with someone who knows the domain. Each one either becomes a real bug ticket or a documented rule. Do not let the agent “fix” them during the refactor that follows.

Turn a production bug into a failing test first

A bug fix without a failing test is a guess. Make the agent reproduce the bug as a test, show you the failure, and only then fix it. The full reproduce-diagnose-fix loop is in AI-assisted debugging in Cursor.

Copy-paste prompt: bug to failing test

Bug: orders with decimal quantities (for example 2.5 units of a product sold
by weight) make calculateOrderTotal in @src/services/order-service.ts return NaN.

Step 1. Write one test in src/services/__tests__/order-service.test.ts that
passes quantity 2.5 at a unit price of 400 cents and expects a total of 1000.
Run it and paste the failure output. Stop if it passes: then the bug is
somewhere else, and you should tell me what you checked.
Step 2. Fix the source. Do not change the test.
Step 3. Run the whole order-service test file and paste the result.

The pasted failure from step 1 is the evidence. A regression test that was never seen red proves nothing about the bug.

Close coverage gaps without chasing the percentage

A coverage percentage is not a quality measure: 100% line coverage with weak assertions still ships bugs. Use the report to find which branches nobody tests, then ask for tests that would catch a regression on the risky ones.

Copy-paste prompt: coverage gaps

Run `npx vitest run --coverage src/auth`. For each file in src/auth, including files with no tests
(set coverage.include), list the uncovered branches and functions with line numbers. Rank them by risk: error
handling, security checks and money first, trivial getters last.

For the top five, write tests with realistic inputs in the existing test files,
following their style. Each test must assert an outcome that would change if
the branch were broken. Do not write a test that only executes a line.
Re-run coverage and show the before and after branch percentage per file.

File           | % Stmts | % Branch | % Funcs | % Lines
---------------|---------|----------|---------|--------
auth/login.ts  |   75.00 |    66.67 |  100.00 |   75.00
auth/reset.ts  |   45.00 |    33.33 |   66.67 |   45.00

In a report like this, auth/reset.ts has the thinnest branch coverage, so the password-reset edge cases (expired token, already-used token, unknown email) are the tests worth writing first. Vitest needs a coverage provider such as @vitest/coverage-v8 installed for --coverage to work. Set coverage.include: ["src/**"] in the Vitest config, or files with no tests at all are missing from the report. To measure whether the tests catch bugs rather than touch lines, see oracle strength.

Build test data factories once

Inline objects in every test drift from the real types and make each test longer than the behaviour it checks. Ask for factories once and name the file in your testing rule.

Copy-paste prompt: test data factories

Create src/test-utils/factories.ts from the types in @src/types/.
Write createUser(overrides?), createOrder(overrides?) and
createPayment(overrides?). Each returns a complete, valid object, accepts a
partial object of overrides typed from the real type, links to its parent (an
order has a user, a payment has an order) and takes ids from one incrementing
counter, never Math.random(). Do not cast with `as`; let the compiler check
every default. Run `npx tsc --noEmit` and fix any type error in the factories.

Good output looks like this:

let seq = 0;
const nextId = () => ++seq;

export function createUser(overrides: Partial<User> = {}): User {
  const id = nextId();
  return { id: `user-${id}`, email: `test-${id}@example.com`, name: 'Test User', ...overrides };
}

The type check is the verification here: if User gains a required field, the factory stops compiling instead of silently producing invalid data. For shared fixtures, seeding and anonymised production data, see test data management.

Drive end-to-end tests with the Playwright MCP server

For journeys that cross pages, the Playwright MCP server (@playwright/mcp) lets the agent drive a real browser, so it can write a Playwright test and then run it against your local app. Add it to the project’s .cursor/mcp.json; MCP setup covers the other configuration locations.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated"]
    }
  }
}

--isolated keeps the browser profile in memory. Playwright’s README notes that a persistent profile can only be used by one browser instance at a time, so parallel agents conflict without it. The old @modelcontextprotocol/server-puppeteer package is archived; use the Playwright server. Its tool schemas and page snapshots take context, so enable it for UI work, not for every session.

Copy-paste prompt: login flow end-to-end tests

The app is running at http://localhost:3000 (started with `npm run dev`).
Using the Playwright MCP server, open /login and explore the form. Then write
tests/e2e/login.spec.ts with Playwright Test covering:
1. Valid credentials redirect to /dashboard.
2. Invalid credentials show an alert containing "Invalid credentials".
3. The "Forgot password" link navigates to /reset.
Use getByRole and getByLabel locators, never CSS selectors, and web-first
assertions such as await expect(page).toHaveURL(/\/dashboard/).
Run `npx playwright test tests/e2e/login.spec.ts` and fix failures in the test
setup only. If the app itself behaves wrongly, report it instead of adapting
the test.

test('shows an error for invalid credentials', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('wrong-password');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByRole('alert')).toContainText('Invalid credentials');
});

Accessible locators survive the CSS refactors that break #id and .class selectors, and they fail when a control loses its label, which is an accessibility bug worth catching. The committed spec, not the agent’s browser session, is what runs in CI. Broader E2E strategy is in end-to-end test automation.

Triage a flaky test with repeated runs

A test that fails one run in ten wastes more time than one that always fails. The agent’s advantage is that it can run the test many times without getting bored.

Copy-paste prompt: flaky-test triage

tests/e2e/checkout.spec.ts > "applies the discount" fails intermittently in CI
and usually passes locally.
1. Run `npx playwright test tests/e2e/checkout.spec.ts --repeat-each=25` and
   report how many runs fail, with the first failure output.
2. Log shared state at setup and teardown: database connections, timers,
   module-level variables, and network calls still in flight.
3. Name the source of nondeterminism (leaked state, an unawaited promise, a
   shared fixture, a real race) with the log lines that show it.
4. Propose a fix that removes the cause. A longer timeout or a retry is not a fix.
5. Apply it and re-run 25 times. Report the pass count.

For Vitest unit tests, loop in the terminal instead: for i in $(seq 25); do npx vitest run src/cart/__tests__/cart.test.ts || echo FAIL; done. The fix is usually isolation, a teardown hook or an awaited settle, not a bigger timeout. Race conditions that need deeper investigation belong in bug hunting.

How do you verify agent-written tests without reading them all?

Check that the tests can fail and that nobody bent them to fit the code. Ask for this evidence on every pull request that adds tests, and read test code only where an item is missing or surprising.

1. Red before green. New tests for new behaviour or a bug fail on the old code, and the failure output is in the pull request. Characterization tests are the exception: they pass by design.
2. Break-it check. For each new test, the agent makes the smallest change that should break it, shows the failure, and reverts. A test that stays green is decoration. Oracle strength scales this into mutation testing across a suite.
3. Tests untouched during the fix. git diff --stat for the implementation commit lists no test files.
4. No hollow mocks. The prompt below finds tests that would pass with the implementation deleted.
5. Gates green in CI, not only in the agent’s report: the test suite, tsc --noEmit and the linter. CI/CD with Cursor wires them in.

Copy-paste prompt: find tests that test nothing

Review the tests added on this branch (`git diff main...HEAD --name-only -- '*.test.ts'`).
For each test, answer: would it still pass if the function under test returned
a hard-coded value, threw nothing, or were deleted and replaced by the mock?
List every test where the answer is yes, with the reason, and rewrite its
assertion to check real behaviour. Do not edit any file outside the test files.

The developer who opened the pull request owns this evidence. The reviewer, human or Bugbot, approves when every item is present. The reasoning behind reviewing evidence instead of diffs is in evidence, not diffs.

When agent-written tests in Cursor go wrong

Symptom	Likely cause	Recovery
Every new test passes on the first run	Tests were derived from the implementation	Re-run the behaviour-first prompt with the rules stated and src/ read-only
A failing test goes green after the test file changed (toBe became toBeDefined)	The agent weakened the assertion	Revert the test file, say “The test is correct; fix the implementation”, and check git diff --stat
Tests pass but the feature is broken	Over-mocking: tests assert against the mock	Run the hollow-mocks prompt; keep at least one integration or E2E test that crosses the real seam
Coverage rises, bugs still escape	Tests execute lines without asserting outcomes	Run the break-it check on the module that leaked the bug
Tests pass locally, fail in CI	Real timers, random values, shared state or a different environment	Add the rule’s no-timers, no-random line; reproduce with the CI command and seed data
The agent ran a command that deleted data or pushed	A run mode that allows every command	Switch to a mode that asks before destructive or remote commands; restore from the pre-session commit
Playwright tests fail at once with connection errors	The dev server is not running or runs on another port	Start the app, put the exact URL in the prompt, and tell the agent to wait for it to respond before navigating
A flaky test is “fixed” with a longer timeout	The race is hidden, not removed	Ask for the root cause with log evidence and 25 consecutive passing runs
The agent writes five features’ worth of code instead of making one test pass	The loop is too wide	Interrupt: “Stop. Make only the failing refund test pass, then run the suite.” A tight loop produces better code than one large generation
One test file grows past a few hundred lines	One file per service accumulates every domain	Ask the agent to split it by behaviour (auth, refunds, webhooks) and run the suite before and after

Where to go next with Cursor testing

Test-driven development in Cursor Write the failing test from the spec first, then let Cursor's agent implement.

AI-assisted debugging in Cursor Investigate read-only, reproduce, fix one cause, and prove it.

Protect the oracle Checks the agent cannot edit: locked test paths, CI-owned gates and holdout scenarios.

Code review in Cursor Review test-bearing pull requests against evidence before merge.

Start from the Cursor test and debug overview if you need the section map. The same stage for other tools: testing with Claude Code and testing with Codex.