Skip to main content

Fixtures Reference

Complete reference for the createBddTest function and fixture system.

Overview​

createBddTest is the main factory function that creates a configured BDD test instance with dependency-injected adapters.

createBddTest​

Import​

import { createBddTest, type CreateBddTestOptions } from '@esimplicity/stack-tests';

Signature​

function createBddTest(options?: CreateBddTestOptions): BddTest

Options​

type CreateBddTestOptions = {
  createApi?: (ctx: CreateContext) => ApiPort;
  createUi?: (ctx: CreateContext) => UiPort;
  createAuth?: (ctx: CreateContext & { api: ApiPort; ui: UiPort }) => AuthPort;
  createCleanup?: (ctx: CreateContext) => CleanupPort;
  getCleanupAuth?: CleanupAuthProvider;
  createTui?: () => TuiPort | undefined;
  worldFactory?: () => World;
};

type CleanupAuthProvider = (request: APIRequestContext) => Promise<Record<string, string>>;

type CreateContext = PlaywrightTestArgs & PlaywrightWorkerArgs & {
  apiRequest: APIRequestContext;
  page: Page;
};

Default Behavior​

When options are not provided, defaults are used:

OptionDefault
createApiPlaywrightApiAdapter
createUiPlaywrightUiAdapter
createAuthUniversalAuthAdapter
createCleanupDefaultCleanupAdapter
getCleanupAuthForm-based login using DEFAULT_ADMIN_* env vars
createTuiundefined (disabled)
worldFactoryinitWorld()

Usage Examples​

Minimal (All Defaults)​

import { createBddTest } from '@esimplicity/stack-tests';

export const test = createBddTest();

Custom API Adapter​

import { createBddTest, PlaywrightApiAdapter } from '@esimplicity/stack-tests';

export const test = createBddTest({
  createApi: ({ apiRequest }) => {
    // Add custom logic, logging, etc.
    return new PlaywrightApiAdapter(apiRequest);
  },
});

With TUI Support​

import { createBddTest, TuiTesterAdapter } from '@esimplicity/stack-tests';

export const test = createBddTest({
  createTui: () => new TuiTesterAdapter({
    command: ['node', 'dist/cli.js'],
    size: { cols: 100, rows: 30 },
  }),
});

Custom Cleanup Rules​

import { createBddTest, DefaultCleanupAdapter } from '@esimplicity/stack-tests';

export const test = createBddTest({
  createCleanup: () => new DefaultCleanupAdapter({
    rules: [
      { varMatch: 'customer', path: '/api/customers/{id}' },
      { varMatch: 'order', path: '/api/orders/{id}' },
    ],
  }),
});

Custom Cleanup Authentication​

import { createBddTest, createOidcCleanupAuth } from '@esimplicity/stack-tests';

// Use OIDC provider (Keycloak, Auth0, Okta, etc.)
export const test = createBddTest({
  getCleanupAuth: createOidcCleanupAuth({
    grantType: 'password',
    extraHeaders: { 'x-user-roles': 'admin' },
  }),
});

// Or provide a fully custom auth provider
export const test2 = createBddTest({
  getCleanupAuth: async (request) => {
    return { Authorization: 'Bearer my-static-token' };
  },
});

Extended World​

import { createBddTest, initWorld, type World } from '@esimplicity/stack-tests';

interface MyWorld extends World {
  currentUser?: { id: string; email: string };
}

function initMyWorld(): MyWorld {
  return {
    ...initWorld(),
    currentUser: undefined,
  };
}

export const test = createBddTest({
  worldFactory: initMyWorld,
});

Available Fixtures​

world​

The test state container.

test('example', async ({ world }) => {
  world.vars['key'] = 'value';
  world.headers['Authorization'] = 'Bearer token';
});

api​

The API adapter for HTTP operations.

test('example', async ({ api, world }) => {
  const result = await api.sendJson('GET', '/users', undefined, world.headers);
});

ui​

The UI adapter for browser operations.

test('example', async ({ ui }) => {
  await ui.goto('/login');
  await ui.fillLabel('Email', 'user@example.com');
});

auth​

The authentication adapter.

test('example', async ({ auth, world }) => {
  await auth.apiLoginAsAdmin(world);
});

cleanup​

The cleanup adapter.

test('example', async ({ cleanup, world }) => {
  cleanup.registerFromVar(world, 'userId', '123');
});

tui​

The TUI adapter (if configured).

test('example', async ({ tui }) => {
  if (tui) {
    await tui.start();
    await tui.typeText('hello');
  }
});

apiRequest​

The raw Playwright API request context.

test('example', async ({ apiRequest }) => {
  const response = await apiRequest.get('/health');
});

Fixture Lifecycle​

Initialization Order​

  1. apiRequest - Playwright request context
  2. api - API adapter
  3. cleanup - Cleanup adapter
  4. ui - UI adapter (requires page)
  5. auth - Auth adapter (requires api and ui)
  6. world - World state
  7. tui - TUI adapter (independent)

Cleanup Order​

After test completion:

  1. World cleanup items executed (reverse order)
  2. TUI stopped (if running)
  3. Resources disposed

baseTest​

Re-exported base test from playwright-bdd for advanced use cases.

import { baseTest } from '@esimplicity/stack-tests';

// Extend with custom fixtures
const customTest = baseTest.extend({
  myFixture: async ({}, use) => {
    await use('value');
  },
});

Type Exports​

import type {
  CreateBddTestOptions,
  CleanupAuthProvider,
  TuiFactory,
  TuiConfig,
} from '@esimplicity/stack-tests';

TuiFactory​

type TuiFactory = () => TuiPort | undefined;

TuiConfig​

type TuiConfig = {
  command: string[];
  size?: { cols: number; rows: number };
  cwd?: string;
  env?: Record<string, string>;
  debug?: boolean;
  snapshotDir?: string;
  shell?: string;
};

Integration with playwright-bdd​

Step Registration​

import { createBdd } from 'playwright-bdd';
import { test } from './fixtures';

const { Given, When, Then } = createBdd(test);

Given('a precondition', async ({ world }) => {
  // Access fixtures
});

Project Configuration​

import { defineBddProject } from 'playwright-bdd';

const project = defineBddProject({
  name: 'api',
  features: 'features/api/**/*.feature',
  steps: 'features/steps/**/*.ts',
  tags: '@api',
});