API reference

This page documents every public symbol exposed by `@krakentech/blueprint‑playwright.

---

createPlaywrightHelpers

Factory that returns test and expect enhanced with custom fixtures.

Import

import { createPlaywrightHelpers } from '@krakentech/blueprint-playwright';

Usage

const { test, expect } = createPlaywrightHelpers({
  nextServerOptions: { /* PlaywrightNextServerOptions */ },
  graphqlEndpoint: process.env.NEXT_PUBLIC_KRAKEN_API_URL,
});

Signature

function createPlaywrightHelpers(
  options: CreatePlaywrightHelpersOptions,
): {
  test: typeof playwright.test;
  expect: typeof playwright.expect;
}

CreatePlaywrightHelpersOptions

Option	Type	Default	Description
nextServerOptions	PlaywrightNextServerOptions	–	Parameters to boot a Next.js server per worker.
graphqlEndpoint	string	–	Real GraphQL endpoint to use as fallback when a middleware call is not mocked.
defaultEdgeConfig	EdgeConfigItems	{}	Initial data for the Edge Config store mock.
defaultFlags	EdgeConfigItems	{}	Initial data for the feature‑flags endpoint mock.
defaultClientHandlers	RequestHandler[]	[]	MSW handlers automatically applied to every client request.
defaultServerHandlers	RequestHandler[]	[]	MSW handlers automatically applied to every server request.

PlaywrightNextServerOptions (recommended options)

Key	Type	Description
dir	string	Path to your Next.js root.
dev	boolean	Run the server in dev mode (next dev) instead of production build. To be used with an env variable like process.env.NODE_ENV === "development".
quiet	boolean	Silence Next.js logs.
experimentalHttpsServer	boolean	Enable the experimental HTTPS server.
conf	NextConfig	(optional) Pass an already‑imported next.config. Needed when used with next.config.ts.

Fixtures

All fixtures are injected automatically in the Playwright context once you use test from the helpers file; no extra imports required. They are grouped by scope (worker vs test).

Worker‑scope

Name	Description
_nextServer	Boots and stops a Next.js server in the same worker.
_edgeProxy	Starts an Express server that exposes a /playwright-edge-server endpoint. It's used by middleware to avoid requests to the real GraphQL endpoint.
_serverWorker	setupServer instance that mocks every Node fetch/XHR.
connectOptions	Patches wsEndpoint so the VSCode Playwright extension can attach even when MSW is intercepting sockets.

All worker fixtures have auto: true, so they start before the first test of the file and stop once the worker ends.

Test‑scope

Name	Description
_environment	Adds x-playwright-edge-port header so your middleware can reach the local proxy.
serverWorker	Same instance as _serverWorker but reset on every test. Use serverWorker.use() to add handlers.
clientWorker	Converts any MSW handler to page.route. Use clientWorker.use() to mock browser calls.
edgeConfig	edgeConfig.use(data) – mocks Edge Config /items and /item/:key.
flags	flags.use(data) – mocks /api/vercel/flags.
waitForGraphQLResponse	Await the next GraphQL response containing a specific operation.
baseURL	String with the local Next.js server URL (e.g. http://127.0.0.1:46001).

Example

test('mock all the things', async ({ page, serverWorker, clientWorker, edgeConfig, flags }) => {
  // Server‑side mock
  serverWorker.use(
    graphql.query('GetSettings', () =>
      HttpResponse.json({ data: { settings: { theme: 'dark' } } }),
    ),
  );

  // Browser mock
  await clientWorker.use(
    http.get('/api/notifications', () =>
      HttpResponse.json({ data: [] }),
    ),
  );

  // Edge Config & feature flags
  edgeConfig.use({ featureX: 'A' });
  flags.use({ newOnboarding: true });

  await page.goto('/');
  ...
});

Utility helpers

playwrightMiddleware

Helper that picks the correct GraphQL endpoint inside Next.js middleware (Edge Runtime).

Import

import { playwrightMiddleware } from '@krakentech/blueprint-playwright/middleware';

Usage

export function middleware(req: NextRequest) {
  const { graphqlEndpoint } = playwrightMiddleware({
    req,
    enabled: !!process.env.NEXT_PUBLIC_PLAYWRIGHT_MODE, // If you plan to use this variable client side, remember to add the NEXT_PUBLIC_ prefix
    defaultGraphqlEndpoint: process.env.NEXT_PUBLIC_KRAKEN_API_URL,
  });

  // your auth / proxy logic here …
}

During tests the helper detects the x-playwright-edge-port header set by _environment and rewrites the endpoint to the local proxy. In production it simply returns the defaultGraphqlEndpoint.

Gotchas & Tips

Multiple Set‑Cookie headers

When mocking a response that sets multiple cookies, use the Headers constructor:

return HttpResponse.json(
  { data: 'ok' },
  {
    headers: new Headers([
      ['Set-Cookie', 'access=token; Path=/; HttpOnly'],
      ['Set-Cookie', 'refresh=token; Path=/; HttpOnly'],
    ]),
  },
);

clientWorker will parse and add all cookies to the Playwright browser context.

Debugging with VSCode

If you use the VSCode Playwright extension, keep connect mode enabled – the connectOptions fixture rewrites the wsEndpoint from localhost to 127.0.0.1 so MSW can forward the connection correctly.