e2e-testing

name	e2e-testing
description	Guides the creation of Playwright E2E tests from planning through implementation. Covers test plan creation, data seeding, Page Object Model development, and test writing with human checkpoints at each stage.
disable-model-invocation	true

Writing E2E Tests

Before starting, read .cursor/skills/e2e-testing/REFERENCE.md for project-specific patterns, application context, POM rules, assertion conventions.

Pre-flight checks

Run these before starting any test work:

# 1. Verify playwright-cli is installed
playwright-cli --version

# 2. Verify Playwright version is 1.59 or higher
npx playwright --version

# 3. Ensure playwright-cli skills are installed
playwright-cli install --skills

# 4. Session name — use -s=<output> for all playwright-cli calls this run
node -e "console.log('e2e-' + Date.now())"

If playwright-cli is not found, install it by running these two commands separately (chaining with && can fail on Windows):

npm install -g @playwright/cli@latest
playwright-cli install --skills

Use the output from step 4 as your -s= value for every playwright-cli call this run.

---

Create Playwright end-to-end tests for a feature or workflow, from plan through passing tests. Follow this workflow step by step. Stop after each step and check in with the user before proceeding.

Workflow checklist

E2E Test Progress:
- [ ] Step 1: Create the test plan
- [ ] Step 2: Seed test data (skip if not needed)
- [ ] Step 3: Create/update Page Object Models
- [ ] Step 4: Write the tests

Step 1: Create the test plan

Read and analyze the feature or workflow to be tested. Identify key interaction points, required test data, page objects, and test scenarios.

If the user provides specific test scenarios, use ONLY those. Do not invent additional scenarios.

Present the plan in chat using this structure:

# Test Plan for [Feature]
[Overview]

## Setup Required
- [Entity]: [Quantity], [Attributes], [Relationships]

## POM Modifications & Creations
- [Page Object]: [Changes or new methods needed]

## Test Cases to Implement
- **[Test Case]**: [Description]
  - Steps: [Numbered steps]
  - Expected Result: [Outcome]

Include exact data requirements — quantities, attributes, relationships. Use timestamps in test identifiers to avoid conflicts. Do NOT write the plan to a file. Document assumptions about existing system state.

-> STOP. Present the plan. Confirm scope, test cases, and data requirements with the user before proceeding.

Step 2: Seed test data

Skip if the test plan requires no new data. Tell the user immediately and move to Step 3.

1. Read and review the existing API helper methods in the project's test helpers lib/helpers or data factory directories lib/datafactory.
2. If the needed entity type isn't supported, extend the data factory helpers with a TypeScript interface and creation method.
3. Create a test spec file that seeds the data with meaningful, varied values and console logging for visibility.
4. Run the seed to verify data creation.

-> STOP. Confirm data was created successfully or that this step was skipped. Share a summary of what was seeded.

Step 3: Create/update Page Object Models

1. Read existing POM files to identify what can be reused or extended. Review current locator strategies.

2. For each page/component in the plan, create or update a POM class.

3. Use playwright-cli to validate locators against the live app — open a session, navigate to the page, and snapshot to confirm elements exist. If locators need discovery, explore the feature: snapshot before AND after each key interaction (dialogs, dropdowns, forms), then capture a recommended locator for each element. Test reliability — verify each locator selects exactly one element across 2-3 attempts.

   # Open a session (reuse the e2e-<n> name from pre-flight for every call)
   playwright-cli -s=$SESSION open <url>
   playwright-cli -s=$SESSION snapshot
   
   # Interact, then snapshot the new state to capture revealed elements
   playwright-cli -s=$SESSION click <element description>
   playwright-cli -s=$SESSION snapshot
   playwright-cli -s=$SESSION fill <element description> <value>
   playwright-cli -s=$SESSION snapshot
   
   # Generate a recommended Playwright locator for an element
   playwright-cli -s=$SESSION generate-locator <ref> --raw
   
   # Optionally open the dashboard to review the live page with the user
   playwright-cli -s=$SESSION show
   
   playwright-cli -s=$SESSION close
   

4. Document assumptions about page state or prerequisites.

Locator priority: getByRole > getByLabel > getByTestId > CSS (last resort). Never use auto-generated classes (e.g., css-1x2y3z).

Follow the Page Object Pattern in REFERENCE.md for the exact POM template and rules.

-> STOP. Present the POM classes. Review locator strategies and method signatures with the user.

Step 4: Write the tests

1. Read the test plan to identify the specific test case to implement.
2. Read the relevant POMs to understand available methods.
3. Write the test. Do NOT reference application source code to generate locators — use only what the POMs provide and what playwright-cli verified.
4. Run the tests to confirm they pass.

-> STOP. Share test results. Confirm the test passes and covers the intended scenario.

Critical rules

• Plan stays in chat, never written to a file
• If user provides test scenarios, use ONLY those — no extras
• Timestamps in test identifiers for isolation
• Validate locators via playwright-cli live verification, not by reading source code
• Reuse the same -s=<session> name for every playwright-cli call in a run; close it when done
• Run tests after seeding data AND after writing tests
• Set realistic scope — avoid feature creep

Anti-patterns

• Generating locators by reading application source code
• Using auto-generated CSS classes as selectors
• Using positional selectors (nth-child) or exact text matches
• Putting business logic in Page Object Models
• Writing the test plan to a file instead of keeping it in chat
• Inventing test scenarios when the user provided specific ones