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 |
projects-and-dependencies.md
View on GitHub# Projects and Dependencies
> **When to use**: Running tests across multiple browsers, devices, or environments from a single config. Projects let you define different test configurations that can depend on each other, share setup work, and run selectively.
## Quick Reference
```bash
# Run all projects
npx playwright test
# Run a specific project
npx playwright test --project=chromium
npx playwright test --project="Mobile Safari"
# Run multiple projects
npx playwright test --project=chromium --project=firefox
# List all projects and their tests
npx playwright test --list
# Skip dependencies (e.g., skip setup during debugging)
npx playwright test --project=chromium --no-deps
```
## Patterns
### Pattern 1: Multi-Browser Testing
**Use when**: Ensuring your application works across Chromium, Firefox, and WebKit.
**Avoid when**: Early development -- start with Chromium only and add browsers later.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
fullyParallel: true,
projects: [
{
name: "chromium",
use: { ...devices["Desktop Chrome"] },
},
{
name: "firefox",
use: { ...devices["Desktop Firefox"] },
},
{
name: "webkit",
use: { ...devices["Desktop Safari"] },
},
],
})
```
**Selective browser testing in CI (fast on PRs, thorough on main):**
```yaml
# .github/workflows/ci.yml
jobs:
test-pr:
if: github.event_name == 'pull_request'
steps:
# Chromium only on PRs for fast feedback
- run: npx playwright test --project=chromium
test-main:
if: github.ref == 'refs/heads/main'
steps:
# All browsers on main branch
- run: npx playwright test
```
### Pattern 2: Desktop and Mobile Projects
**Use when**: Testing responsive layouts, touch interactions, or mobile-specific behavior.
**Avoid when**: Your application is desktop-only.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
fullyParallel: true,
projects: [
// Desktop browsers
{
name: "Desktop Chrome",
use: { ...devices["Desktop Chrome"] },
},
{
name: "Desktop Firefox",
use: { ...devices["Desktop Firefox"] },
},
{
name: "Desktop Safari",
use: { ...devices["Desktop Safari"] },
},
// Mobile devices
{
name: "Mobile Chrome",
use: { ...devices["Pixel 7"] },
},
{
name: "Mobile Safari",
use: { ...devices["iPhone 14"] },
},
// Tablet
{
name: "iPad",
use: { ...devices["iPad Pro 11"] },
},
],
})
```
**Run only mobile or only desktop:**
```bash
npx playwright test --project="Mobile Chrome" --project="Mobile Safari"
npx playwright test --project="Desktop Chrome" --project="Desktop Firefox"
```
### Pattern 3: Setup Project with Dependencies
**Use when**: Tests need shared state (authentication, seeded data) that should be created once before all test projects run.
**Avoid when**: Tests are fully independent with no shared setup phase.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
projects: [
// Setup runs first -- no dependencies, so it runs immediately
{
name: "setup",
testMatch: /global\.setup\.ts/,
},
// Browser projects depend on setup
{
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()
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
await page.context().storageState({ path: authFile })
})
```
**How dependencies work:**
1. Playwright identifies projects with no dependencies and runs them first.
2. Once a dependency project completes successfully, dependent projects start.
3. If a dependency project fails, all dependent projects are skipped.
### Pattern 4: Multiple Auth Roles
**Use when**: Tests need different user roles (admin, editor, viewer) with separate auth states.
**Avoid when**: All tests use the same user -- use a single setup project.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
projects: [
// Auth setup for each role
{
name: "auth-admin",
testMatch: /auth\.setup\.ts/,
use: {
userRole: "admin",
storageStatePath: "playwright/.auth/admin.json",
},
},
{
name: "auth-editor",
testMatch: /auth\.setup\.ts/,
use: {
userRole: "editor",
storageStatePath: "playwright/.auth/editor.json",
},
},
// Admin tests
{
name: "admin-tests",
testDir: "./tests/admin",
use: {
...devices["Desktop Chrome"],
storageState: "playwright/.auth/admin.json",
},
dependencies: ["auth-admin"],
},
// Editor tests
{
name: "editor-tests",
testDir: "./tests/editor",
use: {
...devices["Desktop Chrome"],
storageState: "playwright/.auth/editor.json",
},
dependencies: ["auth-editor"],
},
// Unauthenticated tests (no dependencies, no storageState)
{
name: "public-tests",
testDir: "./tests/public",
use: { ...devices["Desktop Chrome"] },
},
],
})
```
```ts
// tests/auth.setup.ts
import { test as setup, expect } from "@playwright/test"
const credentials: Record<string, { email: string; password: string }> = {
admin: { email: "admin@example.com", password: process.env.ADMIN_PASSWORD! },
editor: { email: "editor@example.com", password: process.env.EDITOR_PASSWORD! },
}
setup("authenticate", async ({ page }, testInfo) => {
const role = testInfo.project.use.userRole as string
const authFile = testInfo.project.use.storageStatePath as string
const { email, password } = credentials[role]
await page.goto("/login")
await page.getByLabel("Email").fill(email)
await page.getByLabel("Password").fill(password)
await page.getByRole("button", { name: "Sign in" }).click()
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
await page.context().storageState({ path: authFile })
})
```
### Pattern 5: Environment-Specific Projects
**Use when**: Running the same tests against different environments (dev, staging, production) from one config.
**Avoid when**: You only test one environment.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
const ENV = process.env.TEST_ENV || "local"
const envConfig: Record<string, { baseURL: string; retries: number }> = {
local: { baseURL: "http://localhost:3000", retries: 0 },
staging: { baseURL: "https://staging.example.com", retries: 2 },
production: { baseURL: "https://www.example.com", retries: 2 },
}
const env = envConfig[ENV]
export default defineConfig({
testDir: "./tests",
retries: env.retries,
use: {
baseURL: env.baseURL,
},
projects: [
{
name: "chromium",
use: { ...devices["Desktop Chrome"] },
},
// Only run smoke tests in production
...(ENV === "production"
? [
{
name: "smoke",
testMatch: "**/*smoke*.spec.ts",
use: { ...devices["Desktop Chrome"] },
grep: /@smoke/,
},
]
: []),
],
})
```
```bash
# Run against different environments
TEST_ENV=local npx playwright test
TEST_ENV=staging npx playwright test
TEST_ENV=production npx playwright test --project=smoke
```
### Pattern 6: Project with Custom `testDir` and `testMatch`
**Use when**: Different projects need different test directories or file patterns.
**Avoid when**: All projects run the same tests.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
projects: [
// E2E tests -- run in all browsers
{
name: "e2e-chromium",
testDir: "./tests/e2e",
testMatch: "**/*.spec.ts",
use: { ...devices["Desktop Chrome"] },
},
{
name: "e2e-firefox",
testDir: "./tests/e2e",
testMatch: "**/*.spec.ts",
use: { ...devices["Desktop Firefox"] },
},
// API tests -- no browser needed, run once
{
name: "api",
testDir: "./tests/api",
testMatch: "**/*.spec.ts",
use: {
baseURL: "https://api.example.com",
},
},
// Visual regression -- Chromium only
{
name: "visual",
testDir: "./tests/visual",
testMatch: "**/*.spec.ts",
use: {
...devices["Desktop Chrome"],
// Lock viewport for consistent screenshots
viewport: { width: 1280, height: 720 },
},
},
],
})
```
```bash
# Run only API tests
npx playwright test --project=api
# Run only visual tests
npx playwright test --project=visual
# Run all E2E tests
npx playwright test --project=e2e-chromium --project=e2e-firefox
```
### Pattern 7: Teardown Projects
**Use when**: You need browser-based cleanup after tests complete (e.g., deleting test data via the UI).
**Avoid when**: Cleanup can be done via API in `globalTeardown` or fixtures (the usual case).
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
projects: [
{
name: "setup",
testMatch: /global\.setup\.ts/,
teardown: "teardown", // link to teardown project
},
{
name: "teardown",
testMatch: /global\.teardown\.ts/,
},
{
name: "chromium",
use: {
...devices["Desktop Chrome"],
storageState: "playwright/.auth/user.json",
},
dependencies: ["setup"],
},
],
})
```
```ts
// tests/global.teardown.ts
import { test as teardown } from "@playwright/test"
teardown("clean up test data", async ({ request }) => {
await request.post("/api/test/cleanup", {
headers: { Authorization: `Bearer ${process.env.ADMIN_API_KEY}` },
})
})
```
**Execution order:**
1. `setup` project runs
2. `chromium` project runs (depends on setup)
3. `teardown` project runs (linked via setup's `teardown` field)
### Pattern 8: Grep and GrepInvert for Project Filtering
**Use when**: Different projects should run different subsets of tests based on tags.
**Avoid when**: All projects run all tests.
```ts
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
projects: [
// Smoke tests -- only @smoke tagged tests, Chromium only
{
name: "smoke",
use: { ...devices["Desktop Chrome"] },
grep: /@smoke/,
},
// Full regression -- everything except @slow, all browsers
{
name: "regression-chromium",
use: { ...devices["Desktop Chrome"] },
grepInvert: /@slow/,
},
{
name: "regression-firefox",
use: { ...devices["Desktop Firefox"] },
grepInvert: /@slow/,
},
// Slow tests -- only @slow, Chromium only, higher timeout
{
name: "slow",
use: { ...devices["Desktop Chrome"] },
grep: /@slow/,
timeout: 120_000,
},
],
})
```
```bash
# CI: run smoke on PRs
npx playwright test --project=smoke
# CI: run full regression on main
npx playwright test --project=regression-chromium --project=regression-firefox
# CI: run slow tests nightly
npx playwright test --project=slow
```
## Decision Guide
| Scenario | Number of Projects | Configuration |
| --------------------------------------- | ----------------------------------- | ------------------------------- |
| Getting started | 1 (chromium) | Single project, no dependencies |
| Cross-browser testing | 3 (chromium, firefox, webkit) | One per browser engine |
| Responsive design | 5-6 (desktop + mobile + tablet) | Use `devices` presets |
| Authenticated tests | 1 setup + N browser projects | Setup with `dependencies` |
| Multiple auth roles | N setup + N test projects | One setup project per role |
| Different test types (E2E, API, visual) | One per type | Custom `testDir` per project |
| Environment targeting | Same projects, different `baseURL` | Use `TEST_ENV` env var |
| Smoke vs regression suites | Projects with `grep` / `grepInvert` | Tag-based filtering |
| Feature | `dependencies` | `teardown` | `globalSetup` |
| --------------------------- | ------------------------------------- | --------------------------------------- | ------------------------------------ |
| Has browser context | Yes | Yes | No |
| Runs when | Before dependent projects | After linked setup project's dependents | Before all projects |
| Use for | Auth state, data seeding with browser | Browser-based cleanup | Non-browser setup (DB, health check) |
| Skips dependents on failure | Yes | N/A | Yes (entire suite fails) |
## Anti-Patterns
| Anti-Pattern | Problem | Do This Instead |
| ------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| All browsers on every PR | 3x CI time for marginal benefit | Chromium on PRs; all browsers on main |
| `dependencies` on projects that don't need shared state | Forced serial execution; slower | Only use dependencies when projects truly need shared state |
| Duplicating config across projects | Hard to maintain; settings drift | Use shared `use` at the top level; override per project |
| No `--project` filtering in CI | All projects always run; no control | Use `--project` to run subsets based on context |
| Setup project modifies database without teardown | Dirty state for next run | Always pair setup with teardown or make setup idempotent |
| Many projects with overlapping test directories | Same test runs multiple times unintentionally | Set explicit `testDir` and `testMatch` per project |
| Not using `--no-deps` for debugging | Setup runs every time, even for one test | Use `--no-deps` to skip dependencies during focused debugging |
## Troubleshooting
### "No tests found" when running specific project
**Cause**: The project's `testDir` or `testMatch` doesn't match any files.
**Fix**: List tests for the project to see what matches:
```bash
npx playwright test --project=chromium --list
```
Check that `testDir` and `testMatch` are correct:
```ts
{
name: 'chromium',
testDir: './tests', // must contain test files
testMatch: '**/*.spec.ts', // must match your file naming
}
```
### Setup project runs every time, even for a single test
**Cause**: The test's project has `dependencies: ['setup']`, so setup always runs first.
**Fix**: Use `--no-deps` to skip dependencies during development:
```bash
npx playwright test --project=chromium --no-deps tests/specific-test.spec.ts
```
### `storageState` file not found
**Cause**: Setup project failed or didn't create the file. Or the path in `use.storageState` doesn't match the path in the setup project.
**Fix**: Verify paths match exactly:
```ts
// In setup test:
await page.context().storageState({ path: "playwright/.auth/user.json" })
// In project config:
use: {
storageState: "playwright/.auth/user.json"
} // must match exactly
```
Add `.auth` to `.gitignore`:
```bash
echo "playwright/.auth/" >> .gitignore
```
### Dependent projects run even when setup fails
**Cause**: This should not happen -- Playwright skips dependent projects when a dependency fails. If it seems like they run, check that `dependencies` is spelled correctly.
**Fix**: Verify the dependency name matches exactly:
```ts
// Setup project name
{ name: 'setup', ... }
// Dependency reference (must match exactly, case-sensitive)
{ dependencies: ['setup'] } // correct
{ dependencies: ['Setup'] } // WRONG -- case mismatch
```
### Tests from multiple projects interfere with each other
**Cause**: Projects share a database or external state. Since projects run in parallel by default, they can collide.
**Fix**: Either:
1. Use per-project isolated data (different test users, different database schemas)
2. Run projects sequentially by adding artificial dependencies:
```ts
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
dependencies: ['chromium'], // forces serial execution
},
],
```
### Custom `use` properties cause TypeScript errors
**Cause**: Playwright's `use` type doesn't include your custom properties.
**Fix**: Extend the type or use `as any`:
```ts
// Option 1: Declare custom properties
declare module '@playwright/test' {
interface PlaywrightTestOptions {
userRole: string;
storageStatePath: string;
}
}
// Option 2: Quick fix (less type-safe)
{
name: 'auth-admin',
use: {
userRole: 'admin',
storageStatePath: 'playwright/.auth/admin.json',
} as any,
}
```
## Related
- [core/configuration.md](../core/configuration.md) -- base config, `projects`, `use` settings
- [ci/global-setup-teardown.md](global-setup-teardown.md) -- `globalSetup` vs setup projects
- [core/fixtures-and-hooks.md](../core/fixtures-and-hooks.md) -- option fixtures configured per project
- [core/authentication.md](../core/authentication.md) -- auth state via setup projects
- [ci/parallel-and-sharding.md](parallel-and-sharding.md) -- sharding across projects
- [ci/ci-github-actions.md](ci-github-actions.md) -- running specific projects in CI
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: 197k | Updated | Claude CodeCodex | Verified | Install |