generate

---
name: generate
description: Use when generating production-ready Playwright tests from user stories, URLs, components, or feature descriptions.
category: Engineering
version: 1.0.0
tools: []
---

# Generate Playwright Tests

Create production-ready Playwright tests from user stories, features, or components.

## Input

Parse arguments to determine:
- User story: behavior to verify
- Component path: read source to understand props/states/interactions
- Page/URL: identify route and elements
- Feature name: map to app areas

## Explore Codebase

- Read `playwright.config.ts` for testDir, baseURL, projects
- Check existing tests for patterns, fixtures, conventions
- Read components to understand their structure
- Check for page objects in `pages/`
- Check fixtures in `fixtures/`
- Check auth setup in `auth.setup.ts`

## Test Structure

```typescript
import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test('should <expected behavior>', async ({ page }) => {
    // Arrange
    // Act
    // Assert
  });
});
```

## Locator Priority

1. `getByRole()` — buttons, links, headings, form elements
2. `getByLabel()` — form fields with labels
3. `getByText()` — text content
4. `getByPlaceholder()` — input placeholder
5. `getByTestId()` — when semantic options fail

## Assertions (web-first, auto-retry)

```typescript
// GOOD
await expect(page.getByRole('heading')).toBeVisible();

// BAD (no retry)
const text = await page.textContent('.msg');
```

## Never Use

- `waitForTimeout()`
- `page.$(selector)` or `page.$$(selector)`
- Bare CSS selectors (unless necessary)
- `page.evaluate()` for locator tasks

## Always Include

- Descriptive test names explaining behavior
- Error/edge case tests alongside happy path
- `await` on every Playwright call
- baseURL-relative navigation (`page.goto('/')`)

## Match Project Conventions

- TypeScript → `.spec.ts`, JavaScript → `.spec.js`
- Use page objects if project has them
- Use custom fixtures if defined
- Use project's test data directory

## Supporting Files

- **Page object**: if test touches 5+ locators on one page
- **Fixture**: if test needs shared setup (auth, data)
- **Test data**: JSON file in test-data/ if structured data used

## Verify

```bash
npx playwright test <file> --reporter=list
```

Test must pass. If app issue, report it.