generate-e2e-test

name	generate-e2e-test
description	Generate Playwright E2E tests from user stories or manual workflows; explore flow interactively before writing code.
argument-hint	Write/paste your workflow description here along with hints about where to write the code.
allowed-tools	mcp__Playwright_browser_click, mcp__Playwright_browser_console_messages, mcp__Playwright_browser_drag, mcp__Playwright_browser_evaluate, mcp__Playwright_browser_file_upload, mcp__Playwright_browser_fill_form, mcp__Playwright_browser_handle_dialog, mcp__Playwright_browser_hover, mcp__Playwright_browser_navigate, mcp__Playwright_browser_navigate_back, mcp__Playwright_browser_network_requests, mcp__Playwright_browser_press_key, mcp__Playwright_browser_resize, mcp__Playwright_browser_select_option, mcp__Playwright_browser_snapshot, mcp__Playwright_browser_take_screenshot, mcp__Playwright_browser_type, mcp__Playwright_browser_wait_for, mcp__Playwright_browser_mouse_click_xy, mcp__Playwright_browser_mouse_drag_xy, mcp__Playwright_browser_mouse_move_xy, mcp__Playwright_browser_verify_element_visible, mcp__Playwright_browser_verify_text_visible, mcp__Playwright_browser_verify_value, Read, Write, Edit, Grep, Glob, Bash, TodoWrite

Generate E2E Test

This Skill converts workflow descriptions into working automated end-to-end tests by first performing the workflow step-by-step using Playwright MCP browser tools, then generating and refining test code based on the actual interaction.

Overview

Convert the following workflow description into working automated tests:

$ARGUMENTS

Process

1. Initial Setup

• Start Playwright MCP browser session using browser_navigate to target URL
• Ask the user to authenticate and perform any initialization steps if needed (there are likely already helper methods in the project test platform files for this)
• Take initial snapshot using browser_snapshot to understand page structure and confirm readiness to begin with the user

2. Manual Workflow Execution

For each step in the described workflow:

Capture state: Use browser_snapshot before each interaction to understand the current page structure

Perform action: Execute using appropriate MCP tools:

• browser_click - Click buttons, links, or elements
• browser_type - Type text into fields
• browser_fill_form - Fill multiple form fields at once
• browser_select_option - Select from dropdowns
• browser_press_key - Press keyboard keys
• Other browser tools as needed

Collect selectors:

• Primary: Note ref values from accessibility snapshots (most stable)
• Fallback: Use browser_evaluate with queries like document.querySelector('[data-testid="..."]') if needed

Verify outcomes: Use browser_wait_for or snapshot to confirm expected results after each action

Document: Track successful selector patterns and interaction sequences for test generation

3. Generate Test Code

Read project conventions: Review TESTING.md for:

• Test runner setup and syntax
• Available helper methods and fixtures
• Assertion patterns
• File naming and location conventions

Write test spec: Transform recorded workflow into test code using:

• Collected selectors (prefer stable attributes: data-testid, aria-label, role+name)
• Project's testing patterns from TESTING.md
• Appropriate waits and assertions
• Helper methods from tests/e2e/utils/test-helpers.ts

File location: Place test in appropriate directory under tests/e2e/ based on feature area:

• tests/e2e/admin/ - Super admin features
• tests/e2e/auth/ - Authentication flows
• tests/e2e/client/ - Client-specific features
• tests/e2e/dashboard/ - Dashboard pages
• tests/e2e/marketing/ - Public pages
• tests/e2e/workouts/ - Workout features

4. Validate & Refine

Run test: Execute using project's test command from TESTING.md:

pnpm test:e2e:ai tests/e2e/your-test.spec.ts

Debug failures:

• If selector issues: Return to MCP browser, use browser_snapshot and browser_evaluate to find better selectors
• If timing issues: Add appropriate waits using waitForElementWithRetry or similar helpers
• If assertion failures: Verify expected values using MCP tools

Iterate: Repeat debugging until test passes consistently

Key MCP Tools Usage

Discovery:

• browser_snapshot (primary) - Get page structure and element information
• browser_evaluate (for complex queries) - Execute JavaScript to query DOM

Actions:

• browser_click - Click elements
• browser_type - Type text
• browser_fill_form - Fill multiple form fields
• browser_select_option - Select dropdown options
• browser_press_key - Press keyboard keys

Validation:

• browser_wait_for - Wait for elements or conditions
• browser_verify_* tools - Verify element visibility, text, and values

Debugging:

• browser_console_messages - Check console errors
• browser_network_requests - Inspect network activity
• browser_take_screenshot - Capture visual state

Best Practices

Selector Strategy

• Prefer accessibility-based selectors (role, aria-label) over fragile CSS
• Use test utilities like getByRole(), getByText(), getByLabel() from Playwright
• Always verify selectors return only a single element to avoid strict mode violations
• Check if actions are in dropdown menus (look for "More actions" buttons)

Waiting and Timing

• Always wait for elements/text after navigation or async operations
• Use helper methods like waitForElementWithRetry() for robust waiting
• For table data: Use waitForTableLoaded(page) before interacting with table elements

Test Structure

• Use fixtures from tests/e2e/fixtures.ts for pre-configured test data
• Test both happy path and error conditions when specified
• Scope selectors to specific containers to avoid matching toast notifications
• Clean up test data using protected email patterns (e2e-*@example.com)

Navigation

• Use navigateToPage() helper instead of page.goto() for reliable client-side routing
• Wait for content-based conditions, not just domcontentloaded

Examples

Simple Form Test

import { test, expect } from './fixtures'
import { navigateToPage, expectToast } from './utils/test-helpers'

test('user can create exercise', async ({ page, superAdminUser }) => {
  await navigateToPage(page, '/super-admin/exercises')

  await page.getByRole('button', { name: 'Add Exercise' }).click()
  await page.getByLabel('Name').fill('Bench Press')
  await page.getByLabel('Muscle Group').selectOption('Chest')

  await page.getByRole('button', { name: 'Save' }).click()
  await expectToast(page, 'Exercise created successfully')
})

Workflow with Dropdown Menu

test('user can delete exercise', async ({ page, superAdminUser }) => {
  await navigateToPage(page, '/super-admin/exercises')

  // Open dropdown menu first
  const row = page.locator('tr').filter({ hasText: 'Bench Press' })
  await row.locator('[aria-label*="More actions"]').click()

  // Then select delete action
  await page.getByRole('menuitem', { name: 'Delete' }).click()
  await page.getByRole('button', { name: 'Confirm' }).click()

  await expectToast(page, 'Exercise deleted successfully')
})

Requirements

• Playwright MCP server must be running and connected
• Development server should be running at http://localhost:3000
• Project must have TESTING.md and test utilities configured

Troubleshooting

If tests fail:

1. Read the AI Coding Agent Reporter output in test-report-for-coding-agents/all-failures.md
2. Check console logs using browser_console_messages
3. Inspect DOM structure with browser_snapshot
4. Verify network requests with browser_network_requests
5. Take screenshots at failure points with browser_take_screenshot

If stuck debugging, ask a human to inspect the Playwright trace in playwright-report/ which contains detailed execution information.