Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

infrastructure-ci-cd/gitlab.md

View on GitHub
# GitLab CI/CD Configuration

## Table of Contents

1. [Key Commands](#key-commands)
2. [Patterns](#patterns)
3. [Decision Guide](#decision-guide)
4. [Anti-Patterns](#anti-patterns)
5. [Troubleshooting](#troubleshooting)

> **When to use**: Running Playwright tests in GitLab pipelines on merge requests, merges to main, or scheduled pipelines.

## Key Commands

```bash
npx playwright install --with-deps    # install browsers + OS deps
npx playwright test --shard=1/4       # run 1 of 4 parallel shards
npx playwright merge-reports ./blob-report  # merge shard results
npx playwright test --reporter=dot    # minimal output for CI logs
```

## Patterns

### Basic Pipeline Configuration

**Use when**: Any GitLab project with Playwright tests.

```yaml
# .gitlab-ci.yml
image: mcr.microsoft.com/playwright:v1.48.0-noble

stages:
    - install
    - test
    - report

variables:
    CI: 'true'
    npm_config_cache: '$CI_PROJECT_DIR/.npm'

cache:
    key:
        files:
            - package-lock.json
    paths:
        - .npm/
        - node_modules/

setup:
    stage: install
    script:
        - npm ci
    artifacts:
        paths:
            - node_modules/
        expire_in: 1 hour

e2e:
    stage: test
    needs: [setup]
    script:
        - npx playwright test
    artifacts:
        when: always
        paths:
            - playwright-report/
            - test-results/
        expire_in: 14 days
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

### Sharded Parallel Execution

**Use when**: Test suite exceeds 10 minutes. GitLab's `parallel` keyword splits across jobs automatically.
**Avoid when**: Suite runs under 5 minutes.

```yaml
image: mcr.microsoft.com/playwright:v1.48.0-noble

stages:
    - install
    - test
    - report

variables:
    CI: 'true'
    npm_config_cache: '$CI_PROJECT_DIR/.npm'

cache:
    key:
        files:
            - package-lock.json
    paths:
        - .npm/
        - node_modules/

setup:
    stage: install
    script:
        - npm ci
    artifacts:
        paths:
            - node_modules/
        expire_in: 1 hour

e2e:
    stage: test
    needs: [setup]
    parallel: 4
    script:
        - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
    artifacts:
        when: always
        paths:
            - blob-report/
        expire_in: 1 hour
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

combine-reports:
    stage: report
    needs: [e2e]
    when: always
    script:
        - npx playwright merge-reports --reporter=html ./blob-report
    artifacts:
        when: always
        paths:
            - playwright-report/
        expire_in: 14 days
```

**Config for sharded pipelines:**

```typescript
// playwright.config.ts
export default defineConfig({
	reporter: process.env.CI ? [['blob'], ['dot']] : [['html', { open: 'on-failure' }]]
});
```

### Environment Variables and Secrets

**Use when**: Tests need secrets (API keys, passwords) and should only run on merge requests or the default branch.

```yaml
image: mcr.microsoft.com/playwright:v1.48.0-noble

stages:
    - test

variables:
    CI: 'true'

e2e:staging:
    stage: test
    variables:
        BASE_URL: $STAGING_URL
        TEST_PASSWORD: $TEST_PASSWORD
        API_KEY: $API_KEY
    before_script:
        - npm ci
    script:
        - npx playwright test
    artifacts:
        when: always
        paths:
            - playwright-report/
            - test-results/
        expire_in: 14 days
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
        - when: manual
          allow_failure: true
```

**Setting variables in GitLab:**
Navigate to **Settings > CI/CD > Variables** and add:

- `STAGING_URL` -- not masked, not protected
- `TEST_PASSWORD` -- masked, protected
- `API_KEY` -- masked, protected

### Multi-Browser Matrix

**Use when**: Running Chromium on MRs and all browsers on the default branch.

```yaml
image: mcr.microsoft.com/playwright:v1.48.0-noble

stages:
    - install
    - test

variables:
    CI: 'true'

setup:
    stage: install
    script:
        - npm ci
    artifacts:
        paths:
            - node_modules/
        expire_in: 1 hour

e2e:chromium:
    stage: test
    needs: [setup]
    script:
        - npx playwright test --project=chromium
    artifacts:
        when: always
        paths:
            - playwright-report/
            - test-results/
        expire_in: 14 days
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"

e2e:all-browsers:
    stage: test
    needs: [setup]
    parallel:
        matrix:
            - PROJECT: [chromium, firefox, webkit]
    script:
        - npx playwright test --project=$PROJECT
    artifacts:
        when: always
        paths:
            - playwright-report/
            - test-results/
        expire_in: 14 days
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

### Services Integration (Database, Cache)

**Use when**: Tests need the application running alongside Playwright, or you need external services.

```yaml
stages:
    - test

e2e:integration:
    stage: test
    image: mcr.microsoft.com/playwright:v1.48.0-noble
    services:
        - name: postgres:latest
          alias: db
        - name: redis:latest
          alias: cache
    variables:
        CI: 'true'
        DATABASE_URL: 'postgresql://postgres:postgres@db:5432/testdb'
        REDIS_URL: 'redis://cache:6379'
        POSTGRES_PASSWORD: 'postgres'
        POSTGRES_DB: 'testdb'
    before_script:
        - npm ci
        - npx prisma db push
        - npx prisma db seed
    script:
        - npx playwright test
    artifacts:
        when: always
        paths:
            - playwright-report/
            - test-results/
        expire_in: 14 days
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

### Scheduled Nightly Regression

**Use when**: Full regression is too slow for every MR.

```yaml
e2e:nightly:
    stage: test
    image: mcr.microsoft.com/playwright:v1.48.0-noble
    before_script:
        - npm ci
    script:
        - npx playwright test --grep @regression
    artifacts:
        when: always
        paths:
            - playwright-report/
        expire_in: 30 days
    rules:
        - if: $CI_PIPELINE_SOURCE == "schedule"
```

Set up the schedule in **CI/CD > Schedules**: `0 3 * * 1-5` (3 AM UTC, weekdays).

## Decision Guide

| Scenario                             | Approach                                               | Why                                                 |
| ------------------------------------ | ------------------------------------------------------ | --------------------------------------------------- |
| Simple project, < 5 min suite        | Single `test` job using Playwright Docker image        | No sharding overhead; artifacts capture report      |
| Suite > 10 min                       | `parallel: N` with `--shard`                           | GitLab auto-assigns `CI_NODE_INDEX`/`CI_NODE_TOTAL` |
| Merge request fast feedback          | Chromium only on MRs; all browsers on main             | 3x fewer pipeline minutes on MRs                    |
| External services needed (DB, Redis) | `services:` keyword with Postgres/Redis images         | GitLab manages service lifecycle                    |
| Secrets for staging environment      | GitLab CI/CD Variables (masked + protected)            | Never hardcode secrets in `.gitlab-ci.yml`          |
| Full nightly regression              | Pipeline schedule (`CI_PIPELINE_SOURCE == "schedule"`) | Avoids blocking MR pipelines                        |
| Report browsing                      | `artifacts:` with `paths: [playwright-report/]`        | Browse directly in GitLab job artifacts UI          |

## Anti-Patterns

| Anti-Pattern                                         | Problem                                                            | Do This Instead                                                           |
| ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| Not using the Playwright Docker image                | Installing browsers every run adds 1-2 minutes                     | Use `mcr.microsoft.com/playwright:v1.48.0-noble` as base image            |
| `artifacts: when: on_failure` only                   | No report when tests pass; can't verify results                    | Use `when: always` to capture reports regardless                          |
| No `expire_in` on artifacts                          | Artifacts accumulate and consume storage                           | Set `expire_in: 14 days` for reports, `1 hour` for intermediate artifacts |
| Hardcoding `CI_NODE_TOTAL` in shard flag             | Breaks when you change `parallel:` value                           | Use `--shard=$CI_NODE_INDEX/$CI_NODE_TOTAL`                               |
| Skipping `needs:` between stages                     | Jobs wait for all previous stage jobs, not just their dependencies | Use `needs:` for precise dependency graphs                                |
| Large `cache:` including `node_modules/` without key | Stale cache causes version conflicts                               | Key cache on `package-lock.json` hash                                     |

## Troubleshooting

### Browser launch fails: "Failed to launch browser"

**Cause**: Not using the Playwright Docker image, or using a version that doesn't match your `@playwright/test` version.

**Fix**: Match the Docker image tag to your Playwright version:

```yaml
# Check your version: npm ls @playwright/test
image: mcr.microsoft.com/playwright:v1.48.0-noble
```

### Tests hang in GitLab runner: "Navigation timeout exceeded"

**Cause**: GitLab shared runners may have limited resources.

**Fix**: Reduce workers and increase timeouts:

```typescript
export default defineConfig({
	workers: process.env.CI ? 2 : undefined,
	use: {
		navigationTimeout: process.env.CI ? 30_000 : 15_000
	}
});
```

### Pipeline runs on every push, not just merge requests

**Cause**: Missing `rules:` configuration.

**Fix**: Add explicit rules:

```yaml
rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

### Services (Postgres/Redis) not reachable from tests

**Cause**: Using `localhost` instead of the service alias.

**Fix**: Use the service alias as hostname:

```yaml
services:
    - name: postgres:latest
      alias: db

variables:
    DATABASE_URL: 'postgresql://postgres:postgres@db:5432/testdb'
```

### Merged report is empty after sharded run

**Cause**: Each shard job needs the `blob` reporter, not `html`.

**Fix**: Configure blob reporter for CI:

```typescript
export default defineConfig({
	reporter: process.env.CI ? [['blob'], ['dot']] : [['html', { open: 'on-failure' }]]
});
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall