Skip to main content

yarn test:integration:ephemeral

yarn test:integration:ephemeral executes yarn saasframe test:integration.

The command starts a disposable Postgres container and app runtime, runs the Playwright suite, and tears everything down when tests finish.

Usage​

# Preferred script
yarn test:integration:ephemeral

# Code coverage report from integration tests
yarn test:integration:coverage

# Interactive menu (persisted ephemeral environment)
yarn test:integration:ephemeral:interactive

# Direct CLI command (alias form)
yarn saasframe test:integration

# Direct CLI command (module/command form)
yarn saasframe test integration

# Direct CLI command (interactive menu)
yarn saasframe test:integration:interactive
# or
yarn saasframe test interactive

# Direct CLI command (coverage)
yarn saasframe test:integration:coverage
# or
yarn saasframe test coverage

Coverage command​

Use yarn test:integration:coverage to measure real Open Saasframe runtime code coverage driven by integration tests.

The command:

  • Starts the ephemeral integration environment
  • Enables Node.js V8 coverage for the running app
  • Executes Playwright integration tests
  • Produces coverage reports in .ai/qa/test-results/coverage/code/ (index.html, lcov.info, coverage-summary.json)

Options for yarn test:integration:coverage:

  • --filter <pattern> or positional <pattern> to run subset of tests
  • --workers <n> and --retries <n> passed to Playwright
  • --verbose
  • --screenshots / --no-screenshots
  • --no-reuse-env always starts a fresh ephemeral runtime (never attaches to existing .ai/qa/ephemeral-env.json)
  • --json outputs machine-readable totals
  • --keep-raw-v8 keeps raw process coverage files in .ai/qa/test-results/coverage/raw-v8/

Environment overrides:

  • SF_INTEGRATION_APP_READY_TIMEOUT_SECONDS=<seconds> increases the ephemeral app readiness timeout (default 90). This is the knob to raise in slower CI runners, for example SF_INTEGRATION_APP_READY_TIMEOUT_SECONDS=180 yarn test:integration:coverage.

If you still need scenario/spec mapping coverage:

yarn test:integration:spec-coverage

Options​

OptionDescription
--filter <pattern>Runs only tests matching a Playwright filter (same as positional filter).
<pattern>Positional shorthand for --filter.
--keepKeeps app and database running after tests (for debugging).
--verboseShows detailed bootstrap/build logs.
--screenshotsForces screenshot capture during test runs.
--no-screenshotsDisables screenshot capture during test runs.
--no-reuse-envForces a new ephemeral app+DB instance instead of reusing an existing one.

Examples​

# Run everything in ephemeral containers
yarn test:integration:ephemeral

# Run only auth-related tests
yarn saasframe test:integration --filter auth/

# Keep environment alive for debugging after tests
yarn saasframe test:integration --keep --verbose

# Always start a new ephemeral runtime (no attach/reuse)
yarn saasframe test:integration --no-reuse-env

Speed up local runs​

yarn test:integration:ephemeral is optimized for clean, fully isolated runs, not for quick iteration. For day-to-day development, use one of these faster patterns:

# 1) Start interactive ephemeral mode once (preferred)
yarn test:integration:ephemeral:interactive --no-screenshots

# 2) Run only the test you are changing against that running environment
BASE_URL=http://127.0.0.1:<port> npx playwright test --config .ai/qa/tests/playwright.config.ts sales/TC-SALES-007.spec.ts --retries=0

# 3) Run with more workers locally when tests are independent
BASE_URL=http://127.0.0.1:<port> npx playwright test --config .ai/qa/tests/playwright.config.ts --workers=4 --retries=0

# 4) Keep ephemeral mode but filter aggressively
yarn test:integration:ephemeral -- --filter sales/TC-SALES-007.spec.ts --no-screenshots

Notes:

  • Ephemeral state is written to .ai/qa/ephemeral-env.json; read baseUrl from this file before running manual Playwright commands.
  • Default ephemeral port is 5001 when available; fallback ports are recorded in .ai/qa/ephemeral-env.json.
  • Use --workers only if tests do not share mutable state.
  • Keep full yarn test:integration:ephemeral for pre-merge confidence and CI parity.

Requirements​

  • Node.js 24.x
  • Docker runtime available (docker info must succeed)

Notes​

  • By default, screenshot capture is enabled locally and disabled in CI.
  • The command ensures Playwright Chromium is installed before running tests.

Interactive mode​

Use interactive mode when you want to keep one ephemeral app/database running and execute multiple tests without re-bootstrapping each time.

yarn test:integration:ephemeral:interactive

The command writes active environment details to .ai/qa/ephemeral-env.json and clears the file when the environment is closed.

Menu actions:

  • Run all tests (or all filtered tests when a text filter is active)
  • Run one selected test file from the list (with test description shown next to each file)
  • Type text (for example crm) to filter the visible list interactively by path/description
  • Refresh test list
  • Clear active filter (a)
  • Open Playwright HTML report (show-report)
  • Quit and tear down ephemeral environment

After each test run, the CLI asks whether to:

  • Return to the menu (press any key, then Enter)
  • Open HTML report immediately (h)
  • Quit (q)

Supported options:

  • --verbose
  • --screenshots
  • --no-screenshots
  • --workers <n>
  • --retries <n>
  • --no-reuse-env