@aleph-alpha/config-playwright

Shared Playwright configuration for Aleph Alpha frontend projects. Provides a spreadable config factory, a base Page Object Model class, and an authenticated test fixture.

What v1 ships

| Export | Type | Purpose | |---|---|---| | mountPlaywrightConfig | function | Returns a PlaywrightTestConfig object you spread into defineConfig | | BasePage | class | Base class for Page Object Models | | authenticatedTest | Playwright fixture | Drop-in for test in tests that require a logged-in session | | expect | re-export | Playwright's expect — import alongside authenticatedTest from one place |

Installation

@playwright/test is a peer dependency — you must install it alongside this package:

pnpm add -D @aleph-alpha/config-playwright @playwright/test

Usage

mountPlaywrightConfig

// playwright.config.ts
import { defineConfig } from '@playwright/test'
import { mountPlaywrightConfig } from '@aleph-alpha/config-playwright'

export default defineConfig({
  ...mountPlaywrightConfig({ baseURL: process.env['BASE_URL'] ?? 'http://localhost:4200' }),
  // Add any project-specific options after spreading:
  // webServer: { command: 'pnpm start', url: 'http://localhost:4200' },
})

Parameters

| Parameter | Type | Required | Default | |---|---|---|---| | baseURL | string | yes | — | | ci | boolean | no | !!process.env['CI'] |

ci is auto-detected from the CI environment variable. Pass it explicitly only to override detection (e.g. in scripts that run locally with CI semantics).

Config values returned

| Field | Local (ci=false) | CI (ci=true) | |---|---|---| | testDir | e2e | e2e | | timeout | 60 000 ms | 60 000 ms | | retries | 0 | 2 | | workers | undefined (Playwright default) | 1 | | forbidOnly | false | true | | use.storageState | .auth/state.json | .auth/state.json | | use.trace | on-first-retry | on-first-retry | | use.video | retain-on-failure | retain-on-failure | | use.screenshot | only-on-failure | only-on-failure | | reporter | [['html'], ['json', ...]] | [['html'], ['json', ...]] | | projects | Chromium + Firefox | Chromium + Firefox |

JSON reporter writes to test-results/results.json.

BasePage

Base class for the Page Object Model pattern. Extend it in your own POM files.

// e2e/pages/login.page.ts
import { BasePage } from '@aleph-alpha/config-playwright'
import type { Page } from '@playwright/test'

export class LoginPage extends BasePage {
  constructor(page: Page) {
    super(page)
  }

  async login(user: string, password: string) {
    await this.navigateTo('/login')
    await this.page.fill('[data-testid="username"]', user)
    await this.page.fill('[data-testid="password"]', password)
    await this.page.click('[type="submit"]')
    await this.waitForLoad()
  }
}

Methods

| Method | Signature | Description | |---|---|---| | navigateTo | (path: string) => Promise<void> | Calls page.goto(path) | | waitForLoad | () => Promise<void> | Waits for networkidle load state |

this.page is exposed as protected for use in subclasses.

authenticatedTest

Drop-in replacement for Playwright's test that pre-loads .auth/state.json as storageState.

// e2e/dashboard.spec.ts
import { authenticatedTest, expect } from '@aleph-alpha/config-playwright'

authenticatedTest('shows dashboard', async ({ page }) => {
  await page.goto('/dashboard')
  await expect(page.getByRole('heading')).toContainText('Dashboard')
})

Auth contract

authenticatedTest reads auth state from .auth/state.json. You must produce that file in your globalSetup before tests run.

// e2e/global-setup.ts  (wire up in your own playwright.config.ts)
import { chromium } from '@playwright/test'

export default async function globalSetup() {
  const browser = await chromium.launch()
  const page = await browser.newPage()

  await page.goto(process.env['BASE_URL'] + '/login')
  await page.fill('[name="username"]', process.env['E2E_USER']!)
  await page.fill('[name="password"]', process.env['E2E_PASSWORD']!)
  await page.click('[type="submit"]')

  await page.context().storageState({ path: '.auth/state.json' })
  await browser.close()
}

Reference it from your playwright.config.ts:

export default defineConfig({
  ...mountPlaywrightConfig({ baseURL: '...' }),
  globalSetup: './e2e/global-setup',
})

Environment variables

| Variable | Used by | Description | |---|---|---| | CI | mountPlaywrightConfig | Auto-enables CI mode (retries, forbidOnly, single worker) | | BASE_URL | your config | Base URL passed to mountPlaywrightConfig | | E2E_USER | your globalSetup | Auth username (not consumed by this package) | | E2E_PASSWORD | your globalSetup | Auth password (not consumed by this package) |

.gitignore additions

Add these to your app's .gitignore:

.auth/
test-results/
playwright-report/

Migration from v0.4.0

| v0.4.0 | v1 | |-------------------------------------------|---| | testDir: './src/e2e' | testDir: 'e2e' | | storageState: '/tmp/storage-state.json' | storageState: '.auth/state.json' | | globalSetup set to a non-existent path | globalSetup not set — wire your own in defineConfig | | slowMo: 800 on browser projects | removed | | reporter: 'html' | reporter: [['html'], ['json', { outputFile: 'test-results/results.json' }]] | | ci required | ci optional — defaults to !!process.env['CI'] | | No BasePage export | BasePage re-exported | | No authenticatedTest export | authenticatedTest + expect re-exported | | @playwright/test in dependencies | @playwright/test is now a peerDependency — add it explicitly to your app's devDependencies |