Skip to content

testdino-hq/playwright-skill / ci

playwright-ci

Verified

Production-ready CI/CD configurations for Playwright — GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Docker, parallel sharding, reporting, code coverage, and global setup/teardown.

FileKindSize
SKILL.mdskill md2.1 KB
ci-github-actions.mdmarkdown18.0 KB
ci-gitlab.mdmarkdown10.8 KB
ci-other.mdmarkdown15.1 KB
docker-and-containers.mdmarkdown14.3 KB
global-setup-teardown.mdmarkdown17.7 KB
parallel-and-sharding.mdmarkdown16.1 KB
projects-and-dependencies.mdmarkdown19.1 KB
reporting-and-artifacts.mdmarkdown20.1 KB
test-coverage.mdmarkdown13.8 KB

global-setup-teardown.md

View on GitHub
# Global Setup and Teardown

> **When to use**: One-time operations that must run before or after the entire test suite -- database seeding, environment health checks, creating shared auth state, starting external services. Runs once per `npx playwright test` invocation, not once per test or per worker.

## Quick Reference

```
globalSetup         →  runs ONCE before all tests in all projects
  ↓
setup projects      →  runs before dependent projects (has browser context)
  ↓
test projects       →  your actual tests
  ↓
teardown projects   →  runs after dependent projects (has browser context)
  ↓
globalTeardown      →  runs ONCE after all tests in all projects
```

**Key distinction:**
- `globalSetup` / `globalTeardown`: No browser provided (you must launch one yourself), no Playwright fixtures, no trace/report integration.
- Setup projects with `dependencies`: Has full browser context, can use `page`, `request`, etc.

## Patterns

### Pattern 1: Basic Global Setup and Teardown

**Use when**: One-time non-browser work like database seeding, environment validation, or external service preparation.
**Avoid when**: You need a browser (use a setup project instead) or per-test isolation (use fixtures).

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: './tests/global-setup.ts',
  globalTeardown: './tests/global-teardown.ts',
  testDir: './tests',
});
```

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  console.log('Global setup: seeding database...');

  // Seed the test database
  const { execSync } = await import('child_process');
  execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
  execSync('npx prisma db seed', { stdio: 'inherit' });

  // Store run metadata for tests to use
  process.env.TEST_RUN_ID = `run-${Date.now()}`;
}

export default globalSetup;
```

```ts
// tests/global-teardown.ts
import type { FullConfig } from '@playwright/test';

async function globalTeardown(config: FullConfig) {
  console.log('Global teardown: cleaning up...');

  const { execSync } = await import('child_process');
  execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
}

export default globalTeardown;
```

### Pattern 2: Environment Health Check in Global Setup

**Use when**: Verifying the test environment is healthy before running any tests. Fails fast if services are down.
**Avoid when**: Tests use `webServer` which already does a health check.

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const baseURL = config.projects[0]?.use?.baseURL || 'http://localhost:3000';
  const maxRetries = 10;
  const retryDelay = 2000;

  console.log(`Checking if ${baseURL} is reachable...`);

  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(`${baseURL}/api/health`);
      if (response.ok) {
        console.log(`Environment is healthy (attempt ${i + 1})`);
        return;
      }
    } catch {
      // Connection refused or timeout -- retry
    }
    console.log(`Waiting for environment... (attempt ${i + 1}/${maxRetries})`);
    await new Promise((resolve) => setTimeout(resolve, retryDelay));
  }

  throw new Error(`Environment at ${baseURL} is not reachable after ${maxRetries} attempts`);
}

export default globalSetup;
```

### Pattern 3: Authentication State in Global Setup (Without Browser)

**Use when**: Creating auth tokens or session cookies via API, without needing a browser.
**Avoid when**: Login requires browser interaction (use a setup project instead).

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';

async function globalSetup(config: FullConfig) {
  const baseURL = config.projects[0]?.use?.baseURL || 'http://localhost:3000';

  // Authenticate via API (no browser needed)
  const response = await fetch(`${baseURL}/api/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'admin@example.com',
      password: process.env.TEST_PASSWORD,
    }),
  });

  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.status} ${response.statusText}`);
  }

  const { token } = await response.json();

  // Save the token as storageState for browser tests to pick up
  const authDir = path.resolve(process.cwd(), 'playwright/.auth');
  fs.mkdirSync(authDir, { recursive: true });

  const storageState = {
    cookies: [],
    origins: [
      {
        origin: baseURL,
        localStorage: [
          { name: 'auth_token', value: token },
        ],
      },
    ],
  };

  fs.writeFileSync(
    path.join(authDir, 'user.json'),
    JSON.stringify(storageState, null, 2)
  );
}

export default globalSetup;
```

```ts
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  globalSetup: './tests/global-setup.ts',
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'playwright/.auth/user.json',
      },
    },
  ],
});
```

### Pattern 4: Passing Data from Global Setup to Tests

