@arcadialdev/arcality 2.2.0

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

@@ -0,0 +1,434 @@
+# 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/.agents/skills/playwright-best-practices/core/locators.md

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