E2e Playwright Testing

End-to-End Playwright Test Creation and Management

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.

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(), 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 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();
});