**Use when**: Global setup generates values (IDs, tokens, URLs) that tests need.
**Avoid when**: Each test should create its own data (the usual case).

**Method 1: Environment variables (simplest):**

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  process.env.TEST_RUN_ID = `run-${Date.now()}`;
  process.env.SEED_USER_ID = 'user-12345';
}

export default globalSetup;
```

```ts
// tests/dashboard.spec.ts
import { test, expect } from '@playwright/test';

test('dashboard shows seeded data', async ({ page }) => {
  const userId = process.env.SEED_USER_ID;
  await page.goto(`/users/${userId}/dashboard`);
  await expect(page.getByRole('heading')).toBeVisible();
});
```

**Method 2: Shared file (for complex data):**

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';

const SETUP_DATA_PATH = path.resolve(process.cwd(), 'test-data/setup-data.json');

async function globalSetup(config: FullConfig) {
  const baseURL = config.projects[0]?.use?.baseURL || 'http://localhost:3000';

  // Create test data via API
  const res = await fetch(`${baseURL}/api/test/seed`, { method: 'POST' });
  const seedData = await res.json();

  // Write to shared file
  const dir = path.dirname(SETUP_DATA_PATH);
  fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(SETUP_DATA_PATH, JSON.stringify(seedData, null, 2));
}

export default globalSetup;
```

```ts
// tests/helpers/setup-data.ts
import * as fs from 'fs';
import * as path from 'path';

const SETUP_DATA_PATH = path.resolve(process.cwd(), 'test-data/setup-data.json');

export function getSetupData(): { userId: string; orgId: string; apiKey: string } {
  const raw = fs.readFileSync(SETUP_DATA_PATH, 'utf8');
  return JSON.parse(raw);
}
```

```ts
// tests/org-settings.spec.ts
import { test, expect } from '@playwright/test';
import { getSetupData } from './helpers/setup-data';

test('org settings page loads', async ({ page }) => {
  const { orgId } = getSetupData();
  await page.goto(`/orgs/${orgId}/settings`);
  await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
});
```

### Pattern 4b: Only Prepare What This Run Needs (`config.filteredProjects`, Playwright 1.64+)

**Use when**: Global setup does per-project work (seeding, auth, warming a service) and the run often targets a subset of projects.

`config.projects` lists every project in the config. `config.filteredProjects` lists only those selected after the `--project` filter and `default: false` are applied, so a `--project=chromium` run does not pay for Firefox and WebKit setup.

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  for (const project of config.filteredProjects) {
    console.log(`Preparing ${project.name}`);
    // seed data or warm caches for this project only
  }
}

export default globalSetup;
```

The same property is available to reporters in `onBegin(config)`.

### Pattern 5: Global Setup with `storageState` (Browser-Based Auth)

**Use when**: Authentication requires browser interaction (form login, OAuth redirect, MFA).
**Avoid when**: Auth can be done via API call (use Pattern 3 instead).

**Important**: `globalSetup` gets no browser or fixtures. For browser-based auth, use a **setup project** instead.

```ts
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    // Setup project: runs first, has a browser, saves auth state
    {
      name: 'setup',
      testMatch: /global\.setup\.ts/,
    },

    // Test projects: depend on setup, reuse saved auth state
    {
      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();

  // Wait for navigation to confirm login succeeded
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();

  // Save signed-in state (cookies + localStorage)
  await page.context().storageState({ path: authFile });
});
```

### Pattern 6: Global Setup for External Services

**Use when**: Starting or configuring external services (mock servers, test containers, feature flags) before any tests run.
**Avoid when**: Per-test or per-worker isolation is needed (use fixtures).

```ts
// tests/global-setup.ts
import type { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  // Start a mock API server
  const { createServer } = await import('../mocks/server');
  const server = await createServer();
  const port = await server.listen(0);
  process.env.MOCK_API_URL = `http://localhost:${port}`;

  // Configure feature flags for test environment
  const baseURL = config.projects[0]?.use?.baseURL || 'http://localhost:3000';
  await fetch(`${baseURL}/api/admin/feature-flags`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.ADMIN_API_KEY}`,
    },
    body: JSON.stringify({
      newCheckout: true,
      darkMode: false,
      betaFeatures: true,
    }),
  });

  // Cleanup goes in globalTeardown below; alternatively, return an async function here and Playwright runs it as teardown
}

export default globalSetup;
```

```ts
// tests/global-teardown.ts
import type { FullConfig } from '@playwright/test';

async function globalTeardown(config: FullConfig) {
  // Reset feature flags
  const baseURL = config.projects[0]?.use?.baseURL || 'http://localhost:3000';
  await fetch(`${baseURL}/api/admin/feature-flags/reset`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ADMIN_API_KEY}` },
  });
}

