@assertrx/dino 1.0.0

package/skills/playwright-core/configuration.md

@@ -0,0 +1,731 @@
+# Configuration
+
+> **When to use**: Setting up a new Playwright project, adjusting timeouts, adding browser targets, configuring CI behavior, or connecting environment-specific settings.
+
+## Quick Reference
+
+```
+npx playwright init                    # scaffold config + first test
+npx playwright test --config=custom.config.ts  # use non-default config
+npx playwright test --project=chromium # run single project
+npx playwright test --reporter=html    # override reporter
+npx playwright show-report             # open last HTML report
+DEBUG=pw:api npx playwright test       # verbose Playwright logging
+```
+
+## Production-Ready Config (Copy-Paste Starter)
+
+### TypeScript
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+import dotenv from 'dotenv';
+import path from 'path';
+
+// Load environment variables from .env file
+dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+export default defineConfig({
+  // ── Test discovery ──────────────────────────────────────────────
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+
+  // ── Execution ───────────────────────────────────────────────────
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,       // fail CI if test.only left in
+  retries: process.env.CI ? 2 : 0,    // retry flakes in CI only
+  workers: process.env.CI ? '50%' : undefined, // half CPU in CI, auto locally
+
+  // ── Reporting ───────────────────────────────────────────────────
+  reporter: process.env.CI
+    ? [['html', { open: 'never' }], ['github']]
+    : [['html', { open: 'on-failure' }]],
+
+  // ── Timeouts ────────────────────────────────────────────────────
+  timeout: 30_000,                     // per-test timeout
+  expect: {
+    timeout: 5_000,                    // per-assertion retry timeout
+  },
+
+  // ── Shared browser context options ──────────────────────────────
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    actionTimeout: 10_000,             // click, fill, etc.
+    navigationTimeout: 15_000,         // goto, waitForURL, etc.
+
+    // Artifact collection
+    trace: 'on-first-retry',          // full trace on first retry only
+    screenshot: 'only-on-failure',     // screenshot on failure
+    video: 'retain-on-failure',        // video only kept for failures
+    // 1.61+ adds video modes matching trace: 'on-all-retries',
+    // 'retain-on-first-failure', 'retain-on-failure-and-retries'
+
+    // Sensible defaults
+    locale: 'en-US',
+    timezoneId: 'America/New_York',
+    extraHTTPHeaders: {
+      'x-test-automation': 'playwright',
+    },
+  },
+
+  // ── Projects (browser targets) ─────────────────────────────────
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 7'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  // ── Dev server ──────────────────────────────────────────────────
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,                  // 2 min for cold builds
+    stdout: 'pipe',
+    stderr: 'pipe',
+  },
+});
+```
+
+### JavaScript
+
+```js
+// playwright.config.js
+const { defineConfig, devices } = require('@playwright/test');
+const dotenv = require('dotenv');
+const path = require('path');
+
+dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? '50%' : undefined,
+
+  reporter: process.env.CI
+    ? [['html', { open: 'never' }], ['github']]
+    : [['html', { open: 'on-failure' }]],
+
+  timeout: 30_000,
+  expect: {
+    timeout: 5_000,
+  },
+
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    actionTimeout: 10_000,
+    navigationTimeout: 15_000,
+
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+
+    locale: 'en-US',
+    timezoneId: 'America/New_York',
+    extraHTTPHeaders: {
+      'x-test-automation': 'playwright',
+    },
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 7'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  },
+});
+```
+
+## Patterns
+
+### Pattern 1: Environment-Specific Configuration
+
+**Use when**: Tests run against dev, staging, and production environments.
+**Avoid when**: Single-environment local-only projects.
+
+#### TypeScript
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+import dotenv from 'dotenv';
+import path from 'path';
+
+// Load environment-specific .env file: .env.staging, .env.production, etc.
+const ENV = process.env.TEST_ENV || 'local';
+dotenv.config({ path: path.resolve(__dirname, `.env.${ENV}`) });
+
+const envConfig: Record<string, { baseURL: string; retries: number }> = {
+  local:      { baseURL: 'http://localhost:3000',       retries: 0 },
+  staging:    { baseURL: 'https://staging.example.com', retries: 2 },
+  production: { baseURL: 'https://www.example.com',     retries: 2 },
+};
+
+const env = envConfig[ENV];
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  retries: env.retries,
+  use: {
+    baseURL: env.baseURL,
+  },
+});
+```
+
+```bash
+# Run against staging
+TEST_ENV=staging npx playwright test
+
+# Run against production (subset of smoke tests)
+TEST_ENV=production npx playwright test --grep @smoke
+```
+
+#### JavaScript
+
+```js
+// playwright.config.js
+const { defineConfig } = require('@playwright/test');
+const dotenv = require('dotenv');
+const path = require('path');
+
+const ENV = process.env.TEST_ENV || 'local';
+dotenv.config({ path: path.resolve(__dirname, `.env.${ENV}`) });
+
+const envConfig = {
+  local:      { baseURL: 'http://localhost:3000',       retries: 0 },
+  staging:    { baseURL: 'https://staging.example.com', retries: 2 },
+  production: { baseURL: 'https://www.example.com',     retries: 2 },
+};
+
+const env = envConfig[ENV];
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+  retries: env.retries,
+  use: {
+    baseURL: env.baseURL,
+  },
+});
+```
+
+### Pattern 2: Multi-Project with Setup Dependencies
+
+**Use when**: Tests need shared authentication state or database seeding before running.
+**Avoid when**: Tests are fully independent with no shared setup phase.
+
+#### TypeScript
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+
+  projects: [
+    // Setup project runs first, saves auth state
+    {
+      name: 'setup',
+      testMatch: /global\.setup\.ts/,
+    },
+
+    // Browser projects depend on setup
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        storageState: 'playwright/.auth/user.json',
+      },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'firefox',
+      use: {
+        ...devices['Desktop Firefox'],
+        storageState: 'playwright/.auth/user.json',
+      },
+      dependencies: ['setup'],
+    },
+  ],
+});
+```
+
+```ts
+// tests/global.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  await page.context().storageState({ path: authFile });
+});
+```
+
+#### JavaScript
+
+```js
+// playwright.config.js
+const { defineConfig, devices } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global\.setup\.js/,
+    },
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        storageState: 'playwright/.auth/user.json',
+      },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'firefox',
+      use: {
+        ...devices['Desktop Firefox'],
+        storageState: 'playwright/.auth/user.json',
+      },
+      dependencies: ['setup'],
+    },
+  ],
+});
+```
+
+```js
+// tests/global.setup.js
+const { test: setup, expect } = require('@playwright/test');
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  await page.context().storageState({ path: authFile });
+});
+```
+
+### Pattern 3: `webServer` with Build Step
+
+**Use when**: Tests need a running application server. Let Playwright manage the server lifecycle.
+**Avoid when**: Testing against an already-deployed environment (staging/prod).
+
+#### TypeScript
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  use: {
+    baseURL: 'http://localhost:3000',
+  },
+  webServer: {
+    command: process.env.CI
+      ? 'npm run build && npm run start'  // production build in CI
+      : 'npm run dev',                    // dev server locally
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: {
+      NODE_ENV: 'test',
+      DATABASE_URL: process.env.DATABASE_URL || 'postgresql://localhost:5432/test',
+    },
+  },
+});
+```
+
+#### JavaScript
+
+```js
+// playwright.config.js
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+  use: {
+    baseURL: 'http://localhost:3000',
+  },
+  webServer: {
+    command: process.env.CI
+      ? 'npm run build && npm run start'
+      : 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: {
+      NODE_ENV: 'test',
+      DATABASE_URL: process.env.DATABASE_URL || 'postgresql://localhost:5432/test',
+    },
+  },
+});
+```
+
+### Pattern 4: `globalSetup` / `globalTeardown`
+
+**Use when**: One-time non-browser work: seeding a database, starting a service, setting env vars. Runs once per `npx playwright test` invocation.
+**Avoid when**: You need browser context (use a setup project instead) or per-test isolation (use fixtures).
+
+#### TypeScript
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  globalSetup: './tests/global-setup.ts',
+  globalTeardown: './tests/global-teardown.ts',
+});
+```
+
+```ts
+// tests/global-setup.ts
+import { FullConfig } from '@playwright/test';
+
+async function globalSetup(config: FullConfig) {
+  // Seed test database
+  const { execSync } = await import('child_process');
+  execSync('npx prisma db seed', { stdio: 'inherit' });
+
+  // Store data for tests to use via environment variables
+  process.env.TEST_RUN_ID = `run-${Date.now()}`;
+}
+
+export default globalSetup;
+```
+
+```ts
+// tests/global-teardown.ts
+import { FullConfig } from '@playwright/test';
+
+async function globalTeardown(config: FullConfig) {
+  const { execSync } = await import('child_process');
+  execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
+}
+
+export default globalTeardown;
+```
+
+#### JavaScript
+
+```js
+// playwright.config.js
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+  globalSetup: './tests/global-setup.js',
+  globalTeardown: './tests/global-teardown.js',
+});
+```
+
+```js
+// tests/global-setup.js
+const { execSync } = require('child_process');
+
+async function globalSetup(config) {
+  execSync('npx prisma db seed', { stdio: 'inherit' });
+  process.env.TEST_RUN_ID = `run-${Date.now()}`;
+}
+
+module.exports = globalSetup;
+```
+
+```js
+// tests/global-teardown.js
+const { execSync } = require('child_process');
+
+async function globalTeardown(config) {
+  execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
+}
+
+module.exports = globalTeardown;
+```
+
+### Pattern 5: `.env` File Setup
+
+**Use when**: Managing secrets, URLs, or feature flags without hardcoding.
+**Avoid when**: Never commit `.env` files with real secrets. Provide `.env.example` instead.
+
+```bash
+# .env.example (commit this)
+BASE_URL=http://localhost:3000
+TEST_PASSWORD=
+API_KEY=
+
+# .env.local (gitignored)
+BASE_URL=http://localhost:3000
+TEST_PASSWORD=s3cret
+API_KEY=test-key-abc123
+
+# .env.staging (gitignored)
+BASE_URL=https://staging.example.com
+TEST_PASSWORD=staging-password
+API_KEY=staging-key-xyz789
+```
+
+```bash
+# .gitignore
+.env
+.env.local
+.env.staging
+.env.production
+playwright/.auth/
+```
+
+Install dotenv:
+
+```bash
+npm install -D dotenv
+```
+
+### Pattern 6: Trace, Screenshot, and Video Settings
+
+**Use when**: Deciding artifact collection strategy for local development vs CI.
+
+| Setting | Local | CI | Why |
+|---|---|---|---|
+| `trace` | `'off'` or `'on-first-retry'` | `'on-first-retry'` | Traces are large; only collect on failure |
+| `screenshot` | `'off'` | `'only-on-failure'` | Useful for CI debugging only |
+| `video` | `'off'` | `'retain-on-failure'` | Video is slow to record; keep only failures |
+
+#### TypeScript
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  use: {
+    // CI: capture everything on failure; Local: minimal overhead
+    trace: process.env.CI ? 'on-first-retry' : 'off',
+    screenshot: process.env.CI ? 'only-on-failure' : 'off',
+    video: process.env.CI ? 'retain-on-failure' : 'off',
+  },
+});
+```
+
+#### JavaScript
+
+```js
+// playwright.config.js
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+  use: {
+    trace: process.env.CI ? 'on-first-retry' : 'off',
+    screenshot: process.env.CI ? 'only-on-failure' : 'off',
+    video: process.env.CI ? 'retain-on-failure' : 'off',
+  },
+});
+```
+
+## Decision Guide
+
+### Which Timeout to Adjust
+
+| Symptom | Timeout to Change | Default | Recommended Range |
+|---|---|---|---|
+| Test takes too long overall | `timeout` | 30s | 30-60s (never above 120s) |
+| Assertion `expect()` keeps retrying too long or not long enough | `expect.timeout` | 5s | 5-10s |
+| `page.goto()` or `waitForURL()` times out | `navigationTimeout` | 30s | 10-30s |
+| `click()`, `fill()`, `check()` time out | `actionTimeout` | 0 (no limit) | 10-15s |
+| Dev server slow to start | `webServer.timeout` | 60s | 60-180s |
+
+### Server Management
+
+| Scenario | Approach | Why |
+|---|---|---|
+| Local dev + CI, app in same repo | `webServer` with `reuseExistingServer: !process.env.CI` | Playwright manages server; reuses yours locally |
+| Separate frontend/backend repos | Manual start or Docker Compose | `webServer` can only run one command |
+| Testing deployed staging/production | No `webServer`; set `baseURL` via env var | Server already running remotely |
+| Multiple services needed (API + frontend) | Array of `webServer` entries | Each gets its own command and URL health check |
+
+### Single vs Multi-Project Config
+
+| Scenario | Approach | Why |
+|---|---|---|
+| Starting out, early development | Single project (chromium only) | Faster feedback, simpler config |
+| Pre-release cross-browser validation | Multi-project: chromium + firefox + webkit | Catch rendering/API differences |
+| Mobile-responsive app | Add mobile projects alongside desktop | Viewport + touch differences matter |
+| Authenticated + unauthenticated tests | Setup project + dependent projects | Share auth state without re-login per test |
+| CI pipeline with tight time budget | Chromium in PR checks; all browsers on merge to main | Balance speed vs coverage |
+
+### globalSetup vs Setup Projects vs Fixtures
+
+| Need | Use | Why |
+|---|---|---|
+| One-time DB seed or external service prep | `globalSetup` | Runs once, no browser needed |
+| Shared browser auth (login once, reuse cookies) | Setup project with `dependencies` | Needs browser context; `globalSetup` has none |
+| Per-test isolated state (unique user, fresh data) | Custom fixture via `test.extend()` | Each test gets its own instance with teardown |
+| Cleanup after all tests | `globalTeardown` | Runs once at the end regardless of pass/fail |
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+|---|---|---|
+| `timeout: 300_000` globally | Masks flaky tests; CI runs take forever | Fix the root cause; keep timeout at 30s; raise `navigationTimeout` only if warranted |
+| Hardcoded URLs in tests: `page.goto('http://localhost:3000/login')` | Breaks in every non-local environment | Use `baseURL` in config, then `page.goto('/login')` |
+| Running chromium + firefox + webkit on every PR | 3x CI time for marginal benefit on most PRs | Chromium on PRs; all browsers on main branch merges |
+| `trace: 'on'` always in CI | Huge artifacts, slow uploads, disk full | `trace: 'on-first-retry'` -- only captures when a test fails and retries |
+| `video: 'on'` always in CI | Massive CI storage; recording slows tests | `video: 'retain-on-failure'` -- records all but only keeps failures |
+| Config values inline in test files: `test.use({ viewport: { width: 1280, height: 720 } })` in every file | Scattered, hard to maintain, inconsistent | Define once in project config; override per-file only when genuinely needed |
+| `retries: 3` locally | Hides flakiness during development | `retries: 0` locally, `retries: 2` in CI |
+| No `forbidOnly` in CI | Accidentally committed `test.only` runs a single test, everything else silently skipped | `forbidOnly: !!process.env.CI` |
+| `globalSetup` for browser auth | No browser context available; complex workarounds needed | Use a setup project with `dependencies` |
+| Committing `.env` files with real credentials | Security risk | Commit `.env.example` only; gitignore real `.env` files |
+
+## Troubleshooting
+
+### "baseURL" not working -- tests navigate to full URL
+
+**Cause**: Using `page.goto('http://localhost:3000/path')` instead of `page.goto('/path')`. When `goto` receives an absolute URL, it ignores `baseURL`.
+
+**Fix**: Always pass relative paths to `page.goto()`:
+
+```ts
+// Wrong -- ignores baseURL
+await page.goto('http://localhost:3000/dashboard');
+
+// Correct -- uses baseURL from config
+await page.goto('/dashboard');
+```
+
+### webServer starts but tests still fail with connection refused
+
+**Cause**: The `url` in `webServer` does not match what the server actually serves, or the health check endpoint returns non-200.
+
+**Fix**: Ensure `webServer.url` matches the actual server address. Add a health check route if needed:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000/api/health',  // use a real endpoint
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+### Tests pass locally but timeout in CI
+
+**Cause**: CI machines are slower. Default timeouts too tight for CI hardware.
+
+**Fix**: Increase `navigationTimeout` for CI, reduce `workers` to avoid resource contention:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  workers: process.env.CI ? '50%' : undefined,
+  use: {
+    navigationTimeout: process.env.CI ? 30_000 : 15_000,
+    actionTimeout: process.env.CI ? 15_000 : 10_000,
+  },
+});
+```
+
+### "Error: page.goto: Target page, context or browser has been closed"
+
+**Cause**: Test exceeded its `timeout` and Playwright tore down the browser while an action was still running.
+
+**Fix**: Do not increase the global timeout. Instead, find the slow step using `--trace on` and fix it. Common causes: waiting for a slow API, unresolved network request, or missing `await`.
+
+```bash
+# Record a trace for debugging
+npx playwright test --trace on
+npx playwright show-report
+```
+
+## Related
+
+- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) -- custom fixtures that replace `globalSetup` for per-test state
+- [core/test-organization.md](test-organization.md) -- file structure, naming conventions, test grouping
+- [core/authentication.md](authentication.md) -- setup projects for shared auth state
+- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI-specific config and caching
+- [ci/projects-and-dependencies.md](../ci/projects-and-dependencies.md) -- advanced multi-project patterns