| 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
The three required sub-agents are:
- playwright-test-planner - Creates comprehensive test plans focusing on USER JOURNEYS.
- playwright-test-generator - Implements automated browser tests using DOM INTERACTIONS.
- playwright-test-healer - Debugs and fixes failing tests.
You must ALWAYS use ALL 3 agents IN SEQUENCE according to the phases below.
Three-Phase Testing Workflow
Phase 1: Planning (MANDATORY FIRST STEP)
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 2: Implementation (EXECUTE ONLY AFTER PHASE 1)
Purpose: Implement the test plan as executable Playwright test code.
Guiding Principles for Generation:
- Prefer UI over API: Use
page.click(),page.fill(), andpage.getByRole()for the primary test actions. - Visual Assertions: Use
expect(locator).toBeVisible()orexpect(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 3: Healing and Validation
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.
The "Real User" Simulation Rule
Absolute Requirements
Output Requirements
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.
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();
});