zebbern/claude-code-guide / skills/playwright/ci
playwright-ci
VerifiedProduction-ready CI/CD configurations for Playwright — GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Docker, parallel sharding, reporting, code coverage, and global setup/teardown.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| ci-github-actions.md | markdown | 17.1 KB |
| ci-gitlab.md | markdown | 12.3 KB |
| ci-other.md | markdown | 16.1 KB |
| docker-and-containers.md | markdown | 13.7 KB |
| global-setup-teardown.md | markdown | 17.8 KB |
| parallel-and-sharding.md | markdown | 15.8 KB |
| projects-and-dependencies.md | markdown | 18.8 KB |
| reporting-and-artifacts.md | markdown | 16.9 KB |
| test-coverage.md | markdown | 15.3 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, no Playwright fixtures. Pure Node.js.
- 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 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` has no browser. 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,
}),
})
// Return a cleanup function (Playwright calls globalTeardown separately)
// For cleanup, use globalTeardown
}
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |