testeiya 0.2.1 → 0.3.9

package/skills/playwright-best-practices-skill/core/global-setup.md

@@ -1,434 +0,0 @@
-# Global Setup & Teardown
-
-## Table of Contents
-
-1. [Global Setup](#global-setup)
-2. [Global Teardown](#global-teardown)
-3. [Database Patterns](#database-patterns)
-4. [Environment Provisioning](#environment-provisioning)
-5. [Setup Projects vs Global Setup](#setup-projects-vs-global-setup)
-6. [Parallel Execution Caveats](#parallel-execution-caveats)
-
-## Global Setup
-
-### Basic Global Setup
-
-```typescript
-// global-setup.ts
-import { FullConfig } from "@playwright/test";
-
-async function globalSetup(config: FullConfig) {
-  console.log("Running global setup...");
-  // Perform one-time setup: start services, run migrations, etc.
-}
-
-export default globalSetup;
-```
-
-### Configure Global Setup
-
-```typescript
-// playwright.config.ts
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  globalSetup: require.resolve("./global-setup"),
-  globalTeardown: require.resolve("./global-teardown"),
-});
-```
-
-> **Authentication in Global Setup**: For authentication patterns using storage state in global setup, see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns). Setup projects are generally preferred for authentication as they provide access to Playwright fixtures.
-
-### Global Setup with Return Value
-
-```typescript
-// global-setup.ts
-async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
-  const server = await startTestServer();
-
-  // Return cleanup function (alternative to globalTeardown)
-  return async () => {
-    await server.stop();
-  };
-}
-
-export default globalSetup;
-```
-
-### Access Config in Global Setup
-
-```typescript
-// global-setup.ts
-import { FullConfig } from "@playwright/test";
-
-async function globalSetup(config: FullConfig) {
-  const { baseURL } = config.projects[0].use;
-  console.log(`Setting up for ${baseURL}`);
-
-  // Access custom config
-  const workers = config.workers;
-  const timeout = config.timeout;
-
-  // Access environment
-  const isCI = !!process.env.CI;
-}
-
-export default globalSetup;
-```
-
-## Global Teardown
-
-### Basic Global Teardown
-
-```typescript
-// global-teardown.ts
-import { FullConfig } from "@playwright/test";
-import fs from "fs";
-
-async function globalTeardown(config: FullConfig) {
-  console.log("Running global teardown...");
-
-  // Clean up auth files
-  if (fs.existsSync(".auth")) {
-    fs.rmSync(".auth", { recursive: true });
-  }
-
-  // Clean up test data
-  await cleanupTestDatabase();
-
-  // Stop services
-  await stopTestServices();
-}
-
-export default globalTeardown;
-```
-
-### Conditional Teardown
-
-```typescript
-// global-teardown.ts
-async function globalTeardown(config: FullConfig) {
-  // Skip cleanup in CI (containers are discarded anyway)
-  if (process.env.CI) {
-    console.log("Skipping teardown in CI");
-    return;
-  }
-
-  // Local cleanup
-  await cleanupLocalTestData();
-}
-
-export default globalTeardown;
-```
-
-## Database Patterns
-
-This section covers **one-time database setup** (migrations, snapshots, per-worker databases). For related topics:
-
-- **Per-test database fixtures** (isolation, transaction rollback): See [fixtures-hooks.md](fixtures-hooks.md#database-fixtures)
-- **Test data factories** (builders, Faker): See [test-data.md](test-data.md)
-
-### Database Migration in Setup
-
-```typescript
-// global-setup.ts
-import { execSync } from "child_process";
-
-async function globalSetup() {
-  console.log("Running database migrations...");
-
-  // Run migrations
-  execSync("npx prisma migrate deploy", { stdio: "inherit" });
-
-  // Seed test data
-  execSync("npx prisma db seed", { stdio: "inherit" });
-}
-
-export default globalSetup;
-```
-
-### Database Snapshot Pattern
-
-```typescript
-// global-setup.ts
-import { execSync } from "child_process";
-import fs from "fs";
-
-const SNAPSHOT_PATH = "./test-db-snapshot.sql";
-
-async function globalSetup() {
-  // Check if snapshot exists
-  if (fs.existsSync(SNAPSHOT_PATH)) {
-    console.log("Restoring database from snapshot...");
-    execSync(`psql $DATABASE_URL < ${SNAPSHOT_PATH}`, { stdio: "inherit" });
-    return;
-  }
-
-  // First run: migrate and create snapshot
-  console.log("Creating database snapshot...");
-  execSync("npx prisma migrate deploy", { stdio: "inherit" });
-  execSync("npx prisma db seed", { stdio: "inherit" });
-  execSync(`pg_dump $DATABASE_URL > ${SNAPSHOT_PATH}`, { stdio: "inherit" });
-}
-
-export default globalSetup;
-```
-
-### Test Database per Worker
-
-```typescript
-// global-setup.ts
-async function globalSetup(config: FullConfig) {
-  const workerCount = config.workers || 1;
-
-  // Create a database for each worker
-  for (let i = 0; i < workerCount; i++) {
-    const dbName = `test_db_worker_${i}`;
-    await createDatabase(dbName);
-    await runMigrations(dbName);
-    await seedDatabase(dbName);
-  }
-}
-
-// global-teardown.ts
-async function globalTeardown(config: FullConfig) {
-  const workerCount = config.workers || 1;
-
-  for (let i = 0; i < workerCount; i++) {
-    await dropDatabase(`test_db_worker_${i}`);
-  }
-}
-```
-
-## Environment Provisioning
-
-### Start Services in Setup
-
-```typescript
-// global-setup.ts
-import { execSync, spawn } from "child_process";
-
-let serverProcess: any;
-
-async function globalSetup() {
-  // Start backend server
-  serverProcess = spawn("npm", ["run", "start:test"], {
-    stdio: "pipe",
-    detached: true,
-  });
-
-  // Wait for server to be ready
-  await waitForServer("http://localhost:3000/health", 30000);
-
-  // Store PID for teardown
-  process.env.SERVER_PID = serverProcess.pid.toString();
-}
-
-async function waitForServer(url: string, timeout: number) {
-  const start = Date.now();
-
-  while (Date.now() - start < timeout) {
-    try {
-      const response = await fetch(url);
-      if (response.ok) return;
-    } catch {
-      // Server not ready yet
-    }
-    await new Promise((r) => setTimeout(r, 1000));
-  }
-
-  throw new Error(`Server did not start within ${timeout}ms`);
-}
-
-export default globalSetup;
-```
-
-### Docker Compose Setup
-
-```typescript
-// global-setup.ts
-import { execSync } from "child_process";
-
-async function globalSetup() {
-  console.log("Starting Docker services...");
-
-  execSync("docker-compose -f docker-compose.test.yml up -d", {
-    stdio: "inherit",
-  });
-
-  // Wait for services to be healthy
-  execSync("docker-compose -f docker-compose.test.yml exec -T db pg_isready", {
-    stdio: "inherit",
-  });
-}
-
-export default globalSetup;
-```
-
-```typescript
-// global-teardown.ts
-import { execSync } from "child_process";
-
-async function globalTeardown() {
-  console.log("Stopping Docker services...");
-
-  execSync("docker-compose -f docker-compose.test.yml down -v", {
-    stdio: "inherit",
-  });
-}
-
-export default globalTeardown;
-```
-
-### Environment Variables Setup
-
-```typescript
-// global-setup.ts
-import dotenv from "dotenv";
-import path from "path";
-
-async function globalSetup() {
-  // Load test-specific environment
-  const envFile = process.env.CI ? ".env.ci" : ".env.test";
-  dotenv.config({ path: path.resolve(process.cwd(), envFile) });
-
-  // Validate required variables
-  const required = ["DATABASE_URL", "API_KEY", "TEST_EMAIL"];
-  for (const key of required) {
-    if (!process.env[key]) {
-      throw new Error(`Missing required environment variable: ${key}`);
-    }
-  }
-}
-
-export default globalSetup;
-```
-
-## Setup Projects vs Global Setup
-
-### When to Use Each
-
-| Use Global Setup                      | Use Setup Projects                       |
-| ------------------------------------- | ---------------------------------------- |
-| One-time setup (migrations, services) | Per-project setup (auth states)          |
-| No access to Playwright fixtures      | Need page, request fixtures              |
-| Runs once before all projects         | Can run per-project or have dependencies |
-| Shared across all workers             | Can be parallelized                      |
-
-### Setup Project Pattern
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  projects: [
-    // Setup project
-    {
-      name: "setup",
-      testMatch: /.*\.setup\.ts/,
-    },
-    // Test projects depend on setup
-    {
-      name: "chromium",
-      use: { ...devices["Desktop Chrome"] },
-      dependencies: ["setup"],
-    },
-    {
-      name: "firefox",
-      use: { ...devices["Desktop Firefox"] },
-      dependencies: ["setup"],
-    },
-  ],
-});
-```
-
-> **For complete authentication setup patterns**, see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns).
-
-### Combining Both
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  // Global: Start services, run migrations
-  globalSetup: require.resolve("./global-setup"),
-  globalTeardown: require.resolve("./global-teardown"),
-
-  projects: [
-    // Setup project: Create auth states
-    { name: "setup", testMatch: /.*\.setup\.ts/ },
-    {
-      name: "chromium",
-      use: {
-        ...devices["Desktop Chrome"],
-        storageState: ".auth/user.json",
-      },
-      dependencies: ["setup"],
-    },
-  ],
-});
-```
-
-## Parallel Execution Caveats
-
-### Understanding Global Setup Execution
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  globalSetup runs ONCE                                      │
-│  ↓                                                          │
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
-│  │ Worker 1│  │ Worker 2│  │ Worker 3│  │ Worker 4│        │
-│  │ tests   │  │ tests   │  │ tests   │  │ tests   │        │
-│  └─────────┘  └─────────┘  └─────────┘  └─────────┘        │
-│  ↓                                                          │
-│  globalTeardown runs ONCE                                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Key implications:**
-
-- Global setup has **no access** to Playwright fixtures (`page`, `request`, `context`)
-- State created in global setup is **shared** across all workers
-- If tests **modify** shared state, they may conflict with parallel workers
-- Global setup **cannot** react to individual test needs
-
-### When to Prefer Worker-Scoped Fixtures
-
-Use **worker-scoped fixtures** instead of globalSetup when:
-
-| Scenario                             | Why Fixtures Are Better                              |
-| ------------------------------------ | ---------------------------------------------------- |
-| Each worker needs isolated resources | Fixtures can create per-worker databases, servers    |
-| Setup needs Playwright APIs          | Fixtures have access to `page`, `request`, `browser` |
-| Setup depends on test configuration  | Fixtures receive test context and options            |
-| Resources need cleanup per worker    | Worker fixtures auto-cleanup when worker exits       |
-
-### Common Parallel Pitfall
-
-```typescript
-// ❌ BAD: Global setup creates ONE user, all workers fight over it
-async function globalSetup() {
-  await createUser({ email: "test@example.com" }); // Shared!
-}
-
-// ✅ GOOD: Each worker gets its own user via worker-scoped fixture
-// Uses workerInfo.workerIndex to create unique data per worker
-```
-
-> **For worker-scoped fixture patterns** (per-worker databases, unique test data, `workerIndex` isolation), see [fixtures-hooks.md](fixtures-hooks.md#isolate-test-data-between-parallel-workers).
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern                   | Problem                          | Solution                                   |
-| ------------------------------ | -------------------------------- | ------------------------------------------ |
-| Heavy setup in globalSetup     | Slow test startup                | Use setup projects for parallelizable work |
-| Not cleaning up in teardown    | Leaks resources, flaky CI        | Always clean up or use containers          |
-| Hardcoded URLs in setup        | Breaks in different environments | Use config.projects[0].use.baseURL         |
-| No timeout on service wait     | Hangs forever if service fails   | Add timeout with clear error               |
-| Shared mutable state           | Race conditions in parallel      | Use worker-scoped fixtures for isolation   |
-| Global setup for per-test data | Tests conflict                   | Use test-scoped fixtures                   |
-
-## Related References
-
-- **Fixtures & Auth**: See [fixtures-hooks.md](fixtures-hooks.md) for worker-scoped fixtures and auth patterns
-- **CI/CD**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for CI setup patterns
-- **Projects**: See [projects-dependencies.md](projects-dependencies.md) for project configuration

package/skills/playwright-best-practices-skill/core/locators.md

@@ -1,242 +0,0 @@
-# Locator Strategies
-
-## Table of Contents
-
-1. [Priority Order](#priority-order)
-2. [User-Facing Locators](#user-facing-locators)
-3. [Filtering & Chaining](#filtering--chaining)
-4. [Dynamic Content](#dynamic-content)
-5. [Shadow DOM](#shadow-dom)
-6. [Iframes](#iframes)
-
-## Priority Order
-
-Use locators in this order of preference:
-
-1. **Role-based** (most resilient): `getByRole`
-2. **Label-based**: `getByLabel`, `getByPlaceholder`
-3. **Text-based**: `getByText`, `getByTitle`
-4. **Test IDs** (when semantic locators aren't possible): `getByTestId`
-5. **CSS/XPath** (last resort): `locator('css=...')`, `locator('xpath=...')`
-
-## User-Facing Locators
-
-### getByRole
-
-Most robust approach - matches how users and assistive technology perceive the page.
-
-```typescript
-// Buttons
-page.getByRole("button", { name: "Submit", exact: true }); // exact accessible name
-page.getByRole("button", { name: /submit/i }); // flexible case-insensitive match
-
-// Links
-page.getByRole("link", { name: "Home" });
-
-// Form elements
-page.getByRole("textbox", { name: "Email" });
-page.getByRole("checkbox", { name: "Remember me" });
-page.getByRole("combobox", { name: "Country" });
-page.getByRole("radio", { name: "Option A" });
-
-// Headings
-page.getByRole("heading", { name: "Welcome", level: 1 });
-
-// Lists & items
-page.getByRole("list").getByRole("listitem");
-
-// Navigation & regions
-page.getByRole("navigation");
-page.getByRole("main");
-page.getByRole("dialog");
-page.getByRole("alert");
-```
-
-### getByLabel
-
-For form elements with associated labels.
-
-```typescript
-// Input with <label for="email">
-page.getByLabel("Email address");
-
-// Input with aria-label
-page.getByLabel("Search");
-
-// Exact match
-page.getByLabel("Email", { exact: true });
-```
-
-### getByPlaceholder
-
-```typescript
-page.getByPlaceholder("Enter your email");
-page.getByPlaceholder(/email/i);
-```
-
-### getByText
-
-```typescript
-// Partial match (default)
-page.getByText("Welcome");
-
-// Exact match
-page.getByText("Welcome to our site", { exact: true });
-
-// Regex
-page.getByText(/welcome/i);
-```
-
-### getByTestId
-
-Configure custom test ID attribute in `playwright.config.ts`:
-
-```typescript
-use: {
-  testIdAttribute: "data-testid"; // default
-}
-```
-
-Usage:
-
-```typescript
-// HTML: <button data-testid="submit-btn">Submit</button>
-page.getByTestId("submit-btn");
-```
-
-## Filtering & Chaining
-
-### filter()
-
-Narrow down locators:
-
-```typescript
-// Filter by text
-page.getByRole("listitem").filter({ hasText: "Product" });
-
-// Filter by NOT having text
-page.getByRole("listitem").filter({ hasNotText: "Out of stock" });
-
-// Filter by child locator
-page.getByRole("listitem").filter({
-  has: page.getByRole("button", { name: "Buy" }),
-});
-
-// Combine filters
-page
-  .getByRole("listitem")
-  .filter({ hasText: "Product" })
-  .filter({ has: page.getByText("$9.99") });
-```
-
-### Chaining
-
-```typescript
-// Navigate down the DOM tree
-page.getByRole("article").getByRole("heading");
-
-// Get parent/ancestor
-page.getByText("Child").locator("..");
-page.getByText("Child").locator("xpath=ancestor::article");
-```
-
-### nth() and first()/last()
-
-```typescript
-page.getByRole("listitem").first();
-page.getByRole("listitem").last();
-page.getByRole("listitem").nth(2); // 0-indexed
-```
-
-## Dynamic Content
-
-### Waiting for Elements
-
-Locators auto-wait for actionability by default. For explicit state waiting:
-
-```typescript
-await page.getByRole("button").waitFor({ state: "visible" });
-await page.getByText("Loading").waitFor({ state: "hidden" });
-```
-
-> **For comprehensive waiting strategies** (element state, navigation, network, polling with `toPass()`), see [assertions-waiting.md](assertions-waiting.md#waiting-strategies).
-
-### Lists with Dynamic Items
-
-```typescript
-// Wait for specific count
-await expect(page.getByRole("listitem")).toHaveCount(5);
-
-// Get all matching elements
-const items = await page.getByRole("listitem").all();
-for (const item of items) {
-  await expect(item).toBeVisible();
-}
-```
-
-## Shadow DOM
-
-Playwright pierces shadow DOM by default:
-
-```typescript
-// Automatically finds elements inside shadow roots
-page.getByRole("button", { name: "Shadow Button" });
-
-// Explicit shadow DOM traversal (if needed)
-page.locator("my-component").locator("internal:shadow=button");
-```
-
-## Iframes
-
-```typescript
-// By frame name or URL
-const frame = page.frameLocator('iframe[name="content"]');
-await frame.getByRole("button").click();
-
-// By index
-const frame = page.frameLocator("iframe").first();
-
-// Nested iframes
-const nestedFrame = page.frameLocator("#outer").frameLocator("#inner");
-await nestedFrame.getByText("Content").click();
-```
-
-## Debugging Locators
-
-```typescript
-// Highlight element in headed mode
-await page.getByRole("button").highlight();
-
-// Count matches
-const count = await page.getByRole("listitem").count();
-
-// Check if exists without waiting
-const exists = (await page.getByRole("button").count()) > 0;
-
-// Use Playwright Inspector
-// PWDEBUG=1 npx playwright test
-```
-
-## Common Issues & Solutions
-
-| Issue                   | Solution                                         |
-| ----------------------- | ------------------------------------------------ |
-| Multiple elements match | Add filters or use `nth()`, `first()`, `last()`  |
-| Element not found       | Check visibility, wait for load, verify selector |
-| Stale element           | Locators are lazy; re-query if DOM changes       |
-| Dynamic IDs             | Use stable attributes like role, text, test-id   |
-| Hidden elements         | Use `{ force: true }` only when necessary        |
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern                      | Problem                           | Solution                                          |
-| --------------------------------- | --------------------------------- | ------------------------------------------------- |
-| `page.locator('.btn-primary')`    | Brittle, implementation-dependent | `page.getByRole('button', { name: 'Submit' })`    |
-| `page.locator('#dynamic-id-123')` | Breaks when IDs change            | Use stable attributes like role, text, or test-id |
-| Testing implementation details    | Breaks on refactoring             | Test user-visible behavior                        |
-
-## Related References
-
-- **Debugging selector issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting
-- **Waiting for elements**: See [assertions-waiting.md](assertions-waiting.md) for waiting strategies
-- **Using in Page Objects**: See [page-object-model.md](page-object-model.md) for organizing locators