@api-core/test

Type-safe API contract definitions and API testing utilities with seamless Playwright integration.

Installation

npm install @api-core/test

Note: @playwright/test is a peer dependency. Make sure @playwright/test is installed in your project.

Features

• Type-Safe API Contracts: Derive route path parameters, query params, request body, and response shapes automatically from your contracts.
• Browser-Free Execution: Built on Playwright's lightweight APIRequestContext without requiring browser binary installations (npx playwright install is not needed).
• Playwright Test Integration: Uses standard Playwright fixtures (api for test-scoped requests, workerApi for worker-scoped requests).
• Full Extensibility: Returns a standard Playwright TestType compatible with test.extend().

Quick Start

1. Define API Contracts

import { createApi } from '@api-core/test';

export interface User {
  id: number;
  name: string;
}

export interface GetUserQuery {
  includeDetails?: boolean;
}

export const getUser = createApi({
  method: 'GET',
  endpoint: '/users/{id}',
});

2. Create API Registry

import { createApiRegistry } from '@api-core/test';
import { getUser } from './api/users';

export const registry = createApiRegistry({
  users: {
    get: getUser,
  },
});

3. Create Test Fixture

import { createApiTest } from '@api-core/test';
import { registry } from './registry';

export const test = createApiTest({
  registry,
  config: {
    baseURL: process.env.API_BASE_URL || 'https://jsonplaceholder.typicode.com',
  },
});

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

4. Write API Tests

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

test('gets user details', async ({ api }) => {
  const response = await api.call('users.get', {
    path: { id: 1 },
    query: { includeDetails: true },
  });

  expect(response.status).toBe(200);
  expect(response.data.id).toBe(1);
});

Extending Playwright Test

createApiTest returns a standard Playwright TestType object, allowing seamless composition with custom fixtures:

const apiTest = createApiTest({ registry });

export const test = apiTest.extend<{ customFixture: string }>({
  customFixture: async ({}, use) => {
    await use('value');
  },
});

Advanced & Custom Runtimes

For custom transport runtimes, framework integrations, or K6 load testing, use createClient from @api-core/client:

import { createClient } from '@api-core/client';

License

MIT © Shanmuka Chandra Teja Anem