E2e Playwright Testing

---
name: e2e-playwright-testing
description: Comprehensive end-to-end test creation, and management. You MUST activate this skill when the user mentions "e2e", "end-to-end", "playwright", or any work involving the `e2e/` folder.
---

# End-to-End Playwright Test Creation and Management

<purpose>
This skill guides you through a systematic three-phase approach for creating, implementing, and healing end-to-end Playwright tests. 
CRITICAL OBJECTIVE: These tests must simulate REAL USER BEHAVIOR. You must distinguish between "Integration/E2E" tests (which use the UI) and "Unit" tests (which use code). 
Tests generated by this skill MUST interact with the DOM (click, type, scroll) to achieve their goals, rather than relying on backend API calls or configuration injection, unless specifically setting up pre-conditions not under test.
</purpose>

<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>

<instructions>

## 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>

</instructions>

<constraints>

## 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>

</constraints>

<examples>

<example>
<scenario>User requests: "Test that an admin can create a new team member"</scenario>

<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**:
```typescript
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>
</example>

</examples>

<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>