Cursor lessons for QA.

Cursor's Place in SDLC and STLC

Cursor can accelerate analysis and implementation, but requirements, product intent, test oracles, and release decisions still need accountable owners.

Treat Cursor as a worker inside the QA system, not as the QA system. It can search a repository, explain a failure, draft cases, edit automation, and run commands. It cannot independently establish that requirements are correct or that residual business risk is acceptable.

Start every task by naming the lifecycle stage and the artifact that may change. A requirement-analysis task should not silently become a product-code edit. A test-repair task should not gain authority to weaken the assertion that catches the defect.

Install, Index, Privacy, and .cursorignore

A useful index should expose the code and tests needed for the task while excluding secrets, customer exports, build artifacts, and unrelated repositories.

Install Cursor from its current official installation guide, open a disposable project, and review indexing before giving the agent a task. Privacy Mode changes data handling, but it does not make a poorly scoped workspace safe by itself.

Keep secrets out of the repository. Use .cursorignore to reduce irrelevant or sensitive indexed context, then verify the effective tool and terminal permissions. An ignore file is defense in depth; it is not a replacement for secret management or a sandbox.

.env*
secrets/**
customer-exports/**
playwright/.auth/**
test-results/**
blob-report/**
node_modules/**

Workspace acceptance check

• Search for a known test file and confirm it is available.
• Search for a synthetic secret filename and confirm it is excluded.
• Inspect Privacy Mode and repository trust settings with a teammate.
• Run git status and confirm the exercise begins on a disposable branch.

Ask, Agent, Manual, and Custom Modes

Choose the least-authoritative mode that can complete the next step. Understanding a failure and changing a repository are different jobs.

Use Ask when you need repository-grounded explanation, impact analysis, or a plan with no edit. Use Agent when the task genuinely requires search, edits, and terminal verification. Manual mode is useful when you want tightly selected files and deliberate edits. Custom modes let a team package a repeatable tool and instruction boundary.

Mode names are only the start. Review the enabled tools, auto-run policy, and approval behavior. An Agent with terminal access can create side effects far beyond the visible file diff.

Project Rules for Playwright and Selenium

Versioned project rules make test conventions discoverable and scoped. They reduce repeated prompting without turning preferences into unchecked acceptance criteria.

Current Cursor project rules live in .cursor/rules as MDC files. Use an Always rule only for guidance that truly applies across the repository. Auto Attached rules are safer for framework-specific conventions because their glob limits when they enter context. Treat a root .cursorrules file as legacy.

A rule should name allowed patterns and forbidden false-green techniques. It should also name the command that proves compliance. Keep business requirements and expected behavior in their owned source documents; a Cursor rule can reference them but should not replace them.

---
description: Playwright test conventions
globs: tests/**/*.spec.ts
alwaysApply: false
---

- Prefer role, label, or test-id locators over CSS chains.
- Use web-first assertions; never add fixed sleeps.
- Do not skip, delete, or weaken an existing assertion.
- Keep credentials synthetic and outside source files.
- After edits run: npm run lint && npx playwright test <focused-file>.

Context Architecture for QA

The best context is not the largest context. It is the smallest set that establishes intent, observed behavior, allowed scope, and the command used to decide.

Build a context packet before prompting: the versioned requirement, one failure log, the affected source surface, neighboring tests that demonstrate conventions, and the exact verification command. Include a short protected-path list so the agent knows what evidence it may read but not redefine.

Separate facts from requests. Paste the observed error as evidence, link the requirement as authority, and state your hypothesis as a hypothesis. This makes it easier to catch a confident answer that is unsupported by the repository.

Goal: explain why tests/login.spec.ts fails.
Evidence: @test-results/login-error.txt
Intent: @docs/auth-requirements.md section AUTH-07
Conventions: @tests/auth/session.spec.ts
Protected: product behavior, assertions, test count.
Do not edit files or run commands yet.
Return: cause, cited evidence, smallest proposed scope, and verification command.

Reject these context smells

• An entire monorepo attached without a task boundary.
• A screenshot with no raw failure, DOM, API response, or requirement.
• A stale wiki copied without its owner or revision.
• A prompt that asks for green tests but never states protected intent.

Risk-Based Test Plans and Traceable Cases

Cursor can draft broad coverage quickly, but a human must supply business impact and review whether every critical risk has an observable oracle.

Ask for a structured table, not a prose brainstorm. Give each requirement and risk a stable ID. Require preconditions, data class, observable outcome, automation layer, and priority. The structure lets a script find missing IDs and duplicates even when the test ideas sound convincing.

Use the agent to challenge the plan as a second pass: which P0 risk has no negative case, which oracle depends on implementation detail, and which case cannot run independently? Keep the source requirement open during review.

required = ["AUTH-01", "AUTH-02", "AUTH-03", "AUTH-04"]
covered  = unique(testCases.flatMap(test => test.requirementIds))
missing  = required.filter(id => !covered.includes(id))

assert(missing.length === 0, "Every critical requirement needs evidence")

Page Objects, Fixtures, and Test Data

Generated automation should preserve test intent, accessibility-first locators, isolated state, and readable assertions rather than maximizing abstraction.

Attach one representative test and the project's fixture pattern. Ask Cursor to follow those conventions, not invent a parallel framework. Prefer a small domain helper or page object when it removes meaningful duplication; keep assertions close to the behavior they prove.

Synthetic test data should be explicit and unique. Do not let an agent copy a production email, token, or storage state from local files. Review generated selectors against the accessible UI and reject fixed waits, force clicks, and broad text matches that hide ambiguity.

import type { Page } from "@playwright/test";

export class LoginPage {
  constructor(private readonly page: Page) {}

