Testing

FlowPad's tests live outside the package — in the matrix-3 repo's shared tests/ tree. The package only ships package.json script entries that invoke the workspace test runner.

Test commands (from `projects/matrix-3/packages/flowpad/package.json`)

jsonc

"scripts": {
  "test":     "cd ../.. && tsx scripts/test.ts --timeout 30000 tests/unit/flowpad-v2/**/*.spec.ts tests/integration/flowpad-v2/**/*.spec.ts",
  "test:ci":  "cd ../.. && tsx scripts/test.ts --timeout 30000 tests/unit/flowpad-v2/**/*.spec.ts",
  "test:unit":"tsx --test tests/unit/**/*.spec.ts",
  "type-check":"tsc --noEmit"
}

pnpm --filter @open-matrix/flowpad test runs both unit and integration tests with a 30s timeout. test:ci runs only unit specs (faster, sufficient for change-detection gating).

Unit tests

projects/matrix-3/tests/unit/flowpad-v2/:

execution-status-topology.spec.ts — resolveExecutionTopology fixture-based tests. Covers the topology summary string when authority/runtime/platform roots vary, and when a requested root is unavailable.
test-runner.spec.ts — exercises the unit-test harness for FlowPad's runtime helpers.

These run via Node's --test mode. They do not start a browser; they import the source modules directly.

Integration tests

projects/matrix-3/tests/integration/flowpad-v2/:

headless-runner.spec.ts — boots a FlowPad runtime headlessly (no DOM), mounts services, and runs DSL examples end-to-end against the in-memory transport. This catches regressions in compileSourceToCanonicalIR and executeCanonicalIR.
project-loader.spec.ts — covers shell/projectCatalog.ts: manifest parsing, dependency topo-sort, alias resolution, and validation of malformed manifests.

End-to-end (Playwright)

projects/matrix-3/tests/e2e/:

flowpad-functional.spec.ts — drives the rendered FlowPad page through Playwright. Asserts that the editor accepts input, the run button executes, results appear, and transport messages are logged.
flowpad-buttons.spec.ts — focused checks on the toolbar buttons (Run, Clear, copy mount tag).
dogfood-flow.spec.ts — bigger scenario combining FlowPad, the catalog, and a target actor.
e2e-flowpad-daemon.spec.ts — covers the historical daemon-routed run mode. Note: this exercises the retired matrixd path; it is kept as a regression guard but new product runs go through hivecast start and the Host Service.
e2e-cli-prompt-flowpad.spec.ts — tests CLI-driven prompts that target FlowPad as $TARGET.
e2e-security-flowpad.spec.ts — exercises the security-realm DSL examples.
e2e-runtime-control-flow-roundtrip.node.ts + .LOG.md — runtime-control-flow round-trip; the .LOG.md companion captures expected output.

End-to-end tests require a built dist/ (Pattern: rebuild before testing — see project rules). The recipe:

bash

pnpm --filter @open-matrix/flowpad build
pnpm --filter @open-matrix/flowpad test
# Then:
cd projects/matrix-3
npx playwright test tests/e2e/flowpad-functional.spec.ts

Type checking

pnpm --filter @open-matrix/flowpad type-check runs tsc --noEmit against projects/matrix-3/packages/flowpad/tsconfig.json. The package is required to be --strict clean per project Rule 9.

What the tests do not cover

Real cross-Host federation. The integration tests use the in-memory transport; the federated NATS path is exercised by tests/e2e/ only.
The COM Bridge example flows ('COM: ...' examples in dsl/examples.ts). They require a Windows host and a running com-bridge daemon.
Real LLM-driven flows. The 'Agent: ...' examples assume a connected inference service; CI runs them only with mocks.

CI gating

The five-gate pre-merge gate (scripts/ci/premerge-local.sh, see project CLAUDE.md) runs FlowPad's test:ci, type-check, and the package-boundary guard. Anything tagged with the harvest watchlist (e.g. cross-package ../../ imports) fails the gate before merge.

Testing ​

Test commands (from projects/matrix-3/packages/flowpad/package.json) ​

Unit tests ​

Integration tests ​

End-to-end (Playwright) ​

Type checking ​

What the tests do not cover ​

CI gating ​

See also ​