Playwright addon

Realistic fixtures for Playwright

Pull realistic synthetic data straight into your tests — random by default, typed end to end. Three ways in: a zero-config singleton, a builder for full control, or a Playwright fixture.

Install

Add the package as a dev dependency alongside @playwright/test. Requires Node 18+ for global fetch.

terminal

pnpm add -D @przeslijmi/real-fake-data-playwright

Quick start

Three ways to pull data in — pick whichever fits, they all return the same typed records. The fixture is not required.

1. Singleton — import and go

Zero config. The fakeData singleton is pre-wired to the public hosted API and returns fresh random data on every run. Best when you just want data in one (or many) tests without touching your Playwright config.

example.spec.ts

import { test, expect } from '@playwright/test';
import { fakeData } from '@przeslijmi/real-fake-data-playwright';

test('registers a new customer', async ({ page }) => {
  const person = await fakeData.plPerson({ sex: 'f' });

  await page.goto('/signup');
  await page.getByLabel('First name').fill(person.name);
  await page.getByLabel('Surname').fill(person.surname);
  await page.getByLabel('PESEL').fill(person.pesel);
  await page.getByRole('button', { name: 'Create account' }).click();

  await expect(page.getByText(person.surname)).toBeVisible();
});

2. createFakeData — full control

Build your own instance over any base URL, with auth headers and an optional seed. Best when you self-host the API, need authentication, or want to pin a fixed dataset.

example.spec.ts

import { test } from '@playwright/test';
import { createFakeData, CloudFakeDataProvider } from '@przeslijmi/real-fake-data-playwright';

const fakeData = createFakeData(
  new CloudFakeDataProvider({
    baseUrl: 'https://api.real-fake-data.com',
    headers: { 'x-api-key': process.env.RFD_API_KEY ?? '' },
  }),
  { seed: 42 }, // optional — omit for random
);

test('uses pinned data', async ({ page }) => {
  const person = await fakeData.plPerson({ sex: 'f' });
  // …
});

3. Fixture — Playwright-native

Configure once with test.use and the fakeData fixture is injected into every test in scope. test and expect are the standard Playwright exports extended with the fixture — use them exactly as you would @playwright/test.

example.spec.ts

import { test, expect } from '@przeslijmi/real-fake-data-playwright';

test.use({ realFakeData: { baseUrl: 'https://api.real-fake-data.com' } });

test('registers a new customer', async ({ page, fakeData }) => {
  const person = await fakeData.plPerson({ sex: 'f' });
  // …
  await expect(page.getByText(person.surname)).toBeVisible();
});

Random by default, reproducible on demand

It is a random-data generator: with no seed set, every call draws fresh data on each run. When a test fails on a particular record, pin a seed to replay the exact same dataset. With a base seed in play, the Nth call uses seed + N — so three back-to-back plPerson() calls still return three different people, yet the whole sequence reproduces identically next run.

playwright.config.ts

test.use({ realFakeData: { baseUrl, seed: 42 } }); // pin this file to a fixed dataset

Generators

Each generator exposes a singular method returning one record and a plural taking count as its first argument and returning an array. Method names are locale-prefixed (plPesel, plCompany, …); locale-agnostic generators (email, lorem) carry no prefix. Every method accepts optional constraints.

Singular	Plural	Returns	Common options
plPesel	plPesels	{ value, birthDate, sex }	sex, atAge, olderThan, …, invalid
plPerson	plPeople	{ name, surname, initials, birthDate, pesel }	same as plPesel
plAddress	plAddresses	{ buildingNumber, postalCode, cityName, … }	teryt
plNip	plNips	{ value, digits }	format, invalid
plIban	plIbans	{ value, electronicFormat, bankCode, bankName }	format, bankCode, bankName, invalid
plRegon	plRegons	{ value, variant }	variant, invalid
plCompany	plCompanies	{ name, legalForm, nip, regon }	strategy, legalForm, …, invalid
plVehicleRegistration	plVehicleRegistrations	{ value, prefix, individualPart, type, … }	type, voivodeship, …
email	emails	{ value, localPart, domain, pattern, plusTag }	domain, pattern, …
lorem	lorems	{ value, words, chars, bytes, paragraphs }	bytes, chars, words, paragraphs

Testing your validators

Every checksum generator accepts invalid: true to produce a value with a deliberately wrong check digit — the rest stays well-formed — so you can assert that your own validators reject bad input.

validator.spec.ts

const bad = await fakeData.plNip({ invalid: true });
await expect(submitNip(bad.value)).rejects.toThrow('invalid checksum');

Error handling

A non-2xx API response throws a RealFakeDataError carrying status (HTTP code), code (the API’s machine error code), and details (per-field validation messages).

error-handling.ts

import { RealFakeDataError } from '@przeslijmi/real-fake-data-playwright';

try {
  await fakeData.plAddress({ teryt: 'not-digits' });
} catch (error) {
  if (error instanceof RealFakeDataError) {
    console.log(error.status, error.code, error.details);
  }
}

Ready to drop it into your suite?

Grab an API key, point the fixture at it, and start pulling realistic data into your tests today.

Get API key View pricing View on GitHub