Skip to content

Getting Started ​

Propmaster extends Playwright Test with fixtures for the systems behind your UI: APIs, databases, message brokers, caches, mobile devices and OTP. You keep your Playwright config and tests. Propmaster adds more fixtures to request.

Requirements ​

  • Node.js 22.12 or newer
  • @playwright/test (a peer dependency, so you choose the version)

Install ​

bash
npm install --save-dev @playwright/test @inluxc/propmaster

Propmaster itself has no runtime dependencies. Each fixture's driver is an optional peer dependency, so you install only the ones for the fixtures you use:

FixtureInstall
openApiClientopenapi-client-axios (js-yaml too, for YAML spec files; ajv and ajv-formats for contract checks)
graphqlClientgraphql-request graphql
databaseClientpg (PostgreSQL), mysql2 (MySQL), mssql (MSSQL) or better-sqlite3 (SQLite)
mongoDbClientmongodb
neo4jClientneo4j-driver
kafkaClientkafkajs
redisClientioredis
otpClientotplib
inboxClientnothing (uses fetch); needs a Mailpit server
mockServernothing (uses fetch); needs a WireMock server
testDatanothing (@faker-js/faker optional, for f.faker)
appiumDriverwebdriverio (gadsHub needs nothing extra)
container: true on any backend (Testcontainers)testcontainers
bash
# e.g. a project testing a REST API backed by PostgreSQL and Kafka
npm install --save-dev openapi-client-axios pg kafkajs

A test that requests a fixture whose driver isn't installed fails with a MissingPackageError that names the package and the install command. Importing Propmaster never loads a driver; each one loads the first time a test uses its fixture.

Or scaffold a new project ​

propmaster init creates a project with one folder per test type (tests/api, tests/integration, tests/e2e, tests/mobile), a Playwright config that runs each type as its own project, an environments.json, and tests/support/ for page objects, fixtures, test data and helpers:

bash
npx propmaster init my-tests

Run it in a project that already has Playwright tests and it adds only what's missing. It moves nothing and reports where your tests belong; npx propmaster organize then moves them. See Project Layout.

Your first test ​

Import test and expect from Propmaster instead of @playwright/test. Then request fixtures by name:

typescript
// tests/users.spec.ts
import { test, expect } from '@inluxc/propmaster';

test('a new user is stored as active', async ({ openApiClient, databaseClient }) => {
    const { client } = openApiClient;

    await test.step('Create the user through the API', async () => {
        const res = await (client as any).createUser(null, { name: 'Alice', email: '[email protected]' });
        expect(res.status).toBe(201);
    });

    await test.step('Check the row in the database', async () => {
        const rows = await databaseClient.query<{ active: boolean }>(
            'SELECT active FROM users WHERE email = $1', ['[email protected]'],
        );
        expect(rows[0].active).toBe(true);
    });
});

Point the fixtures at your services with environment variables:

bash
PW_OPENAPI_SPEC_PATH=./openapi.yaml \
PW_OPENAPI_BASE_URL=http://localhost:3000 \
PW_DB_TYPE=postgresql PW_DB_HOST=localhost PW_DB_NAME=app \
PW_DB_USERNAME=app PW_DB_PASSWORD=app \
npx playwright test

For more than a couple of variables, keep them in environments.json or .env files instead.

Playwright fixtures still work ​

Propmaster's test is built on @playwright/test, so page, request, context and browser are all available, alongside Propmaster fixtures in the same test:

typescript
import { test, expect } from '@inluxc/propmaster';

test('a user created through the API appears in the admin UI', async ({ openApiClient, page }) => {
    const { client } = openApiClient;
    await (client as any).createUser(null, { name: 'Alice', email: '[email protected]' });

    await page.goto('/admin/users');
    await expect(page.getByText('[email protected]')).toBeVisible();
});

Available fixtures ​

FixtureWhat it gives youGuide
openApiClientTyped HTTP client generated from an OpenAPI specOpenAPI
graphqlClientGraphQL queries, mutations and raw responsesGraphQL
databaseClientPostgreSQL, MySQL, MSSQL or SQLite queriesDatabase
mongoDbClientMongoDB CRUD and aggregationMongoDB
neo4jClientNeo4j Cypher reads, writes and transactionsNeo4j
kafkaClientKafka produce and consumeKafka
redisClientRedis keys and pub/subRedis
otpClientTOTP/HOTP codes for 2FA flowsOTP
inboxClientEmailed codes, verification and reset links (Mailpit)Inbox
mockServerStubbed third-party APIs your backend calls (WireMock)Mock server
testDataFactories and unique values; inserts through the clients are removed after each testTest data
authToken / authRequestOAuth/OIDC tokens per role; authRole also starts browser tests logged inAuth
appiumDriverAppium session (WebdriverIO) on local Appium, a grid, a cloud farm or GADSAppium
gadsHubGADS hub status and device listingAppium → GADS

Need something else? Write your own fixture on top of Propmaster's test.

Next steps ​

Released under the MIT License.