Playwright Testing Framework Standards

Core Principles

Five non-negotiable rules that govern every test. These drive architecture decisions and reviewer expectations — all five must hold for every PR.

Project Structure

Every directory has a single responsibility. Files are domain-grouped, not type-grouped. Tests are separated by layer: api/ for request-level, ui/ for browser-level.

Code Standards

ESLint and Prettier are non-negotiable — zero warnings allowed in CI. TypeScript strict mode enforced via compiler options. All settings checked into version control.

// ✅ Type imports separated
import type { Page, APIRequestContext } from '@playwright/test'
import { test, expect } from '@playwright/test'
import { createUser } from '@/functions/users'

// ❌ Mixed type + value imports
import { Page, test } from '@playwright/test'

Custom Fixtures — BasePage

BasePage wraps Page via a Proxy, transparently forwarding all native page calls while adding an authenticated API context and session caching on top.

fixtures/BasePage.tsexport class BasePage {
  public  page: Page
  private api: APIRequestContext | null = null

  constructor(page: Page) {
    this.page = page
    // Proxy delegates unknown props to the inner Page instance
    return new Proxy(this, {
      get(target, prop) {
        return prop in target ? target[prop] : target.page[prop]
      }
    })
  }

  async getAPI(): Promise<APIRequestContext> {
    if (!this.api) {
      const cookies = await this.page.context().cookies()
      const token   = cookies.find(c => c.name === 'auth_token')?.value
      this.api = await this.page.request.newContext({
        extraHTTPHeaders: { 'Authorization': `Bearer ${token}` }
      })
    }
    return this.api
  }
}

BaseAPI & Fixture Registration

BaseAPI is a standalone context for API-only tests — no browser overhead. Both fixtures are registered once in fixtures/index.ts via test.extend and re-exported.

fixtures/BaseAPI.tsexport class BaseAPI {
  public apiContext: APIRequestContext

  async init(token: string) {
    this.apiContext = await request.newContext({
      baseURL: process.env.BASE_URL,
      extraHTTPHeaders: {
        'Authorization': `Bearer ${token}`,
        'Content-Type':  'application/json'
      }
    })
  }

  get(url: string, opts?: any) {
    return this.apiContext.get(url, opts)
  }
  post(url: string, opts?: any) {
    return this.apiContext.post(url, opts)
  }
  delete(url: string, opts?: any) {
    return this.apiContext.delete(url, opts)
  }
}

fixtures/index.tsexport type CustomPage = BasePage & Page

export const test = base.extend<MyFixtures>({

  customPage: async ({ page }, use) => {
    await use(new BasePage(page) as CustomPage)
  },

  apiContext: async ({}, use) => {
    const api = new BaseAPI()
    await api.init(process.env.API_TOKEN!)
    await use(api)
    await api.dispose()
  }

})

export { expect } from '@playwright/test'

Helper Functions

Helpers in functions/ are domain-grouped and overloaded to accept either BasePage or BaseAPI — the same createUser call works from a UI test or an API test.

functions/common.tsimport { faker } from '@faker-js/faker'

export function generateUserData() {
  return {
    email:    `${faker.string.alphanumeric(10)}@test.com`,
    password: faker.internet.password({ length: 12 })
  }
}

functions/users.ts// Overload signatures
export async function createUser(
  page: BasePage, data: UserData
): Promise<string>
export async function createUser(
  api: BaseAPI, data: UserData
): Promise<string>

// Shared implementation
export async function createUser(
  fixture: any, data: UserData
): Promise<string> {
  const api = await fixture.getAPI()
  const res = await api.post('/api/users', { data })
  return (await res.json()).id
}

Test Design Patterns

Every test follows Feature > Section > Action naming with a unique annotation ID. Arrange-Act-Assert structure with cleanup baked in as the final step.

tests/ui/users.spec.tstest('User Management > Profile > Edit first name',
{ annotation: { type: 'ID', description: 'USR-042' } },
async ({ customPage: page }) => {
  // Arrange
  const userId = await createUser(page, generateUserData())

  // Act
  await page.goto(`/users/${userId}/edit`)
  await page.getByLabel('First Name').fill('Updated')
  await page.getByRole('button', { name: 'Save' }).click()

  // Assert
  await expect(page.getByText('Profile updated')).toBeVisible()

  // Cleanup — runs even when assertions fail via test.afterEach
  await deleteUser(page, userId)
})

Data Management

Tests create unique data to avoid parallel conflicts. API cleanup is faster and preferred over UI. All config lives in environment variables — no hardcoded URLs or credentials.

// ✅ Unique — safe for parallel runs
const name = `Product-${Date.now()}`

// ❌ Hardcoded — conflicts in parallel
const name = 'Test Product'

let userId: string

test.beforeAll(async ({ apiContext }) => {
  userId = await createUser(apiContext, generateUserData())
})
test.afterAll(async ({ apiContext }) => {
  await deleteUser(apiContext, userId)
})

.env.exampleBASE_URL=https://app.example.com
API_TOKEN=your_token_here
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=SecurePass123

// Remove leftovers from interrupted runs
test.beforeAll(async ({ apiContext }) => {
  const stale = await getUsers(
    apiContext, { email: 'test@example.com' }
  )
  for (const u of stale) {
    await deleteUser(apiContext, u.id)
  }
})

Custom Reporters

The custom reporter tracks per-test history (last 10 runs) and automatically marks flaky tests — passed on retry. Results persist to a JSON file scoped by ENV variable.

reporter/reporter.tsclass CustomReporter implements Reporter {
  private runId = Date.now().toString()

  onTestEnd(test: TestCase, result: TestResult): void {
    const annotation = result.annotations.find(a => a.type === 'ID')
    const entry: TestResultEntry = {
      time:    new Date().toISOString(),
      result:  result.status,
      file:    path.basename(test.location?.file ?? 'unknown'),
      retried: result.retry > 0,
      flaky:   result.retry > 0 && result.status === 'passed',
      testId:  annotation?.description ?? 'NO-ID',
      runId:   this.runId
    }
    const history = this.results.tests[test.title] ??= []
    if (history.length >= 10) history.shift()
    history.push(entry)
  }
}

CI/CD Integration

Tests run nightly and on every pull request. CI enforces stricter settings: forbidOnly blocks committed test.only calls, 1 retry, 2 workers. Artifacts retained 30 days.

.github/workflows/playwright.ymlon:
  schedule:
    - cron: '0 2 * * *'   # nightly at 02:00
  pull_request:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

playwright.config.tsexport default defineConfig({
  testDir:       './tests',
  fullyParallel: true,
  forbidOnly:    !!process.env.CI,
  retries:       process.env.CI ? 1 : 0,
  workers:       process.env.CI ? 2 : undefined,
  use: {
    baseURL:    process.env.BASE_URL,
    trace:      'on-first-retry',
    screenshot: 'only-on-failure',
    video:      'retain-on-failure'
  },
  projects: [
    { name: 'setup',    testMatch: /.*\.setup\.ts/   },
    { name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      dependencies: ['setup'] },
    { name: 'api',       testMatch: /.*\.api\.test\.ts/ }
  ]
})

PR Checklist & Best Practices

Every PR must pass all checklist items before requesting review. A test that passes once is not enough — run 3+ times locally without failure.