@assertrx/dino 1.0.0

package/skills/playwright-cli/test-generation.md

@@ -0,0 +1,336 @@
+# 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