Using Cursor to build a test framework (2026)

TL;DR

Using Cursor to build a test framework is safest when you give Agent a narrow architecture brief, persistent repository rules, and a command-based definition of done. Build one vertical slice, run it, review the diff, and expand only when a second real scenario proves an abstraction is needed.

Key Takeaways

• Define framework outcomes, users, boundaries, and feedback targets before asking Cursor to create files.
• Use a planning pass to discover repository constraints before allowing multi-file edits.
• Prove the architecture with one executable vertical slice instead of generating every framework layer.
• Store concise project rules in .cursor/rules and verify that the intended rule is active.
• Prefer Playwright fixtures, semantic locators, and direct assertions over speculative wrapper layers.
• Use compiler, test, lint, and trace evidence to steer corrections.
• Treat Cursor checkpoints as local convenience and Git as the durable review history.

Using Cursor to build a test framework can accelerate repository discovery, scaffolding, refactoring, and feedback, but Cursor should implement a framework strategy rather than invent one. Begin with the product risks, intended contributors, execution environments, supported browsers, data ownership, and target feedback time. Then ask Cursor to prove those decisions through one runnable scenario.

This guide builds a small Playwright and TypeScript framework because Playwright Test already provides isolation, fixtures, parallel workers, retries, reporters, projects, and trace capture. That lets Cursor focus on product-specific structure instead of generating replacements for runner features. The same controlled workflow applies to Selenium, API, mobile, or hybrid frameworks: discover, plan, build a thin slice, execute, review, and only then generalize.

TL;DR

The core loop is brief -> plan -> constrained edit -> executable feedback -> human review. Cursor can search and edit faster than a person, so your process must make wrong direction visible early.

1. Using Cursor to Build a Test Framework Begins With Outcomes

A framework is not a folder tree. It is a product used by testers and developers to create trusted evidence. Before asking Cursor to generate code, write an architecture brief that answers why the framework exists and how maintainers will judge it.

Define the first three to five risks it must cover. For a web application, these might be authentication boundaries, checkout integrity, role permissions, and critical read paths. Define users: experienced SDETs, feature developers, manual testers contributing data, or all three. State execution environments, browser scope, expected pull request feedback time, and where test data comes from. Add non-goals such as visual testing, performance testing, or production execution if they are outside the first release.

A useful brief includes measurable acceptance without fabricated performance promises:

Goal: create the first maintainable Playwright TypeScript framework slice.

Users: QA engineers and feature developers.
Initial scope: public documentation navigation in Chromium.
Later scope: Firefox and WebKit after the first scenario is reliable.
Required: isolated tests, semantic locators, HTML report, trace on first retry,
typed page model, no shared mutable state, no fixed waits, no custom reporter.
Commands: npm run typecheck and npm test must pass.
Allowed files: package scripts, playwright.config.ts, tests/, pages/, fixtures/.
Do not create base classes, dependency injection containers, or generic utilities.

The brief changes the nature of the task. Instead of build a framework, Cursor receives a bounded engineering increment. The engineer can review each choice against an outcome. For a broader framework decision model, read how to build your first test automation framework.

2. Select Cursor Modes and Context Deliberately

Cursor Agent can search the codebase, edit multiple files, and run terminal commands. Ask mode is useful for exploration when you do not want edits. Inline Edit is useful for a known selection. The correct choice depends on uncertainty and blast radius, not on which interface feels most powerful.

Start with a discovery prompt: Do not edit files. Read package.json, tsconfig files, CI workflows, and existing tests. Report the current runner, module format, commands, locator conventions, environment inputs, and conflicts with the proposed Playwright slice. Cite every conclusion by repository path. This prevents a common failure where Agent creates a second toolchain beside an existing one.

Context should be surgical. Attach or mention the architecture brief, relevant build file, one application feature, and one good neighboring pattern. Adding the entire repository indiscriminately can bury the decision facts. Cursor automatically retrieves relevant code, but explicit file context is valuable when you know which contract matters.

After discovery, ask for a plan with a proposed file list and one sentence of responsibility per file. Review it before edits. If the plan includes BasePage, DriverManager, WaitUtils, or a custom assertion library for a first Playwright scenario, remove them and ask why native runner features are insufficient.

