e2e-playwright-testing

End-to-End Playwright Test Creation and Management

<core_mandate> CRITICAL: You MUST use all three sub-agents in the specified order for ANY E2E test work. Never write, modify, or debug E2E tests directly. Always delegate to the appropriate sub-agent.

The three required sub-agents are:

1. playwright-test-planner - Creates comprehensive test plans focusing on USER JOURNEYS.
2. playwright-test-generator - Implements automated browser tests using DOM INTERACTIONS.
3. playwright-test-healer - Debugs and fixes failing tests.

You must ALWAYS use ALL 3 agents IN SEQUENCE according to the phases below. </core_mandate>

Three-Phase Testing Workflow

Phase 1: Planning (MANDATORY FIRST STEP)

<phase_1> Action: Invoke the playwright-test-planner sub-agent

Purpose: Create a comprehensive test plan that mimics a human user.

Required Information to Provide:

• Subject Under Test (SUT): Clearly define what specific feature is being tested.
• User Journey: The exact sequence of clicks, inputs, and navigations a human would perform.
• Pre-conditions: What state must exist before the user starts (these can be set up via API/Helpers).
• Success Criteria: Visual confirmation in the UI (not just DB checks).

Critical Distinction:

• If the SUT is "Create User", the plan MUST involve clicking the "Create User" button and filling the form.
• If the SUT is "User Dashboard", the plan MAY use an API helper to create the user/login, but MUST use the UI to view the dashboard.

Output: A detailed test plan document that serves as a script for the Generator. </phase_1>

Phase 2: Implementation (EXECUTE ONLY AFTER PHASE 1)

<phase_2> Action: Invoke the playwright-test-generator sub-agent

Purpose: Implement the test plan as executable Playwright test code.

Guiding Principles for Generation:

• Prefer UI over API: Use page.click(), page.fill(), and page.getByRole() for the primary test actions.
• Visual Assertions: Use expect(locator).toBeVisible() or expect(locator).toHaveText() rather than asserting on variable state.
• Accessibility First: Use specific locators (getByRole, getByLabel) over generic CSS/XPath selectors to ensure the UI is accessible.

Output: Working Playwright test files in the e2e/ folder. </phase_2>

Phase 3: Healing and Validation

<phase_3> Action: Invoke the playwright-test-healer sub-agent

Purpose: Run tests, identify failures, and automatically fix issues.

Healer Strategy:

• If a test fails because a selector changed, update the selector.
• If a test fails because the UI behavior changed (e.g., a new confirmation modal), update the test steps to handle the new UI.
• DO NOT "fix" a test by bypassing the UI and calling an API instead. The failure might be a legitimate bug in the UI.

Output: Passing tests or a request for human intervention. </phase_3>

The "Real User" Simulation Rule

<simulation_rules>

1. No Shortcuts for the SUT: If the test title is "User can update profile", the test MUST navigate to the profile page and type in the input fields. It MUST NOT send a POST request to /api/user/profile.
2. Visible Feedback: Assertions should check what the user sees (Toasts, text updates, element visibility), not invisible database states, unless specifically required for data integrity checks.
3. Black Box Testing: Treat the application as a black box. Do not import application code (React components, backend models) into the test file. Test the deployed DOM. </simulation_rules>

Absolute Requirements

<absolute_requirements>

1. Sequential Execution: Plan → Generate → Heal.
2. No Skipped Tests: Use e2e/helper/ to ensure infrastructure is ready so tests don't need skipping.
3. 100% Pass Rate Goal. </absolute_requirements>

Output Requirements

<output_requirements>

1. Test Files: Created in e2e/.
2. Inline Summaries: Brief updates after each phase. </output_requirements>

<incorrect_approach> Bad Plan/Implementation:

1. Admin logs in.
2. Test calls api.post('/members', { name: 'John' }).
3. Test reloads page.
4. Expect 'John' to be on page.

Why this is bad: It tests the API and the List View, but it completely ignores the "Create Member" UI form, which is the primary feature being tested. </incorrect_approach>

<correct_approach> Phase 1 - Planning:

• SUT: Create Team Member Form.
• Pre-condition: Logged in as Admin (can use auth.loginWithApi() helper).
• User Flow:
  1. Navigate to 'Team' page.
  2. Click 'Add Member' button.
  3. Wait for modal/drawer.
  4. Fill 'Name' with 'John'.
  5. Select 'Role' dropdown.
  6. Click 'Save'.
• Assertion: Verify 'John' appears in the list and success toast is shown.

Phase 2 - Implementation:

test('Admin can create team member via UI', async ({ page, authHelper }) => {
  // Setup: We aren't testing login, so API login is fine here
  await authHelper.loginAsAdmin(); 
  
  // Action: We ARE testing member creation, so use UI
  await page.goto('/team');
  await page.getByRole('button', { name: 'Add Member' }).click();
  await page.getByLabel('Name').fill('John Doe');
  await page.getByRole('combobox', { name: 'Role' }).click();
  await page.getByRole('option', { name: 'Editor' }).click();
  await page.getByRole('button', { name: 'Save' }).click();

  // Assert: Visual confirmation
  await expect(page.getByText('Member created successfully')).toBeVisible();
  await expect(page.getByRole('row', { name: 'John Doe' })).toBeVisible();
});

</correct_approach>

<reasoning_guidance> When defining the test plan:

1. Ask: "What is the primary thing being tested?"
2. If it is a feature (e.g., "Search"), the test must use the feature (type in search box), not bypass it (filtering API response).
3. Only use API shortcuts for setup (creating data needed for the test) or teardown. Never use them for the act of the test. </reasoning_guidance>