# Test Generation

> **When to use**: Generating Playwright test code from interactive CLI sessions — recording user flows, building test scaffolds, converting manual testing into automated tests.
> **Prerequisites**: [core-commands.md](core-commands.md) for basic CLI usage

## Quick Reference

```bash
# Every CLI action outputs the equivalent Playwright code
playwright-cli open https://example.com/login
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
# Output: await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

playwright-cli fill e2 "password123"
# Output: await page.getByRole('textbox', { name: 'Password' }).fill('password123');

playwright-cli click e3
# Output: await page.getByRole('button', { name: 'Sign In' }).click();
```

## How It Works

Every action you perform with `playwright-cli` automatically generates the corresponding Playwright TypeScript code in the output. This code uses the same **role-based locators** that Playwright recommends for production tests.

The workflow:

1. **Open a page** → generates `await page.goto(url)`
2. **Take a snapshot** → see element refs and their accessible roles
3. **Interact** → each action generates one line of Playwright code
4. **Collect the code** → assemble generated lines into a complete test

## Recording a Flow

### Example: Login Flow

```bash
playwright-cli open https://example.com/login
# Ran Playwright code:
# await page.goto('https://example.com/login');

playwright-cli snapshot
# Output:
# e1 [textbox "Email"]
# e2 [textbox "Password"]
# e3 [button "Sign In"]
# e4 [link "Forgot password?"]

playwright-cli fill e1 "user@example.com"
# Ran Playwright code:
# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

playwright-cli fill e2 "password123"
# Ran Playwright code:
# await page.getByRole('textbox', { name: 'Password' }).fill('password123');

playwright-cli click e3
# Ran Playwright code:
# await page.getByRole('button', { name: 'Sign In' }).click();
```

### Assemble into a Test

Collect the generated code and wrap it in a Playwright test:

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

test('user can log in', async ({ page }) => {
  await page.goto('https://example.com/login');
  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
  await page.getByRole('button', { name: 'Sign In' }).click();

  // Add assertions (not generated — you add these)
  await expect(page).toHaveURL(/.*dashboard/);
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});
```

```javascript
const { test, expect } = require('@playwright/test');

test('user can log in', async ({ page }) => {
  await page.goto('https://example.com/login');
  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
  await page.getByRole('button', { name: 'Sign In' }).click();

  await expect(page).toHaveURL(/.*dashboard/);
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});
```

## Locator Strategies in Generated Code

The generated code uses Playwright's recommended locator hierarchy:

| Priority | Locator Type | Example | When used |
|----------|-------------|---------|-----------|
| 1 | Role-based | `getByRole('button', { name: 'Submit' })` | Elements with ARIA roles |
| 2 | Label-based | `getByLabel('Email')` | Form inputs with labels |
| 3 | Placeholder | `getByPlaceholder('Search...')` | Inputs with placeholder text |
| 4 | Text-based | `getByText('Welcome back')` | Static text content |
| 5 | Test ID | `getByTestId('submit-btn')` | Elements with `data-testid` |

These locators are **resilient to markup changes** — they mirror how users perceive the page rather than relying on CSS selectors or XPath.

## Recording Complex Flows

### E-Commerce Checkout

```bash
playwright-cli open https://shop.example.com

# Browse products
playwright-cli snapshot
playwright-cli click e5                # "Add to Cart" button
# await page.getByRole('button', { name: 'Add to Cart' }).click();

playwright-cli click e12               # Cart icon
# await page.getByRole('link', { name: 'Cart' }).click();

playwright-cli snapshot
playwright-cli click e3                # "Proceed to Checkout"
# await page.getByRole('button', { name: 'Proceed to Checkout' }).click();

# Shipping info
playwright-cli snapshot
playwright-cli fill e1 "Jane Doe"
# await page.getByRole('textbox', { name: 'Full Name' }).fill('Jane Doe');
playwright-cli fill e2 "123 Main St"
# await page.getByRole('textbox', { name: 'Address' }).fill('123 Main St');
playwright-cli fill e3 "Springfield"
# await page.getByRole('textbox', { name: 'City' }).fill('Springfield');
playwright-cli select e4 "IL"
# await page.getByRole('combobox', { name: 'State' }).selectOption('IL');
playwright-cli fill e5 "62701"
# await page.getByRole('textbox', { name: 'ZIP Code' }).fill('62701');
playwright-cli click e6               # "Continue to Payment"
```

### Multi-Step Wizard

```bash
playwright-cli open https://example.com/onboarding

# Step 1
playwright-cli snapshot
playwright-cli fill e1 "Acme Corp"
playwright-cli select e2 "technology"
playwright-cli click e3    # Next

# Step 2
playwright-cli snapshot
playwright-cli check e1    # Feature checkbox
playwright-cli check e3    # Another feature
playwright-cli click e5    # Next

# Step 3
playwright-cli snapshot
playwright-cli click e2    # "Complete Setup"
```

### Search with Dynamic Results

```bash
playwright-cli open https://example.com
playwright-cli snapshot

playwright-cli fill e1 "playwright testing"
# await page.getByRole('searchbox', { name: 'Search' }).fill('playwright testing');

