@arcadialdev/arcality 2.4.28 → 2.4.30

package/.agents/skills/playwright-best-practices/core/projects-dependencies.md

@@ -1,453 +0,0 @@
-# Projects & Dependencies
-
-## Table of Contents
-
-1. [Project Configuration](#project-configuration)
-2. [Project Dependencies](#project-dependencies)
-3. [Setup Projects](#setup-projects)
-4. [Filtering & Running Projects](#filtering--running-projects)
-5. [Sharing Configuration](#sharing-configuration)
-6. [Advanced Patterns](#advanced-patterns)
-
-## Project Configuration
-
-### Basic Multi-Browser Setup
-
-```typescript
-// playwright.config.ts
-import { defineConfig, devices } from "@playwright/test";
-
-export default defineConfig({
-  projects: [
-    {
-      name: "chromium",
-      use: { ...devices["Desktop Chrome"] },
-    },
-    {
-      name: "firefox",
-      use: { ...devices["Desktop Firefox"] },
-    },
-    {
-      name: "webkit",
-      use: { ...devices["Desktop Safari"] },
-    },
-  ],
-});
-```
-
-### Environment-Based Projects
-
-```typescript
-export default defineConfig({
-  projects: [
-    {
-      name: "staging",
-      use: {
-        baseURL: "https://staging.example.com",
-      },
-    },
-    {
-      name: "production",
-      use: {
-        baseURL: "https://example.com",
-      },
-    },
-    {
-      name: "local",
-      use: {
-        baseURL: "http://localhost:3000",
-      },
-    },
-  ],
-});
-```
-
-### Test Type Projects
-
-```typescript
-export default defineConfig({
-  projects: [
-    {
-      name: "e2e",
-      testDir: "./tests/e2e",
-      use: { ...devices["Desktop Chrome"] },
-    },
-    {
-      name: "api",
-      testDir: "./tests/api",
-      use: { baseURL: "http://localhost:3000" },
-    },
-    {
-      name: "visual",
-      testDir: "./tests/visual",
-      use: {
-        ...devices["Desktop Chrome"],
-        viewport: { width: 1280, height: 720 },
-      },
-    },
-  ],
-});
-```
-
-## Project Dependencies
-
-### Setup Dependency
-
-```typescript
-export default defineConfig({
-  projects: [
-    // Setup project runs first
-    {
-      name: "setup",
-      testMatch: /.*\.setup\.ts/,
-    },
-
-    // Browser projects depend on setup
-    {
-      name: "chromium",
-      use: {
-        ...devices["Desktop Chrome"],
-        storageState: ".auth/user.json",
-      },
-      dependencies: ["setup"],
-    },
-    {
-      name: "firefox",
-      use: {
-        ...devices["Desktop Firefox"],
-        storageState: ".auth/user.json",
-      },
-      dependencies: ["setup"],
-    },
-  ],
-});
-```
-
-### Multiple Auth States
-
-```typescript
-export default defineConfig({
-  projects: [
-    // Auth setup projects
-    {
-      name: "setup-admin",
-      testMatch: /admin\.setup\.ts/,
-    },
-    {
-      name: "setup-user",
-      testMatch: /user\.setup\.ts/,
-    },
-
-    // Admin tests
-    {
-      name: "admin-tests",
-      testDir: "./tests/admin",
-      use: { storageState: ".auth/admin.json" },
-      dependencies: ["setup-admin"],
-    },
-
-    // User tests
-    {
-      name: "user-tests",
-      testDir: "./tests/user",
-      use: { storageState: ".auth/user.json" },
-      dependencies: ["setup-user"],
-    },
-
-    // Tests that need both
-    {
-      name: "integration-tests",
-      testDir: "./tests/integration",
-      dependencies: ["setup-admin", "setup-user"],
-    },
-  ],
-});
-```
-
-### Chained Dependencies
-
-```typescript
-export default defineConfig({
-  projects: [
-    // Step 1: Database setup
-    {
-      name: "db-setup",
-      testMatch: /db\.setup\.ts/,
-    },
-
-    // Step 2: Auth setup (needs DB)
-    {
-      name: "auth-setup",
-      testMatch: /auth\.setup\.ts/,
-      dependencies: ["db-setup"],
-    },
-
-    // Step 3: Seed data (needs auth)
-    {
-      name: "seed-setup",
-      testMatch: /seed\.setup\.ts/,
-      dependencies: ["auth-setup"],
-    },
-
-    // Tests (need everything)
-    {
-      name: "tests",
-      testDir: "./tests",
-      dependencies: ["seed-setup"],
-    },
-  ],
-});
-```
-
-## Setup Projects
-
-### Authentication Setup
-
-Setup projects are the recommended way to handle authentication. They run before your main test projects and can use Playwright fixtures.
-
-> **For complete authentication patterns** (storage state, multiple auth states, auth fixtures), see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns).
-
-### Data Seeding Setup
-
-```typescript
-// seed.setup.ts
-import { test as setup } from "@playwright/test";
-
-setup("seed test data", async ({ request }) => {
-  // Create test data via API
-  await request.post("/api/test/seed", {
-    data: {
-      users: 10,
-      products: 50,
-      orders: 100,
-    },
-  });
-});
-```
-
-### Cleanup Setup
-
-```typescript
-// cleanup.setup.ts
-import { test as setup } from "@playwright/test";
-
-setup("cleanup previous run", async ({ request }) => {
-  // Clean up data from previous test runs
-  await request.delete("/api/test/cleanup");
-});
-```
-
-## Filtering & Running Projects
-
-### Run Specific Project
-
-```bash
-# Run single project
-npx playwright test --project=chromium
-
-# Run multiple projects
-npx playwright test --project=chromium --project=firefox
-```
-
-### Run by Grep
-
-```bash
-# Run tests matching pattern
-npx playwright test --grep @smoke
-
-# Run project with grep
-npx playwright test --project=chromium --grep @critical
-
-# Exclude pattern
-npx playwright test --grep-invert @slow
-```
-
-### Project-Specific Grep
-
-```typescript
-export default defineConfig({
-  projects: [
-    {
-      name: "smoke",
-      grep: /@smoke/,
-      use: { ...devices["Desktop Chrome"] },
-    },
-    {
-      name: "regression",
-      grepInvert: /@smoke/,
-      use: { ...devices["Desktop Chrome"] },
-    },
-  ],
-});
-```
-
-## Sharing Configuration
-
-### Base Configuration
-
-```typescript
-// playwright.config.ts
-const baseConfig = {
-  timeout: 30000,
-  expect: { timeout: 5000 },
-  use: {
-    trace: "on-first-retry",
-    screenshot: "only-on-failure",
-  },
-};
-
-export default defineConfig({
-  ...baseConfig,
-  projects: [
-    {
-      name: "chromium",
-      use: {
-        ...baseConfig.use,
-        ...devices["Desktop Chrome"],
-      },
-    },
-    {
-      name: "firefox",
-      use: {
-        ...baseConfig.use,
-        ...devices["Desktop Firefox"],
-      },
-    },
-  ],
-});
-```
-
-### Shared Project Settings
-
-```typescript
-const sharedBrowserConfig = {
-  timeout: 60000,
-  retries: 2,
-  use: {
-    video: "on-first-retry",
-    trace: "on-first-retry",
-  },
-};
-
-export default defineConfig({
-  projects: [
-    {
-      name: "chromium",
-      ...sharedBrowserConfig,
-      use: {
-        ...sharedBrowserConfig.use,
-        ...devices["Desktop Chrome"],
-      },
-    },
-    {
-      name: "firefox",
-      ...sharedBrowserConfig,
-      use: {
-        ...sharedBrowserConfig.use,
-        ...devices["Desktop Firefox"],
-      },
-    },
-  ],
-});
-```
-
-## Advanced Patterns
-
-### Conditional Projects
-
-```typescript
-const projects = [
-  {
-    name: "chromium",
-    use: { ...devices["Desktop Chrome"] },
-  },
-];
-
-// Add Firefox only in CI
-if (process.env.CI) {
-  projects.push({
-    name: "firefox",
-    use: { ...devices["Desktop Firefox"] },
-  });
-}
-
-// Add mobile only for specific test dirs
-if (process.env.TEST_MOBILE) {
-  projects.push({
-    name: "mobile",
-    use: { ...devices["iPhone 14"] },
-  });
-}
-
-export default defineConfig({ projects });
-```
-
-### Project Metadata
-
-```typescript
-export default defineConfig({
-  projects: [
-    {
-      name: "chromium",
-      use: { ...devices["Desktop Chrome"] },
-      metadata: {
-        platform: "desktop",
-        browser: "chromium",
-        priority: "high",
-      },
-    },
-  ],
-});
-
-// Access in test
-test("example", async ({ page }, testInfo) => {
-  const { platform, priority } = testInfo.project.metadata;
-  console.log(`Running on ${platform} with ${priority} priority`);
-});
-```
-
-### Teardown Projects
-
-```typescript
-export default defineConfig({
-  projects: [
-    {
-      name: "setup",
-      testMatch: /.*\.setup\.ts/,
-      teardown: "teardown", // Run teardown after this completes
-    },
-    {
-      name: "teardown",
-      testMatch: /.*\.teardown\.ts/,
-    },
-    {
-      name: "tests",
-      dependencies: ["setup"],
-    },
-  ],
-});
-```
-
-```typescript
-// cleanup.teardown.ts
-import { test as teardown } from "@playwright/test";
-
-teardown("cleanup", async ({ request }) => {
-  await request.delete("/api/test/data");
-});
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern               | Problem                | Solution                            |
-| -------------------------- | ---------------------- | ----------------------------------- |
-| Too many browser projects  | Slow CI, expensive     | Focus on critical browsers          |
-| Missing setup dependencies | Tests fail randomly    | Declare all dependencies explicitly |
-| Duplicated configuration   | Hard to maintain       | Extract shared config               |
-| Not using setup projects   | Repeated auth in tests | Use setup project + storageState    |
-
-## Related References
-
-- **Global Setup**: See [global-setup.md](global-setup.md) for globalSetup vs setup projects
-- **Fixtures**: See [fixtures-hooks.md](fixtures-hooks.md) for authentication patterns
-- **CI/CD**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for running projects in CI