3. Scaffold Playwright With the Official Tooling

Use Playwright's supported initializer rather than asking Cursor to handcraft every dependency. In an empty or approved repository, the official command is:

npm init playwright@latest

Choose TypeScript, a tests directory, the GitHub Actions option according to your repository policy, and browser installation when prompted. In an existing repository, review the generated diff before accepting it. If package management, Node versions, or CI are already governed, instruct Cursor to integrate with those choices rather than overwrite them.

The key commands are:

npx playwright install
npx playwright test
npx playwright test --project=chromium
npx playwright show-report

Add stable package scripts so humans and Agent use the same entry points:

{
  "scripts": {
    "test": "playwright test",
    "test:chromium": "playwright test --project=chromium",
    "test:headed": "playwright test --headed",
    "test:report": "playwright show-report",
    "typecheck": "tsc --noEmit"
  }
}

This snippet shows the scripts portion, not a complete replacement for package.json. Keep the initializer's current @playwright/test dependency and commit the lockfile. A lockfile makes CI and local installation resolve the same graph.

Ask Cursor to run npx playwright --version and read the installed type definitions if a method is uncertain. Current documentation is more reliable than model memory. Do not prompt it to use undocumented internals or methods copied from another test library. Native Playwright auto-waiting and web-first assertions remove the need for hand-built wait helpers. The Playwright getting started guide is useful background for contributors who are new to the runner.

4. Design a Thin Vertical Slice Before a Folder Taxonomy

A vertical slice crosses the minimum architecture needed to prove value: configuration, a product-facing model, a fixture, one test, and execution evidence. It reveals whether imports, typing, lifecycle, locators, reports, and CI assumptions work together. A folder taxonomy without a passing slice proves none of those things.

Use this initial structure:

.
├── fixtures/
│   └── test.ts
├── pages/
│   └── DocsHomePage.ts
├── tests/
│   └── docs-navigation.spec.ts
├── playwright.config.ts
├── package.json
├── package-lock.json
└── tsconfig.json

Responsibilities are intentionally narrow. playwright.config.ts contains runner policy. DocsHomePage models a real user capability. fixtures/test.ts composes a reusable typed page object with Playwright's lifecycle. The spec contains the behavior and oracle. There is no utils directory because no repeated utility need has appeared.

Ask Cursor to write a responsibility table before code:

This table makes architecture review concrete. When a later scenario needs an authenticated user, decide whether state belongs in an API helper, worker fixture, or test-scoped fixture based on cost and isolation. Do not add a BaseFixture in anticipation.

The thin-slice principle also limits AI rework. If the base URL is wrong or a semantic locator does not match, only a few files are affected. Once the slice passes, use it as high-quality local context for Cursor. Models imitate nearby patterns, so the first accepted pattern deserves unusually careful review.

5. Add Cursor Project Rules for Test Architecture

Cursor project rules live under .cursor/rules as version-controlled .mdc files. Current Cursor documentation describes Always, Auto Attached, Agent Requested, and Manual rule types. The metadata fields description, globs, and alwaysApply control how a rule is selected. Use Cursor's New Cursor Rule command when possible, then verify its displayed rule type in settings.

For a small framework, an always-applied rule can remain concise:

---
description: Playwright test framework architecture and quality rules
globs:
alwaysApply: true
---

# Test framework rules

- Use TypeScript and Playwright Test native fixtures.
- Keep assertions in specs. Page models expose user capabilities.
- Prefer getByRole, getByLabel, and team-owned test IDs.
- Never add waitForTimeout or fixed sleeps.
- Do not add retries to repair an individual failing test.
- Keep every test isolated and safe for parallel execution.
- Use process.env only through documented configuration boundaries.
- Never log credentials, tokens, cookies, or private user data.
- Reuse an abstraction only after two real callers demonstrate the same behavior.
- Run npm run typecheck and the narrowest relevant Playwright test after edits.
- Report exact commands, results, assumptions, and files changed.

Rules should encode stable repository truth. A one-off scenario belongs in the prompt, not permanent context. Avoid long style manuals, duplicated documentation, and conflicting rules at nested paths. A rule that says make tests robust is not actionable. A rule that forbids fixed sleeps and identifies the approved locator hierarchy can be checked in a diff.

