testdino-hq/playwright-skill / 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.1 KB |
| ci-github-actions.md | markdown | 18.0 KB |
| ci-gitlab.md | markdown | 10.8 KB |
| ci-other.md | markdown | 15.1 KB |
| docker-and-containers.md | markdown | 14.3 KB |
| global-setup-teardown.md | markdown | 17.7 KB |
| parallel-and-sharding.md | markdown | 16.1 KB |
| projects-and-dependencies.md | markdown | 19.1 KB |
| reporting-and-artifacts.md | markdown | 20.1 KB |
| test-coverage.md | markdown | 13.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
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 |