automation-harness-bootstrapper

tests/
  e2e/
    smoke/
      home.spec.ts          # one example smoke test (Step 4)
  fixtures/
    base.ts                 # extended test fixture (Step 3)
  pages/
    BasePage.ts             # page-object base class (Step 3)
    HomePage.ts             # example concrete page object
playwright.config.ts        # Step 5 configuration
.github/
  workflows/
    e2e.yml                 # CI job (Step 5)

// tests/pages/BasePage.ts
import { type Page } from "@playwright/test";

export abstract class BasePage {
  // Raw page is protected, not public - callers use typed action methods.
  protected constructor(protected readonly page: Page) {}

  async navigateTo(path: string): Promise<void> {
    await this.page.goto(path);
  }
}

// tests/pages/HomePage.ts
import { type Page, type Locator } from "@playwright/test";
import { BasePage } from "./BasePage";

export class HomePage extends BasePage {
  readonly heading: Locator;

  constructor(page: Page) {
    super(page);
    // Locators captured once in constructor - single place to update selectors
    this.heading = page.locator("h1").first();
  }

  async open(): Promise<void> {
    await this.navigateTo("/");
  }
}

// tests/fixtures/base.ts
import { test as base } from "@playwright/test";
import { HomePage } from "../pages/HomePage";

type Fixtures = { homePage: HomePage };

export const test = base.extend<Fixtures>({
  homePage: async ({ page }, use) => {
    await use(new HomePage(page));
  },
});

export { expect } from "@playwright/test";

// tests/e2e/smoke/home.spec.ts
import { test, expect } from "../../fixtures/base";

test("home page loads", async ({ homePage }) => {
  await homePage.open();
  // Assertion lives in the test, never in the page object
  await expect(homePage.heading).toBeVisible();
});

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests/e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,   // [playwright-config]: "useful for CI pipelines"
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: "html",
  use: {
    baseURL: process.env.BASE_URL ?? "http://localhost:3000",
    trace: "on-first-retry",
  },
  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
});

# .github/workflows/e2e.yml
name: E2E
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          CI: true

// cypress.config.ts
import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: process.env.BASE_URL ?? "http://localhost:3000",
    specPattern: "cypress/e2e/**/*.cy.{js,jsx,ts,tsx}",
    supportFile: "cypress/support/e2e.ts",
    setupNodeEvents(on, config) { return config; },
  },
});

// cypress/support/e2e.ts  - loads shared commands per [cyx]
import "./commands";

// cypress/support/commands.ts
Cypress.Commands.add("openHome", () => cy.visit("/"));
declare global {
  namespace Cypress { interface Chainable { openHome(): Chainable<void> } }
}

// cypress/e2e/home.cy.ts  - one smoke test; assertions live in the test
describe("home page", () => {
  it("loads", () => {
    cy.visit("/");
    cy.get("h1").should("be.visible");
  });
});

# .github/workflows/e2e.yml - runner: cypress
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: cypress-io/github-action@v7
        with:
          start: npm run dev
          wait-on: "http://localhost:3000"

## Harness scaffold - <repo> - <stack> + <runner>

### Files written
- `playwright.config.ts` - runner config with CI flags and webServer
- `tests/pages/BasePage.ts` - abstract page-object base
- `tests/pages/HomePage.ts` - example concrete page object
- `tests/fixtures/base.ts` - extended fixture wiring page objects
- `tests/e2e/smoke/home.spec.ts` - smoke test (1 test)
- `.github/workflows/e2e.yml` - CI job

### Next step
Run `npx playwright install --with-deps chromium` then `npx playwright test`.
Hand off to **spec-to-e2e-test-scaffolder** (qa-web-e2e) to generate further
spec files, or to **js-test-author** (qa-unit-tests-js) for unit layer coverage.