playwright-cli press Enter
# await page.keyboard.press('Enter');

playwright-cli snapshot    # See search results — new refs assigned

playwright-cli click e3    # First result
# await page.getByRole('link', { name: 'Getting Started with Playwright' }).click();
```

## Adding Assertions

Generated code captures **actions** but not **assertions**. Always add assertions manually to create meaningful tests.

### Common Assertions to Add

```typescript
// URL changed after navigation
await expect(page).toHaveURL(/.*dashboard/);
await expect(page).toHaveURL('https://example.com/success');

// Element is visible
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
await expect(page.getByText('Order confirmed')).toBeVisible();

// Element contains text
await expect(page.getByTestId('total')).toHaveText('$99.99');
await expect(page.getByRole('alert')).toContainText('saved');

// Element has specific attribute
await expect(page.getByRole('button', { name: 'Submit' })).toBeDisabled();
await expect(page.getByRole('checkbox')).toBeChecked();

// Element count
await expect(page.getByRole('listitem')).toHaveCount(5);

// Page title
await expect(page).toHaveTitle(/Dashboard/);

// Screenshot comparison
await expect(page).toHaveScreenshot('checkout.png');
```

### Where to Place Assertions

```typescript
test('complete checkout flow', async ({ page }) => {
  await page.goto('https://shop.example.com/products');

  // Action: Add item to cart
  await page.getByRole('button', { name: 'Add to Cart' }).click();

  // Assertion: Cart badge updates
  await expect(page.getByTestId('cart-count')).toHaveText('1');

  // Action: Go to cart
  await page.getByRole('link', { name: 'Cart' }).click();

  // Assertion: Correct page
  await expect(page).toHaveURL(/.*cart/);
  await expect(page.getByRole('heading', { name: 'Your Cart' })).toBeVisible();

  // Action: Proceed to checkout
  await page.getByRole('button', { name: 'Checkout' }).click();

  // Action: Fill shipping
  await page.getByRole('textbox', { name: 'Full Name' }).fill('Jane Doe');
  await page.getByRole('textbox', { name: 'Address' }).fill('123 Main St');
  await page.getByRole('button', { name: 'Place Order' }).click();

  // Assertion: Order confirmed
  await expect(page.getByText('Order confirmed')).toBeVisible();
  await expect(page.getByTestId('order-number')).toBeVisible();
});
```

## Best Practices

### 1. Explore Before Recording

Take a snapshot first to understand the page structure. Don't blindly click — know what elements are available:

```bash
playwright-cli open https://example.com
playwright-cli snapshot
# Review the elements, plan your flow, then start interacting
```

### 2. Use Semantic Locators

The generated code already prefers role-based locators. If you see CSS selectors in generated output, consider filing an issue — role-based locators are more resilient:

```typescript
// Generated (good — semantic, resilient)
await page.getByRole('button', { name: 'Submit' }).click();

// Avoid writing manually (fragile — breaks if CSS changes)
await page.locator('#submit-btn').click();
await page.locator('.btn.btn-primary').click();
```

### 3. Keep Tests Focused

One test = one user behavior. Don't record an entire session into a single test:

```typescript
// Good: Focused test
test('user can add item to cart', async ({ page }) => {
  // Just the add-to-cart flow
});

test('user can complete checkout', async ({ page }) => {
  // Just the checkout flow (use auth state to skip login)
});

// Bad: Monolith test
test('user journey', async ({ page }) => {
  // Login + browse + add to cart + checkout + verify email...
});
```

### 4. Parameterize Test Data

Replace hardcoded values from the recording with variables or test data:

```typescript
// Instead of hardcoded values from recording
test('registration', async ({ page }) => {
  const user = {
    name: 'Jane Doe',
    email: `test+${Date.now()}@example.com`,
    password: 'SecurePass123!'
  };

  await page.goto('/register');
  await page.getByRole('textbox', { name: 'Name' }).fill(user.name);
  await page.getByRole('textbox', { name: 'Email' }).fill(user.email);
  await page.getByRole('textbox', { name: 'Password' }).fill(user.password);
  await page.getByRole('button', { name: 'Create Account' }).click();

  await expect(page).toHaveURL(/.*welcome/);
});
```

### 5. Add Wait Strategies for Flaky Steps

If a recorded action depends on async content loading, add explicit waits:

```typescript
// Before clicking a dynamically loaded element
await page.waitForSelector('.results-loaded');
await page.getByRole('link', { name: 'First Result' }).click();

// Or use Playwright's auto-waiting (preferred)
await expect(page.getByRole('link', { name: 'First Result' })).toBeVisible();
await page.getByRole('link', { name: 'First Result' }).click();
```

## Tips

- **Generated code is a starting point** — always review, add assertions, and parameterize before committing to your test suite
- **Re-snapshot after dynamic changes** — refs change when the DOM updates
- **Combine with `state-save`** — record a login flow once, save state, then start all other recordings from the authenticated state
- **Use `--filename` for snapshots** — save before/after snapshots for complex flows to help write assertions later