api-fixture-generation

API Fixture Generation

Purpose

This skill generates the tests/api/fixtures/api-client.ts barrel that all API spec files import. The fixture extends Playwright's base test with a typed apiClient fixture that provides an authenticated APIRequestContext, manages tokens, and cleans up created resources in teardown.

Output

Produces tests/api/fixtures/api-client.ts (path controlled by apiTestDir in .playwright-agent.json). The file exports an extended test object and expect.

Core Fixture: test.extend

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

type ApiFixtures = {
  apiClient: APIRequestContext;
};

export const test = base.extend<ApiFixtures>({
  apiClient: async ({ playwright }, use) => {
    // Create a new APIRequestContext with base URL and auth headers
    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',
      },
    });

    // Provide context to the test
    await use(context);

    // Teardown — dispose the context and flush any pending requests
    await context.dispose();
  },
});

export { expect };

Token Management

When the API uses a short-lived token that must be fetched before each test session, generate a token-fetching helper and call it during fixture setup:

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

async function fetchAuthToken(): Promise<string> {
  const res = await fetch(`${process.env.API_BASE_URL}/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: process.env.API_CLIENT_ID,
      clientSecret: process.env.API_CLIENT_SECRET,
    }),
  });
  if (!res.ok) {
    throw new Error(`Failed to fetch auth token: ${res.status}`);
  }
  const { access_token } = await res.json();
  return access_token;
}

type ApiFixtures = {
  apiClient: APIRequestContext;
};

export const test = base.extend<ApiFixtures>({
  apiClient: async ({ playwright }, use) => {
    const token = await fetchAuthToken();

    const context = await playwright.request.newContext({
      baseURL: process.env.API_BASE_URL ?? 'http://localhost:3000/api',
      extraHTTPHeaders: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
    });

    await use(context);
    await context.dispose();
  },
});

export { expect };

Resource Cleanup in Teardown

When tests create resources that must be removed after the test, collect their IDs and delete them in teardown:

type ApiFixtures = {
  apiClient: APIRequestContext;
  createdUserIds: string[];
};

export const test = base.extend<ApiFixtures>({
  // Shared array to accumulate IDs during a test
  createdUserIds: [[], { scope: 'test' }],

  apiClient: async ({ playwright, createdUserIds }, 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);

    // Cleanup — delete all resources created during this test
    for (const id of createdUserIds) {
      await context.delete(`/users/${id}`).catch(() => {
        // Ignore 404s — resource may have been deleted by the test itself
      });
    }

    await context.dispose();
  },
});

export { expect };

Usage in a spec:

import { test, expect } from '../fixtures/api-client';

test('should create and clean up a user', async ({ apiClient, createdUserIds }) => {
  const res = await apiClient.post('/users', {
    data: { name: 'Temp User', email: '[email protected]' },
  });
  expect(res.status()).toBe(201);
  const { id } = await res.json();

  // Register for teardown cleanup
  createdUserIds.push(id);

  // ... rest of the test
});

Multiple Auth Roles

When tests require different permission levels, generate a fixture per role:

type ApiFixtures = {
  apiClient: APIRequestContext;        // authenticated as standard user
  adminApiClient: APIRequestContext;   // authenticated as admin
};

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_USER_TOKEN ?? ''}`,
        'Content-Type': 'application/json',
      },
    });
    await use(context);
    await context.dispose();
  },

  adminApiClient: 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_ADMIN_TOKEN ?? ''}`,
        'Content-Type': 'application/json',
      },
    });
    await use(context);
    await context.dispose();
  },
});

export { expect };

Environment Variables

Always read sensitive values from environment variables. Never hardcode credentials or base URLs:

Variable	Purpose
API_BASE_URL	Base URL for all API requests
API_AUTH_TOKEN	Static bearer token for non-rotating auth
API_CLIENT_ID	OAuth client ID for token exchange
API_CLIENT_SECRET	OAuth client secret for token exchange
API_USER_TOKEN	Token for standard-user role fixture
API_ADMIN_TOKEN	Token for admin-role fixture

Store defaults for local development in a .env.test file that is git-ignored.