  async signIn(email: string, password: string) {
    await this.page.getByLabel("Email").fill(email);
    await this.page.getByLabel("Password").fill(password);
    await this.page.getByRole("button", { name: "Sign in" }).click();
  }
}

Review the generated diff

• The locator encodes stable user-facing identity.
• The data is synthetic and the test owns its setup and cleanup.
• Assertions still prove the business outcome.
• No test was skipped, deleted, retried globally, or made serial without evidence.

The Edit-Run-Diagnose Loop

A trustworthy agent task ends with exact commands and a reviewed diff. Repeated conversational confidence is not a test result.

Define the command order before editing: static checks, the smallest focused test, then the relevant regression slice. Require the agent to stop after an unexpected failure class instead of modifying additional files until something turns green.

Review the terminal output directly. A passing focused test can coexist with a broken assertion, missing test, modified fixture, or unrelated regression. Pair results with git diff --stat, the full diff, and test-count checks where risk justifies them.

git diff --check
npm run lint
npx tsc --noEmit
npx playwright test tests/login.spec.ts --project=chromium
npx playwright test tests/auth --project=chromium
git diff -- tests/login.spec.ts tests/pages/login-page.ts

1. Reproduce the original failure and save its output.
2. Approve one hypothesis and one mutable path set.
3. Apply the smallest candidate diff.
4. Run fixed checks without changing commands between attempts.
5. Review the diff and raw evidence before accepting the explanation.

MCP Without Leaking Secrets or Authority

MCP can connect Cursor to browsers, issue trackers, and internal systems. Every server expands the data and actions available to the agent.

Begin by listing the servers and tools Cursor can see. Prefer a read-only issue-tracker tool for analysis and a synthetic browser target for UI exploration. Separate read tools from write tools, and require explicit approval before creating tickets, changing test data, or touching shared environments.

Keep tokens in the platform's secret mechanism, never in a prompt or committed configuration. Review server provenance, command arguments, network destinations, and the data returned to context. Remove a server when the current task does not need it.

cursor-agent mcp list
cursor-agent mcp list-tools <server-identifier>

# Authenticate only after the server and requested scopes are reviewed.
cursor-agent mcp login <server-identifier>

Cursor CLI in a Constrained CI Job

Print mode enables scripted analysis, but the CLI still needs a sandbox, explicit repository permissions, structured output handling, and deterministic gates.

The current CLI uses cursor-agent. Print mode (-p or --print) supports text, JSON, and stream-JSON output. Start with review-only work in a read-only checkout or isolated container and omit --force. A prompt that says 'do not edit' is useful guidance, not a security boundary.

Do not make an agent's prose the required CI status. Let lint, types, tests, policy checks, and code owners control merge. Attach the structured agent review as advisory evidence with the exact commit and prompt version.

cursor-agent status
cursor-agent -p \
  --output-format json \
  "Review the current diff for weakened assertions, fixed sleeps, skipped tests, and leaked secrets. Do not modify files. Cite each finding by path."

npm run lint
npx playwright test tests/auth --project=chromium

CI boundary

• Use a short-lived token and a least-privilege repository identity.
• Block production credentials and deployment permissions from the job.
• Pin the prompt/rule revision and record the commit under review.
• Fail or pass on deterministic policy and test results, not model wording.

Bugbot and Pull-Request Review Policy

Bugbot can surface suspicious changes on a pull request, while a repository policy file focuses review on QA-specific false-green and security risks.

Create .cursor/BUGBOT.md with concise, reviewable concerns. Ask for evidence-backed findings, not style preferences. For test repositories, focus on weakened assertions, removed coverage, fixed sleeps, non-isolated state, secret exposure, and changes that make a test pass without preserving behavior.

Review each finding against the diff, requirement, and test output. A missed finding does not certify the pull request, and a generated warning is not automatically a defect. Keep code owners and the normal review checklist in place.

# QA review policy

- Flag skipped, deleted, or weakened tests.
- Flag fixed sleeps, force clicks, and broad selectors used to hide timing or identity defects.
- Flag production credentials, captured auth state, or customer data.
- Require a requirement or defect ID for changed critical-path coverage.
- Cite the changed line and explain the false-green or security path.
- Do not block on formatting that lint already enforces.

Background-Agent Capstone: Repair One Login Test

Use a synthetic failure to demonstrate the complete Cursor workflow while keeping remote execution, product behavior, verification, and acceptance bounded.

Background agents run remotely in an isolated environment and work from a repository branch. That convenience comes with elevated terminal and network risk. Use only a disposable exercise repository, synthetic credentials, narrow integrations, and a branch that cannot deploy.

The capstone begins with a product that correctly exposes a Sign in button and a stale test that searches for Login. The allowed correction surface is the one test file. The product fixture, requirement, assertions, and verification commands are protected.

Goal: restore tests/login.spec.ts without changing product behavior.
Evidence: Playwright locator error plus AUTH-01 requirement.
Mutable: tests/login.spec.ts only.
Protected: app/**, requirements/**, playwright.config.ts, test count, dashboard assertion.
Checks:
  1. git diff --check
  2. npm run lint
  3. npx playwright test tests/login.spec.ts --project=chromium --repeat-each=2
Stop: any new failure class, protected-path diff, or ambiguous requirement.
Decision: human reviewer accepts or rejects the branch.

Required evidence package

1. Save the original red failure and confirm the product requirement independently.
2. Commit the applicable Cursor rule and task contract.
3. Run the agent in the disposable branch and inspect every command it executes.
4. Preserve the diff, lint result, repeated focused result, and unchanged assertion count.
5. Have another SDET reproduce the checks and record accept, reject, or revise.