# Playwright Repo Structure · PW-01

This page shows the layout of a Playwright repository. Tests are organised following the [Page Object Model](/standards/engineering/coding-standards/playwright/page-object-model) standards, and files are named following the [TypeScript file naming](/standards/engineering/coding-standards/typescript/typescript-naming) standards.

## Standard Metadata

- Area: Playwright
- Owner: Technical Leadership group
- Last reviewed: 2026-10-07
- Next review due from: 2026-12-01
- Enforcement: Code review
- Status: Active

##  Project Structure

Names in `<angle brackets>` are placeholders: replace them with your project's own endpoints and pages. Every other file and folder name is part of the standard layout. The examples use the 'pet' and 'store' endpoints of the [Swagger Petstore](https://petstore.swagger.io/) API and a 'todo' page.

- `api`: Contains API related scripts and endpoint functionalities.
  - `api.ts`: Main API script that may contain configurations or common API-related functionalities.
  - `endpoints/`: A directory dedicated to individual API endpoint scripts. Each script in this directory represents a specific endpoint, encapsulating its associated functionalities, configurations, and methods. By modularising endpoints in this manner, the project ensures clarity, maintainability, and ease of expansion for future endpoints.
    - `<endpoint>.ts`: One file per API endpoint, for example `pet.ts` and `store.ts`.

- `fixtures`: Houses base test configurations, schema generators, and validator(s).
  - `baseExpect.ts`: An enhancement of the standard `expect` function from `@playwright/test`. At the moment this file provides an extended matcher, `toMatchSchema`, which validates if a given API response conforms to a specified schema
  - `baseTest.ts`: A foundational test configuration file that extends the core `test` functionality provided by `@playwright/test`. It establishes a unified testing context by integrating both API and page objects, thereby streamlining the setup for various test scenarios.
  - `schemaGenerator.ts`: Script to dynamically generate schemas, for validations.
  - `schemaValidator.ts`: Script responsible for validating data against predefined schemas.

- `helpers`: Utility scripts that aid in various tasks throughout the project.
  - `env.ts`: Manages environment-specific configurations and variables.
  - `randomString.ts`: A utility to generate random strings, for test data.
  - `setHeader.ts`: A script to set or manage headers for API requests.

- `pages`: A directory housing [Page Object Models (POM)](https://playwright.dev/docs/pom) that encapsulate specific interactions and elements for individual pages of the application. Each file within this directory represents a unique page, offering structured and reusable methods for tests to interact with that page.
  - `<page>.page.ts`: One page object per page, for example `todo.page.ts`, which defines the `TodoPage` class.

- `tests`: Houses the test scripts for both API and e2e tests.
  - `api-tests/`: This directory is dedicated to housing test scripts focused on API interactions and validations.
    - `<endpoint>/`: One folder per API endpoint, for example `pet/` and `store/`.
      - `<endpoint>.<method>.spec.ts`: One file per HTTP method (GET, POST, PUT, DELETE), for example `pet.get.spec.ts`.
  - `e2e-tests/`: A directory reserved for end-to-end (E2E) test scripts.
    - `<page>.spec.ts`: E2E tests for a page, named to match its page object, for example `todo.spec.ts`.

- `types`: A directory centralising type definitions and related scripts essential for ensuring type safety throughout the project.
  - `APISchemaTypes.ts`: A central hub for API schema type definitions. This file consolidates and exports type definitions related to different API endpoints, ensuring type safety and consistency across API interactions.
  - `endpoints/`: A directory for type definitions associated with individual API endpoints. Each file within this directory represents a specific endpoint's type schema, detailing the expected structure and data types of requests and responses for that endpoint.
    - `<endpoint>.ts`: Type definitions for an endpoint, for example `pet.ts` and `store.ts`.
  - `global.d.ts`: Contains global type definitions for our custom Playwright matcher.
  - `swagger.d.ts`: Type definitions generated from the swagger documentation.