BGSTM Playwright Frameworks

🚧 Early development. APIs and package names will change. Built in the open — feedback and PRs welcome.

A monorepo of opinionated, domain-specific Playwright automation frameworks with native traceability into BGSTM.

Most Playwright starters are generic. These aren't. Each domain pack ships with:

• Pre-built page objects for the common entities of that domain (e.g. CRM: Lead, Opportunity, Account)
• Realistic test data factories
• Multi-step workflow helpers
• BGSTM-native reporting — every test result, step, and artifact is traceable back to a BGSTM requirement and test case

Packages

Package	Description	Status
@bgstm/playwright-core	Shared fixtures, base POM, BGSTM reporter	🚧 Stub
@bgstm/domain-crm	CRM domain pack (Leads, Opportunities, Accounts)	🚧 Stub
@bgstm/domain-accounting	Accounting domain pack (Ledgers, Journals, Reconciliations)	🚧 Stub
@bgstm/domain-saas-workflows	AI workforce / SaaS workflows pack (AI receptionist, scheduling, CRM-from-call)	🚧 Stub

💼 Looking for regulated-industry packs (Healthcare/HIPAA, Financial/SOX, GxP)? Those are available as part of NAT — the managed test execution platform built around BGSTM.

Quick start

# Scaffold a new project (coming soon)
npm create bgstm-playwright@latest my-tests -- --domain=crm

# Or install packages directly
pnpm add -D @bgstm/playwright-core @bgstm/domain-crm

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { bgstmReporter } from '@bgstm/playwright-core/reporter';

export default defineConfig({
  reporter: [bgstmReporter({ baseUrl: process.env.BGSTM_URL, token: process.env.BGSTM_TOKEN })],
  // ...
});

// tests/lead.spec.ts
import { test, expect } from '@bgstm/domain-crm';

test('create a lead and convert to opportunity', async ({ leadsPage, opportunitiesPage }) => {
  const lead = await leadsPage.create({ name: 'Acme Corp', value: 50000 });
  await leadsPage.convert(lead.id);
  await expect(opportunitiesPage.byLeadId(lead.id)).toBeVisible();
});

Linking tests to requirements

The BGSTM reporter reads Playwright bgstm:requirement annotations from each completed test and forwards them to BGSTM as requirement external IDs.

import { test } from '@playwright/test';

test(
  'login redirects to dashboard',
  { annotation: { type: 'bgstm:requirement', description: 'REQ-LOGIN-001' } },
  async ({ page }) => {
    await page.goto('/login');
  },
);

You can also add them dynamically with test.info().annotations.push({ type: 'bgstm:requirement', description: 'REQ-LOGIN-001' }). Multiple requirement annotations per test are supported. BGSTM resolves them against requirements.external_id; unknown IDs are dropped silently and recorded in the audit log, so create the requirement in BGSTM first for guaranteed linking. auto_register_requirements is server-side opt-in only; this reporter does not send it.

How it relates to BGSTM and NAT (http://NAT-Testing.io)

BGSTM            ← methodology + traceability platform (open-source)
   ▲
   │ reports to via the BGSTM Reporter API
   │
This repo        ← Playwright execution scaffolding (open-source, Apache-2.0)
   ▲
   │ runs at scale on
   │
NAT              ← managed execution + AI-adaptive testing (commercial)

Read more: BGSTM integration design

Example: crm-example

The examples/crm-example directory is a minimal Playwright project that exercises the full reporter pipeline against a live BGSTM instance.

It contains exactly three tests (1 pass / 1 fail / 1 skip) — the failing test is intentional and is the artifact-upload smoke proof for the BGSTM step-2 CI job.

Required environment variables

Variable	Description
BGSTM_API_URL	Base URL of the BGSTM instance (e.g. https://bgstm.example.com)
BGSTM_API_TOKEN	Runner token (format: bgstm_runner_…)
BGSTM_PROJECT_ID	BGSTM project UUID to report results into
GITHUB_SHA	Commit SHA under test (set automatically in GitHub Actions)
GITHUB_REF_NAME	Branch name (set automatically in GitHub Actions)

When BGSTM_API_URL is unset the reporter is skipped and only the list reporter runs.

cd examples/crm-example
BGSTM_API_URL=https://bgstm.example.com \
BGSTM_API_TOKEN=bgstm_runner_… \
BGSTM_PROJECT_ID=<uuid> \
pnpm smoke

Development

pnpm install
pnpm build
pnpm test
pnpm -r --filter @bgstm/domain-crm test:e2e

Requires Node ≥ 20 and pnpm ≥ 9.

Contributing

We welcome PRs! See CONTRIBUTING.md. For new domain pack proposals, please open a Domain Pack Proposal issue first.

License

Apache-2.0 — see LICENSE.

Related

• BGSTM — methodology + traceability platform
• NAT — managed execution platform powered by BGSTM
• BGSTM Reporter API contract (#291) — the integration spec this repo implements