1# Test Generation
2 
3Generate Playwright test code automatically as you interact with the browser.
4 
5## How It Works
6 
7Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
8This code appears in the output and can be copied directly into your test files.
9 
10## Example Workflow
11 
12```bash
13# Start a session
14playwright-cli open https://example.com/login
15 
16# Take a snapshot to see elements
17playwright-cli snapshot
18# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
19 
20# Fill form fields - generates code automatically
21playwright-cli fill e1 "[email protected]"
22# Ran Playwright code:
23# await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');
24 
25playwright-cli fill e2 "password123"
26# Ran Playwright code:
27# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
28 
29playwright-cli click e3
30# Ran Playwright code:
31# await page.getByRole('button', { name: 'Sign In' }).click();
32```
33 
34## Building a Test File
35 
36Collect the generated code into a Playwright test:
37 
38```typescript
39import { test, expect } from '@playwright/test';
40 
41test('login flow', async ({ page }) => {
42  // Generated code from playwright-cli session:
43  await page.goto('https://example.com/login');
44  await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');
45  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
46  await page.getByRole('button', { name: 'Sign In' }).click();
47 
48  // Add assertions
49  await expect(page).toHaveURL(/.*dashboard/);
50});
51```
52 
53## Best Practices
54 
55### 1. Use Semantic Locators
56 
57The generated code uses role-based locators when possible, which are more resilient:
58 
59```typescript
60// Generated (good - semantic)
61await page.getByRole('button', { name: 'Submit' }).click();
62 
63// Avoid (fragile - CSS selectors)
64await page.locator('#submit-btn').click();
65```
66 
67### 2. Explore Before Recording
68 
69Take snapshots to understand the page structure before recording actions:
70 
71```bash
72playwright-cli open https://example.com
73playwright-cli snapshot
74# Review the element structure
75playwright-cli click e5
76```
77 
78### 3. Add Assertions Manually
79 
80Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
81 
82- `toBeVisible()` — element is rendered and visible
83- `toHaveText(text)` — element text content matches
84- `toHaveValue(value) / toBeEmpty()` — input/select value matches
85- `toBeChecked() / toBeUnchecked()` — checkbox state matches
86- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
87 
88Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
89 
90When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
91 
92Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
93 
94```bash
95# Get a stable locator for an element ref to use in the assertion
96playwright-cli --raw generate-locator e5
97# getByRole('button', { name: 'Submit' })
98 
99# Capture expected text content for toHaveText
100playwright-cli --raw eval "el => el.textContent" e5
101 
102# Capture expected input value for toHaveValue/toBeEmpty
103playwright-cli --raw eval "el => el.value" e5
104 
105# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
106# (whole page, or use a ref to scope to a region)
107playwright-cli --raw snapshot
108playwright-cli --raw snapshot e5
109```
110 
111```typescript
112// Generated action
113await page.getByRole('button', { name: 'Submit' }).click();
114 
115// Manual assertions using the outputs above:
116await expect(page.getByRole('alert', { name: 'Success' })).toBeVisible();
117await expect(page.getByTestId('main-header')).toHaveText('Welcome, user');
118await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('[email protected]');
119await expect(page.getByRole('checkbox', { name: 'Enable notifications' })).toBeChecked();
120 
121// toMatchAriaSnapshot on the whole page, finds a matching region
122await expect(page).toMatchAriaSnapshot(`
123  - heading "Welcome, user"
124  - link /\\d+ new messages?/
125  - button "Sign out"
126`);
127 
128// toMatchAriaSnapshot scoped to a region
129await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`
130  - link "Home"
131  - link /\\d+ new messages?/
132  - link "Profile"
133`);
134```
135