api-project-structure

API Project Structure

Standard Directory Layout

The default structure places all API test artefacts under tests/api/ at the repository root:

tests/
  api/
    specs/               ← API test spec files (*.api.spec.ts)
    fixtures/
      api-client.ts      ← extended test + APIRequestContext fixture export
    schemas/             ← JSON Schema files for response validation (*.schema.json)
    helpers/             ← shared utilities (mock factories, request builders, etc.)
playwright.config.ts     ← Playwright configuration at repo root (api project block added here)

Create .gitignore entries for generated test output:

test-results/
playwright-report/
.env.test

File Naming Conventions

Artefact	Pattern	Example
Spec file	<resource>.api.spec.ts	users.api.spec.ts, orders.api.spec.ts
Fixture barrel	api-client.ts	fixtures/api-client.ts
JSON Schema	<resource>.schema.json	schemas/user.schema.json
Mock factory	<resource>.factory.ts	helpers/user.factory.ts
Request builder	<resource>.builder.ts	helpers/order.builder.ts

All file names use kebab-case. No index.ts barrel exports — import directly from the source file.

Directory Tree (Populated Example)

tests/
  api/
    specs/
      users.api.spec.ts
      orders.api.spec.ts
      products.api.spec.ts
      graphql/
        users-graphql.api.spec.ts
    fixtures/
      api-client.ts
    schemas/
      user.schema.json
      order.schema.json
      product.schema.json
    helpers/
      user.factory.ts
      order.factory.ts
      request-builders.ts
playwright.config.ts

playwright.config.ts — API Project Block

Add the api project to the existing playwright.config.ts. If no config exists, generate it from scratch:

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 1 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: process.env.CI
    ? [['json', { outputFile: 'test-results/results.json' }], ['list']]
    : [['html'], ['list']],

  projects: [
    // --- API project (no browser) ---
    {
      name: 'api',
      testDir: './tests/api/specs',
      testMatch: '**/*.api.spec.ts',
      use: {
        baseURL: process.env.API_BASE_URL ?? 'http://localhost:3000/api',
      },
      timeout: 10_000,
      fullyParallel: true,
    },

    // --- E2E browser projects (if co-located) ---
    {
      name: 'chromium',
      testDir: './tests/e2e/specs',
      testMatch: '**/*.spec.ts',
      use: {
        ...devices['Desktop Chrome'],
        baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
        storageState: 'tests/e2e/.auth/user.json',
        trace: 'on-first-retry',
      },
      dependencies: ['setup'],
    },
  ],
});

Fixture Barrel Scaffold

Generate tests/api/fixtures/api-client.ts as the entry point for all spec imports:

import { test as base, expect, type APIRequestContext } from '@playwright/test';

type ApiFixtures = {
  apiClient: APIRequestContext;
};

export const test = base.extend<ApiFixtures>({
  apiClient: async ({ playwright }, use) => {
    const context = await playwright.request.newContext({
      baseURL: process.env.API_BASE_URL ?? 'http://localhost:3000/api',
      extraHTTPHeaders: {
        Authorization: `Bearer ${process.env.API_AUTH_TOKEN ?? ''}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
    });
    await use(context);
    await context.dispose();
  },
});

export { expect };

Monorepo Adaptation

In a monorepo, use the directoryMapping key in .playwright-agent.json to map app packages to their API test directories:

{
  "directoryMapping": {
    "apps/api-gateway": "apps/api-gateway/tests/api",
    "apps/user-service": "apps/user-service/tests/api"
  }
}

Each mapped service gets its own tests/api/ subtree. Shared schemas and factory helpers can live in a packages/api-test-utils/ workspace package:

apps/
  api-gateway/
    tests/api/
      specs/
      fixtures/
  user-service/
    tests/api/
      specs/
      fixtures/
packages/
  api-test-utils/        ← shared schemas, factories, builders
    src/
      schemas/
      helpers/

Checklist

When scaffolding a new API test module, verify:

• tests/api/ directory created (or monorepo equivalent)
• tests/api/fixtures/api-client.ts created with extended test and expect
• tests/api/schemas/ directory created for JSON Schema files
• tests/api/helpers/ directory created for factory and builder helpers
• playwright.config.ts updated with api project block
• API_BASE_URL and API_AUTH_TOKEN env vars documented in .env.test.example
• test-results/ and .env.test added to .gitignore
• At least one *.api.spec.ts file generated to validate the setup