Scaffolding Playwright Projects

Instructions

1. Framework Structure

Always enforce this directory structure for scalability:

/
├── tests/              # Test files (.spec.ts)
├── pages/              # Page Object Models
├── utils/              # Helper functions and hooks
├── fixtures/           # Test fixtures (data or custom objects)
├── reports/            # Output directory for test results
├── playwright.config.ts # Core configuration
└── package.json

2. Standard playwright.config.ts Template

Generate a config that includes:

• Parallelism: Fully parallel by default.
• Reporting: List, HTML, and JUnit (for CI).
• Traces: on-first-retry to save storage while assisting debugging.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
  ],
});

3. Page Object Model (POM) Guidelines

• Encapsulation: Components should hide internal selectors and expose only high-level actions.
• Locators: Prefer User-Facing Locators (e.g., getByRole, getByText) over fragile CSS/XPath.
• Assertions: Keep assertions in the test files, not inside Page Objects (unless for state verification).

Resources

• Example Page Object
• Custom Reporter Template

Implementation Details

Example Page Object

Create in .agent/skills/scaffolding-playwright-projects/examples/base-page.ts:

import { Page, Locator } from '@playwright/test';

export class BasePage {
  readonly page: Page;

  constructor(page: Page) {
    this.page = page;
  }

  async navigate(path: string) {
    await this.page.goto(path);
  }

  async waitForNetworkIdle() {
    await this.page.waitForLoadState('networkidle');
  }
}

Custom Reporter

Create in .agent/skills/scaffolding-playwright-projects/resources/custom-reporter.ts:

import { Reporter, TestCase, TestResult } from '@playwright/test/reporter';

class MyReporter implements Reporter {
  onTestEnd(test: TestCase, result: TestResult) {
    if (result.status !== 'passed') {
      console.log(`❌ Test ${test.title} failed with status: ${result.status}`);
    }
  }
}
export default MyReporter;