@thiaq/playwright-runner

Deterministic Playwright execution and report ingestion for ThiaQ-compatible flow harnesses.

import {
  buildFlowSubmissionEnvelope,
  createFlowRunner,
  ingestRunReportFromEnv,
} from "@thiaq/playwright-runner";

Install it with the flow DSL and Playwright test runner:

bun add --dev @playwright/test @thiaq/flow-core @thiaq/playwright-runner

Build one combined v2 submission from the same executable catalog and reports used by the runner. This preserves definition-step ids, journey-step ids, draft obligation bindings, commit provenance, and honest per-journey evidence:

const envelope = buildFlowSubmissionEnvelope({
  machineId,
  contractVersionId: "coverage-version-uuid",
  sourceSpec: "tests/thiaq/coverage-wave.spec.ts",
  flows,
  journeys,
  reports,
  provenance: {
    repo: "customer-repo",
    gitRef: "main",
    gitSha: commitSha,
  },
});

Submit that object through ThiaQ MCP submit_flow_envelope, then approve its returned submissionId with approve_flow_submission. The helper never marks partial or mismatched-commit evidence as passed.

For a pilot or exploratory catalog that must not bind live coverage, set mode: "exploratory". The helper emits submission_mode: "exploratory" and omits all flow and journey obligation bindings. Coverage mode remains the default and still requires each journey to nominate its contract and obligations.

Use contractVersionId for a successor draft. contractVersion remains available when the contract's human-readable version number is the only stable identifier. Agents can call list_coverage_obligations to enumerate the exact ids and keys in that draft, and get_flow_submission_schema to retrieve the authoritative v2 JSON Schema before submission. These operations are available with @thiaq/playwright-runner 0.1.5 or newer.

ingestRunReport and ingestRunReportFromEnv throw RunReportIngestError on every non-2xx control-plane response. Await the promise without converting that error into a passing teardown; its status, issues, and responseBody fields explain catalog/SHA rejection. ingestRunReportFromEnv also sets process.exitCode = 1 before rethrowing, so a broad customer-side catch cannot silently turn rejected evidence into a green CI command. Set THIAQ_ALLOW_INGEST_FAILURE=1 only for a deliberate negative ingest test.