export default globalTeardown;
```

## Decision Guide

| Need | Use | Why |
|---|---|---|
| One-time DB seed | `globalSetup` | No browser needed; runs once before everything |
| Browser-based login (shared state) | Setup project with `dependencies` | Needs `page` and `context` (not available in globalSetup) |
| API-based auth token | `globalSetup` | Simple HTTP call, no browser needed |
| Per-test unique data | Custom fixture via `test.extend()` | Each test gets isolated data |
| Per-worker shared resource | Worker-scoped fixture (`{ scope: 'worker' }`) | Shared within worker, isolated between workers |
| Health check before tests | `globalSetup` | Fail fast if environment is down |
| Start mock server | `globalSetup` + `globalTeardown` | One-time server lifecycle |
| Clean up after all tests | `globalTeardown` | Runs once at the end regardless of pass/fail |

```
Do I need globalSetup?
│
├── Does the work need a browser (page, context)?
│   ├── YES → Use a setup project, not globalSetup
│   └── NO  → globalSetup is appropriate
│
├── Does every test need unique/isolated data?
│   ├── YES → Use a fixture with test.extend()
│   └── NO  → globalSetup for shared, read-only data
│
├── Is it per-worker (expensive resource, connection pool)?
│   ├── YES → Worker-scoped fixture
│   └── NO  → globalSetup for truly global, one-time work
│
└── Is it cleanup?
    ├── After all tests → globalTeardown
    ├── After each test → Fixture teardown (after use())
    └── After each worker → Worker-scoped fixture teardown
```

## Anti-Patterns

| Anti-Pattern | Problem | Do This Instead |
|---|---|---|
| Browser login in `globalSetup` | No browser context available; complex workarounds | Use a setup project with `dependencies` |
| Creating per-test data in `globalSetup` | All tests share the same data; not isolated | Use per-test fixtures for unique data |
| `globalSetup` without `globalTeardown` | Database or services left in dirty state | Always pair setup with teardown |
| Storing setup results in module-level variables | Workers are separate processes; variables don't share | Use environment variables or files |
| Complex logic in `globalSetup` | Hard to debug; runs outside normal test lifecycle | Keep it minimal: seed, verify, set env vars |
| `globalSetup` that takes > 60 seconds | Slows every test run, even for a single test | Move heavy work to a separate script or CI step |
| Relying on `globalTeardown` for critical cleanup | If the process crashes, `globalTeardown` might not run | Design tests to be idempotent; use `beforeAll` in setup project |

## Troubleshooting

### Global setup runs but environment variables are not available in tests

**Cause**: Each worker is a separate process. `process.env` mutations in `globalSetup` propagate to workers, but only if set before workers spawn.

**Fix**: Set environment variables at the top level of `globalSetup`, before any async work that might delay:

```ts
// tests/global-setup.ts
async function globalSetup() {
  // This works -- set before returning
  process.env.TEST_RUN_ID = `run-${Date.now()}`;
}
export default globalSetup;
```

If environment variables are still missing, write data to a file instead (Pattern 4, Method 2).

### Global setup fails with "Cannot find module"

**Cause**: The path in `globalSetup` is relative to the config file, but the module resolution is wrong.

**Fix**: Use a path relative to the project root:

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: './tests/global-setup.ts',   // relative to config location
  globalTeardown: './tests/global-teardown.ts',
});
```

### Global teardown doesn't run after test failure

**Cause**: If the process is killed (SIGKILL, OOM) rather than exiting normally, teardown is skipped.

**Fix**: Design your setup to be idempotent. Global setup should handle a dirty state from a previous incomplete run:

```ts
// tests/global-setup.ts
async function globalSetup() {
  // Always reset first, then seed -- handles dirty state
  const { execSync } = await import('child_process');
  execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
  execSync('npx prisma db seed', { stdio: 'inherit' });
}
export default globalSetup;
```

### Setup project runs every time, even when only running one test file

**Cause**: The `dependencies` configuration requires the setup project to run before any dependent project.

**Fix**: This is expected behavior. To skip setup during focused debugging:

```bash
# Skip setup by running without dependencies
npx playwright test --project=chromium --no-deps tests/specific-test.spec.ts
```

### `storageState` file doesn't exist when tests start

**Cause**: The setup project or `globalSetup` that creates the file failed silently, or the path is wrong.

**Fix**: Add explicit error handling and verify the file exists:

```ts
// tests/global.setup.ts
import { test as setup, expect } from '@playwright/test';
import * as fs from 'fs';

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 });

  // Verify the file was created
  if (!fs.existsSync(authFile)) {
    throw new Error(`Auth state file was not created at ${authFile}`);
  }
});
```

## Related

- [core/fixtures-and-hooks.md](../core/fixtures-and-hooks.md) -- per-test and per-worker fixtures (preferred over globalSetup for most cases)
- [core/configuration.md](../core/configuration.md) -- `globalSetup`, `globalTeardown`, `webServer` config
- [ci/projects-and-dependencies.md](projects-and-dependencies.md) -- setup projects with `dependencies`
- [core/authentication.md](../core/authentication.md) -- authentication patterns using setup projects
- [core/test-data-management.md](../core/test-data-management.md) -- seeding and managing test data
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall