API Automation Framework Design with Playwright and TypeScript

Fifty API tests in one file work fine. Fifteen hundred tests, five environments, eight roles and six people committing every day don’t, unless the framework underneath is designed for it. “Explain your framework” is also the question every automation interview spends the most time on. In this lesson we assemble everything from Module 6 into a clean, layered Playwright TypeScript API framework, explain each design decision, and finish with the conventions that keep it maintainable for years.

The Folder Structure

This is the structure of the framework built in this module. Every file shown in lessons 31 to 35 lives here, and the whole suite passes against the practice API:

sqa-api-tests/
├── playwright.config.ts        # projects, baseURL, reporters, retries
├── tsconfig.json
├── package.json
├── .env.example                # documented variables, no secrets
├── .gitignore                  # .env, .auth/, test-results/, playwright-report/
├── src/
│   ├── config.ts               # credentials + paths from environment variables
│   ├── fixtures.ts             # test.extend: clients, role contexts, cleanup
│   ├── schemas.ts              # Zod schemas + Ajv helper
│   ├── builders.ts             # test data builders
│   └── api/                    # service objects (one per resource)
│       ├── UsersApi.ts
│       ├── ObjectsApi.ts
│       └── AuthApi.ts
├── data/                       # data-driven inputs
│   ├── age-boundaries.json
│   └── object-ttl.csv
└── tests/
    ├── auth.setup.ts           # logs in once per run (setup project)
    ├── request-basics.spec.ts
    ├── crud.spec.ts
    ├── assertions.spec.ts
    ├── auth.spec.ts
    ├── data-driven.spec.ts
    └── builders.spec.ts

The Layers and Why They Exist

Layer 1: Configuration and Environments

The full playwright.config.ts:

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

try { process.loadEnvFile(); } catch { /* no .env file: rely on real environment variables (CI) */ }

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 1 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: [
    ['list'],
    ['html', { open: 'never' }],
    ['junit', { outputFile: 'results/junit.xml' }],
  ],
  use: {
    // Trailing slash matters: request paths are resolved relative to this URL.
    baseURL: process.env.API_BASE_URL ?? 'https://sqatools.in/wp-json/sqa-api/v1/',
    extraHTTPHeaders: { Accept: 'application/json' },
  },
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    { name: 'api', testIgnore: /.*\.setup\.ts/, dependencies: ['setup'] },
  ],
});

• process.loadEnvFile() (built into Node.js 20.12+) reads a local .env file, so no extra dependency is needed. In CI the variables come from the pipeline’s secret store.
• forbidOnly fails CI if someone commits test.only.
• retries: 1 in CI absorbs rare network blips; a test that needs retries regularly is a bug to fix, not to hide.

Commit a .env.example that documents every variable without real values:

# .env.example - copy to .env and fill in
API_BASE_URL=https://sqatools.in/wp-json/sqa-api/v1/
ADMIN_USER=admin
ADMIN_PASS=
VIEWER_USER=viewer
VIEWER_PASS=

Layer 2: Service Objects

One class per resource; methods return raw APIResponses; a few ...OrThrow helpers for setup. You built ObjectsApi in the CRUD lesson, UsersApi in the data-driven lesson and AuthApi in the auth lesson. Guidelines:

• No assertions inside service objects (except guards in ...OrThrow helpers).
• Accept typed inputs (NewObject, UserQuery) so TypeScript catches mistakes.
• Take the APIRequestContext in the constructor, so the same class works for anonymous, admin and viewer contexts.
• Keep them thin. Business flows that span services (place an order = cart + payment) go in a separate “flows” or “steps” layer if you need them.

Layer 3: Models and Schemas

src/schemas.ts (from the assertions lesson) holds Zod schemas that double as TypeScript types, and an Ajv helper for official JSON Schemas. Rule of thumb: every response type the suite touches has a schema, and every positive test validates against it.

Layer 4: Fixtures

src/fixtures.ts is the heart of the framework: usersApi, objectsApi, authApi, role contexts adminApi/viewerApi and cleanup. Tests import test and expect from here, never directly from @playwright/test, so new shared capabilities (a custom matcher, a logger) reach every test through one file.

Layer 5: Test Data Builders

A builder returns a valid object with sensible defaults; tests override only the field they’re testing. This keeps tests short and makes the intent obvious. src/builders.ts:

import { NewObject } from './api/ObjectsApi';

let counter = 0;

/** Test data builder: valid defaults, override only what a test cares about. */
export function anObject(overrides: Partial<NewObject> = {}): NewObject {
  counter += 1;
  return {
    name: `auto-${process.pid}-${Date.now()}-${counter}`,
    data: { source: 'playwright' },
    ttl: 60,
    ...overrides,
  };
}

export function aUserPayload(overrides: Record<string, unknown> = {}) {
  return { name: 'Asha Verma', email: 'asha@example.com', age: 30, ...overrides };
}

import { test, expect } from '../src/fixtures';
import { anObject, aUserPayload } from '../src/builders';

test('builder: only the field under test is specified', async ({ objectsApi, cleanup }) => {
  const res = await objectsApi.create(anObject({ ttl: 1800 }));
  expect(res.status()).toBe(201);
  const obj = await res.json();
  cleanup(() => objectsApi.delete(obj.id));
  expect(obj.ttl_seconds).toBe(1800);
});

test('builder: one invalid field, everything else valid', async ({ request }) => {
  const res = await request.post('validate/user', { data: aUserPayload({ age: 101 }) });
  expect(res.status()).toBe(422);
  expect((await res.json()).error.details).toEqual([expect.objectContaining({ field: 'age' })]);
});

The second test proves a subtle point: because every other field is valid, the API reports exactly one error, for age. Negative tests built from a valid baseline isolate the rule under test.

Layer 6: Tests and Conventions

• Files by feature (orders.spec.ts, refunds.spec.ts), not by test type.
• Titles that state behaviour: "PATCH merges and null removes a key".
• Tags for selection: test('...', { tag: '@smoke' }, ...), run with --grep @smoke.
• Arrange-Act-Assert shape; one behaviour per test.
• No sleeps; use expect.poll.
• Independent: own data, cleanup, parallel-safe.

Debuggability: Make Failures Explain Themselves

• Use await expect(res).toBeOK() and custom messages, so reports show status and body.
• Attach request/response details on failure with testInfo.attach() (see the bug reporting lesson).
• Name generated data so it’s traceable (auto-<pid>-<timestamp>) and searchable in server logs.
• Send a correlation header (e.g. X-Request-Id with the test title) via extraHTTPHeaders if the backend logs it.

Scaling the Framework

Code Quality for Test Code

• TypeScript strict mode and tsc --noEmit in CI (Playwright runs tests without type-checking, so run tsc separately).
• ESLint with eslint-plugin-playwright (catches missing awaits, focused tests).
• Pull-request reviews for tests, like production code.
• Delete or fix flaky tests quickly; quarantine with test.fixme() and a ticket.

Interview Questions: API Framework Design