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
npm install --save-dev @playwright/test @inluxc/propmasterPropmaster 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:
| Fixture | Install |
|---|---|
openApiClient | openapi-client-axios (js-yaml too, for YAML spec files; ajv and ajv-formats for contract checks) |
graphqlClient | graphql-request graphql |
databaseClient | pg (PostgreSQL), mysql2 (MySQL), mssql (MSSQL) or better-sqlite3 (SQLite) |
mongoDbClient | mongodb |
neo4jClient | neo4j-driver |
kafkaClient | kafkajs |
redisClient | ioredis |
otpClient | otplib |
inboxClient | nothing (uses fetch); needs a Mailpit server |
mockServer | nothing (uses fetch); needs a WireMock server |
testData | nothing (@faker-js/faker optional, for f.faker) |
appiumDriver | webdriverio (gadsHub needs nothing extra) |
container: true on any backend (Testcontainers) | testcontainers |
# e.g. a project testing a REST API backed by PostgreSQL and Kafka
npm install --save-dev openapi-client-axios pg kafkajsA 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:
npx propmaster init my-testsRun 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:
// 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:
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 testFor 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:
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
| Fixture | What it gives you | Guide |
|---|---|---|
openApiClient | Typed HTTP client generated from an OpenAPI spec | OpenAPI |
graphqlClient | GraphQL queries, mutations and raw responses | GraphQL |
databaseClient | PostgreSQL, MySQL, MSSQL or SQLite queries | Database |
mongoDbClient | MongoDB CRUD and aggregation | MongoDB |
neo4jClient | Neo4j Cypher reads, writes and transactions | Neo4j |
kafkaClient | Kafka produce and consume | Kafka |
redisClient | Redis keys and pub/sub | Redis |
otpClient | TOTP/HOTP codes for 2FA flows | OTP |
inboxClient | Emailed codes, verification and reset links (Mailpit) | Inbox |
mockServer | Stubbed third-party APIs your backend calls (WireMock) | Mock server |
testData | Factories and unique values; inserts through the clients are removed after each test | Test data |
authToken / authRequest | OAuth/OIDC tokens per role; authRole also starts browser tests logged in | Auth |
appiumDriver | Appium session (WebdriverIO) on local Appium, a grid, a cloud farm or GADS | Appium |
gadsHub | GADS hub status and device listing | Appium → GADS |
Need something else? Write your own fixture on top of Propmaster's test.
Next steps
- Project Layout: folders by test type, one config, and sorting existing tests
- Configuration: environments,
.envfiles and per-project settings - Writing Tests: test IDs, steps and the convention checker
- Running in CI: GitHub Actions jobs with real services