Verify rule use. Cursor shows active rules in its interface, and an Auto Attached rule needs a matching referenced file. If behavior suggests a rule was missed, inspect the rule type and explicitly mention it rather than assuming. Treat .cursorrules as legacy and prefer Project Rules for new work.

Review rule changes through pull requests. An AI tool's persistent instructions can influence many later files, so a small rule modification may have a larger effect than a single test edit.

6. Use a Three-Prompt Workflow: Plan, Build, Review

One giant prompt combines discovery, design, implementation, execution, and repair. Separate prompts create review gates.

Prompt 1: plan without edits

Do not edit files. Using the architecture brief and current repository:
1. Identify existing commands, TypeScript settings, and CI constraints.
2. Propose the smallest Playwright vertical slice.
3. List files to create or modify with one responsibility each.
4. Identify assumptions and decisions that cannot be inferred.
5. Explain how the slice proves isolation, diagnostics, and maintainability.

Prompt 2: implement within boundaries

Implement only the approved vertical slice.
Allowed paths: playwright.config.ts, pages/, fixtures/, tests/, package scripts.
Use native Playwright APIs and the project rule.
Run npm run typecheck and npx playwright test tests/docs-navigation.spec.ts
--project=chromium. Fix only errors caused by this change.
Stop and report if the repository or network prevents execution.

Prompt 3: adversarial review

Review the resulting diff without editing it.
Find unsupported API use, hidden shared state, weak locators, fixed waits,
assertions in page models, secret exposure, speculative abstractions,
parallel-safety problems, and missing failure evidence.
Rank findings by impact and cite file locations.

The review prompt changes the model's role from builder to critic. It does not replace human review, but it can surface inconsistencies before a pull request. Ask Cursor to explain zero findings if it reports none, because an empty review should still mention what it checked.

Follow-ups should carry raw evidence. Paste the exact TypeScript error or Playwright failure, reference the affected file, and constrain repairs. Avoid make it pass because that can invite weakened assertions, skipped tests, or broad configuration changes.

7. Implement a Runnable Playwright Framework Slice

Use a public documentation site so the example can run without credentials. First configure Playwright:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: Boolean(process.env.CI),
  retries: process.env.CI ? 1 : 0,
  reporter: process.env.CI
    ? [['line'], ['html', { open: 'never' }]]
    : [['list'], ['html', { open: 'never' }]],
  use: {
    baseURL: 'https://playwright.dev',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

Create pages/DocsHomePage.ts:

import type { Locator, Page } from '@playwright/test';

export class DocsHomePage {
  readonly getStartedLink: Locator;

  constructor(private readonly page: Page) {
    this.getStartedLink = page.getByRole('link', { name: /get started/i });
  }

  async open(): Promise<void> {
    await this.page.goto('/');
  }

  async openGetStarted(): Promise<void> {
    await this.getStartedLink.first().click();
  }
}

Create a typed fixture at fixtures/test.ts:

import { test as base } from '@playwright/test';
import { DocsHomePage } from '../pages/DocsHomePage';

type AppFixtures = {
  docsHome: DocsHomePage;
};

export const test = base.extend<AppFixtures>({
  docsHome: async ({ page }, use) => {
    await use(new DocsHomePage(page));
  },
});

export { expect } from '@playwright/test';

Finally, create tests/docs-navigation.spec.ts:

import { expect, test } from '../fixtures/test';

test('Get Started opens the installation guide', async ({ docsHome, page }) => {
  await docsHome.open();
  await docsHome.openGetStarted();

  await expect(page).toHaveURL(/.*\/docs\/intro/);
  await expect(
    page.getByRole('heading', { name: 'Installation', exact: true }),
  ).toBeVisible();
});

Run npm run typecheck and npx playwright test tests/docs-navigation.spec.ts --project=chromium. The slice uses supported fixtures, locators, configuration, and web-first assertions. There is no manual browser cleanup because Playwright Test owns the built-in page fixture lifecycle.

8. Design Configuration, Test Data, and Secrets as Boundaries

Frameworks often become difficult because configuration and data leak into every test. Ask Cursor to create a single documented boundary only when the application needs it. Validate required environment values early and return sanitized errors. Do not create an all-purpose configuration singleton that reads arbitrary variables throughout the repository.

A small typed configuration module might be:

type TestEnvironment = {
  baseURL: string;
  apiURL: string;
};

export function loadTestEnvironment(): TestEnvironment {
  const baseURL = process.env.BASE_URL;
  const apiURL = process.env.API_URL;

  if (!baseURL || !apiURL) {
    throw new Error('BASE_URL and API_URL are required');
  }

  return { baseURL, apiURL };
}

Pass resolved values into Playwright configuration or fixtures. Never print tokens to prove they loaded. Use CI secret management, and keep .env files with real values out of source control. If Cursor needs an example, provide names and redacted shapes, not credentials.

Separate test data definitions from test data lifecycle. A data object describes values. A fixture or API client creates mutable server state and cleans it up. Prefer API setup for UI tests when it is an approved product path, then use the browser to test the user behavior that matters. Each parallel worker must receive unique mutable data or an isolated account.

Ask Cursor to document data ownership for every fixture: scope, creation, teardown, idempotency, and failure behavior. Worker-scoped authentication can be efficient, but it is not automatically safe for tests that mutate the same account. Test-scoped fixtures offer stronger isolation at higher setup cost. The choice should follow actual application behavior.

A useful design reference is the test data management guide. AI can generate data quickly, but privacy, referential integrity, cleanup, and realistic boundaries still require test engineering judgment.

9. Steer Cursor With Compiler, Runner, and Trace Evidence

Cursor's terminal integration is valuable because feedback can stay inside the implementation loop. The important discipline is to give commands semantic roles. Type checking detects invalid types and imports. Linting detects repository style and selected hazards. A targeted test detects behavior. Full regression detects integration effects. Trace Viewer helps explain the browser state and action sequence.

When a command fails, do not let Agent freely modify the repository until green. Tell it to:

1. quote the first relevant error,
2. identify the violated assumption,
3. distinguish product failure from test failure and environment failure,
4. propose the smallest repair,
5. name the files it would touch,
6. rerun the narrow command.

This protocol prevents failure laundering. For example, if a heading assertion fails, removing it or changing it to a generic body visibility check makes the command green while destroying the oracle. If a test times out in CI, increasing every timeout hides the missing state model.

Review the actual diff after Agent execution. Cursor's review interface helps inspect additions and deletions. Checkpoints can restore Agent changes locally, but Cursor explicitly distinguishes them from version control. They track Agent changes, not all manual edits, and may be cleaned up. Use Git branches and commits for durable comparison and team review.

For intermittent failures, use Playwright traces, screenshots, console output, and network evidence. Ask Cursor to correlate those artifacts, but confirm its claim. The flaky test debugging guide gives a broader classification workflow. A framework is successful when a maintainer can explain a red test, not merely rerun it.

10. Scale Using Cursor to Build a Test Framework in CI

A second real scenario is the architecture test. It reveals whether the first page model API is useful, whether fixtures isolate state, and whether configuration supports another target without branching. Ask Cursor to compare the two scenarios and list actual duplication. Extract only behavior with the same meaning, lifecycle, and failure expectations.

Use the following decision table:

CI should install the locked dependency graph, install supported Playwright browsers, run type checking, and run an appropriately selected suite. A minimal workflow is:

name: playwright

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run typecheck
      - run: npx playwright test --project=chromium

Adapt action pinning and Node support to organizational policy. Upload reports and traces when useful, with retention and privacy controls. Add Firefox and WebKit because the product risk requires them, not because a generated config makes the lines easy.

Govern the framework with contribution examples, ownership, upgrade policy, flake triage, and deletion criteria. Cursor can help enforce those rules, but maintainers decide when a layer still earns its cost.

Interview Questions and Answers

Q: How would you use Cursor to build a test framework without overengineering it?

I would start with a written architecture brief and ask Cursor for a read-only repository assessment. After reviewing a file-level plan, I would authorize one vertical slice with explicit allowed paths and commands. I would use native runner capabilities before adding custom abstractions. A second real scenario must demonstrate duplication before I extract a reusable layer.

Q: Why is a vertical slice better than generating a full folder structure?

A vertical slice proves that configuration, typing, lifecycle, product modeling, assertions, and execution work together. A folder structure only shows that files were created. Early execution exposes wrong assumptions while the diff is small. It also creates a reviewed local pattern that improves later AI output.

Q: What belongs in a Cursor Project Rule for test automation?

Stable repository conventions belong there: runner choice, locator order, lifecycle, secret handling, forbidden waits, validation commands, and abstraction policy. One-off feature details should stay in the task prompt. Rules should be short, versioned, and verifiable. I also confirm that the rule type and scope are active in the Cursor interface.

Q: How do you prevent Cursor Agent from making broad changes?

I define allowed files, protected interfaces, non-goals, and exact commands before edits. I ask for a plan first and tell Agent to stop when it encounters an unstated architecture choice or environment block. After execution, I inspect the real diff and command output. A green command does not authorize unrelated cleanup.

Q: Why use Playwright fixtures instead of a custom dependency container?

Playwright fixtures already provide typed composition, lifecycle scopes, dependency ordering, and integration with the runner. Replacing those features adds code and a second lifecycle model. I use test-scoped or worker-scoped fixtures based on state ownership. A custom container needs a demonstrated requirement that native fixtures cannot meet.

Q: How should Cursor respond to a failing generated test?

It should use the exact error and artifacts to identify the first failed assumption. I ask it to classify product, test, data, or environment failure and propose the smallest repair before editing. It must not weaken assertions, add skips, or increase timeouts without evidence. The narrow command is rerun after the change.

Q: Are Cursor checkpoints sufficient for framework development?

No. Checkpoints are convenient local snapshots of Agent changes, but they are not durable version control and do not track every manual edit. I use Git for branches, commits, diffs, and team review. A checkpoint may help undo a local experiment, while Git remains the source of truth.

Q: What proves that an AI-assisted test framework is maintainable?

Contributors can add a risk-based test without copying hidden setup, tests run independently, failures produce useful evidence, and dependencies have clear owners. The suite has predictable commands, bounded feedback time, and a process for flake and deletion. Architecture explanations and clean execution matter more than the number of generated layers.

Common Mistakes

• Prompting from a blank brief. Cursor cannot infer product risk, users, execution targets, and data policy. Write those inputs before code.
• Using Agent before repository discovery. Multi-file editing can create a second toolchain or violate existing conventions. Start with a read-only map.
• Generating every layer at once. Base classes, factories, wrappers, reporters, and utilities create unproven coupling. Build one slice.
• Treating the folder tree as architecture. Responsibilities, state ownership, and feedback flow define the design. Directories only organize it.
• Duplicating native Playwright behavior. Custom waits, driver managers, and browser cleanup often make the framework less reliable.
• Writing vague Project Rules. Make tests high quality cannot be checked. Encode concrete locator, wait, data, and command policies.
• Assuming a rule applied. Rule types and scopes differ. Confirm activation and explicitly attach a manual rule when needed.
• Letting Agent chase green output. It may weaken an assertion or broaden a timeout. Require failure classification and a minimal repair.
• Using shared accounts in parallel mutation tests. Worker concurrency turns shared state into nondeterministic failures. Design unique or isolated data.
• Relying on checkpoints as history. They are local convenience, not a substitute for reviewed Git changes.
• Adding cross-browser projects without execution capacity. Each project multiplies runtime and triage. Expand from product risk and CI evidence.

Conclusion

Using Cursor to build a test framework works when Cursor is part of a disciplined engineering loop, not the source of the architecture. Give it a repository-grounded brief, apply concise rules, constrain edits, and require compiler and runner evidence. One reliable vertical slice is more valuable than a generated architecture diagram with no executable proof.

The next step is to write the one-page framework brief, run a read-only Cursor discovery prompt, and approve only the smallest Playwright slice. Once a second scenario passes and exposes real repetition, let the framework grow around evidence rather than prediction.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Add CI to a test framework (2026)
• How to Add logging to a test framework (2026)
• How to Add reporting to a test framework (2026)
• How to Build a hybrid test automation framework (2026)
• How to Structure a scalable test automation framework (2026)
• How to Add parallel execution to a framework (2026)