flowcheck

Your coding agent changed the UI. Does the user journey still work?

FlowCheck Local replays a JSON scenario in Chromium and saves a pass/fail report, screenshots, a Playwright trace, and JUnit XML. Review the steps once, commit them, and rerun the same checks from the CLI or an MCP client after the next change.

Runs on localhost. No FlowCheck account, API key, or model call required by the runner.

An optional software engineering runtime is available as a separate CLI. It can invoke Codex for code changes; browser checks remain deterministic.

You or your agent → reviewable JSON scenario → Chromium → pass/fail + evidence

Use it for small smoke checks such as signup, form submission, and navigation. The runner executes the steps you supply; an AI agent can help write them before a run.

Try the demo · See it catch a failure · Choose the right tool

Quickstart

Requires Node.js 22.18+ on macOS or Linux. Run from any directory:

npx --yes @kadessovb/flowcheck demo

That is the complete setup: npm fetches the published package, FlowCheck downloads Chromium if missing, starts its bundled app on a free port, checks a real user journey, and saves evidence in your current directory. Later runs reuse the caches. No Git clone, build step, account, or AI subscription is needed.

First use requires an internet connection and space for Chromium. Minimal Linux installations may also need system libraries: run the same command with setup --with-deps instead of demo. This explicit command may request administrator privileges; regular runs never install OS packages.

No project installation is required for the commands below. To pin FlowCheck in your project dependencies instead:

npm install --save-dev @kadessovb/flowcheck
npx flowcheck --help

With a project installation, you can use npx flowcheck as a shorter alias. Published packages are available on npm; versioned archives are also available through GitHub Releases.

Related MCP server: deploytest MCP server

Check your app without an agent

Start your application, then run:

npx @kadessovb/flowcheck check http://localhost:3000
npx @kadessovb/flowcheck check http://localhost:3000/login --text "Sign in"

A page check requires a successful HTTP navigation and a visible page; --text also checks for the expected visible text. It does not claim to test every user journey. Use a scenario for interactions such as filling and submitting a form.

Add --headed to watch Chromium, or --json for a machine-readable result. Validation and setup errors return exit code 2, failed checks return 1, and successful checks return 0.

Use with a coding agent

From the project you want to test, choose your installed client:

npx @kadessovb/flowcheck connect codex

npx @kadessovb/flowcheck connect claude

The command prepares Chromium and uses the client's CLI to register a version-pinned stdio MCP server. It sets this project as the workspace and uses a project-specific server name, so connecting another project does not replace it. Codex stores the registration in its user configuration; Claude Code uses local project scope. Restart the client session after connecting. The codex or claude command must be on your PATH.

Then ask your agent:

Use FlowCheck to check my app at http://localhost:3000. Validate the signup journey using the actual labels in the code, run it, and show me the failed step and evidence if it breaks.

The agent can pass a scenario directly to MCP. No manual JSON file is required. Save useful scenarios in your repository when you want to repeat them later.

For another client that supports local stdio MCP, run npx @kadessovb/flowcheck config and copy the generated entry into its MCP configuration. It includes your workspace path. npx @kadessovb/flowcheck mcp also starts the server directly. Clients that only accept remote HTTP servers need a different transport; this release is local stdio only.

Agents with terminal access can use npx @kadessovb/flowcheck check ... --json and npx @kadessovb/flowcheck run ... --json without MCP. FlowCheck runs the checks; your chosen agent provides the reasoning.

Configuration references: Codex MCP, Claude Code MCP.

See it catch a failure

npx @kadessovb/flowcheck demo --broken

The demo app now shows an error when creating a workspace. The same assertions fail at confirmation, skip the remaining URL assertion, and save the failure screenshot and trace. FAILED and exit code 1 are expected here.

✓ open-home · goto
✓ enter-email · fill
✓ enter-company · fill
✓ create-workspace · click
✗ confirmation · assertText

FAILED
Evidence: .../.flowcheck/runs/<run-id>

This is a real screenshot from the public demo. Run npx @kadessovb/flowcheck demo to see the journey pass, or add --headed to watch either version.

Save a repeatable journey

npx @kadessovb/flowcheck init --url http://localhost:3000

Edit the generated flowcheck.scenario.json to describe the journey you want to protect:

{
  "version": 1,
  "name": "Create a workspace",
  "baseUrl": "http://localhost:3000",
  "evidence": { "screenshots": "on-failure", "trace": true },
  "steps": [
    { "id": "open", "action": "goto", "path": "/" },
    { "id": "email", "action": "fill", "target": { "label": "Work email" }, "value": "developer@example.com" },
    { "id": "company", "action": "fill", "target": { "label": "Company name" }, "value": "Acme" },
    { "id": "create", "action": "click", "target": { "role": "button", "name": "Create workspace" } },
    { "id": "confirm", "action": "assertText", "text": "Workspace Acme is ready", "exact": true }
  ]
}

Replace the example labels and text with those in your application, then run:

npx @kadessovb/flowcheck validate flowcheck.scenario.json
npx @kadessovb/flowcheck run --headed

The same JSON object works as the scenario argument to the MCP validation and run tools. Alternatively, use scenarioPath for a file inside the configured workspace. See the scenario reference for actions, locators, environment variables, and screenshot masking.

What a run produces

.flowcheck/runs/<run-id>/
├── report.json      # versioned machine-readable result
├── junit.xml        # CI-compatible result
├── trace.zip        # Playwright trace, when enabled
└── *.png            # screenshots, according to the scenario policy

Use --output <directory> to choose where evidence is saved. Keep .flowcheck/ out of source control. Open a trace with:

npx playwright show-trace .flowcheck/runs/<run-id>/trace.zip

The CI workflow exercises successful and failed runs and saves the public demo evidence.

Run reviewed journeys in CI

Put several v1 scenarios under checks/, then run the same files locally and in CI:

npx flowcheck run 'checks/**/*.json' --base-url http://127.0.0.1:3000 --output .flowcheck/runs

The quoted glob is resolved by FlowCheck. Files run in lexical order with a separate Chromium context each. Failed checks and invalid files are reported while later scenarios continue; infrastructure failure skips the rest. An empty match is an error. --base-url changes the tested origin without editing committed scenarios. Use root-relative URL assertions to check a preview deployment's path; absolute expected URLs remain unchanged.

Copy and adapt the GitHub Actions recipe: it starts the application, waits up to 30 seconds, runs the suite, writes a job summary, and uploads JSON/JUnit evidence even after a failed check. The recipe installs the published npm package; until this change is released, test it with a locally built package tarball. Pin a published version after verifying it. Keep CI scenarios and uploaded artifacts synthetic and reviewed.

Check a frontend before each commit

FlowCheck can act as a local Git pre-commit check for an npm project. Keep one short, reviewed scenario in your app repository, for example checks/pre-commit.json:

{
  "version": 1,
  "name": "Save settings",
  "baseUrl": "http://127.0.0.1:3000",
  "timeoutMs": 3000,
  "steps": [
    { "id": "open", "action": "goto", "path": "/settings" },
    { "id": "save", "action": "click", "target": { "role": "button", "name": "Save" } },
    { "id": "confirm", "action": "assertText", "text": "Settings saved", "exact": true }
  ]
}

Once a version containing this command is published, install and prepare it in that project:

npm install --save-dev @kadessovb/flowcheck
npx flowcheck setup
npx flowcheck hook install checks/pre-commit.json --base-url http://127.0.0.1:3000

Start your frontend before committing. The scenario must contain an assertion; a page open alone is rejected. The hook runs only this scenario, disables trace capture, and takes a masked screenshot if a step fails, even when the scenario normally has screenshots off. A failed assertion blocks the commit with exit code 1; setup failures use 2. It prints the failed step and screenshot path and opens the PNG automatically on macOS or a Linux desktop when a viewer is available. Try the same check manually with npx flowcheck pre-commit checks/pre-commit.json. The hook refuses to replace an existing pre-commit hook and respects Git's configured hooks path; add its printed command to an existing hook if you use Husky or another hook manager.

Evidence stays under .flowcheck/pre-commit/ and is not uploaded. The hook checks the currently running app and working tree, which may differ from the staged commit. Use the CI suite for a check against the code built in CI. The browser is cached after setup, but runtime depends on the app and scenario; keep the pre-commit journey short and use representative test data. This command is not part of npm version 0.2.1; use a built tarball until the next release.

How it fits with Playwright

FlowCheck uses Playwright underneath. Choose based on the workflow you need:

Already happy with a Playwright suite? Keep it. FlowCheck focuses on small smoke checks that a developer or agent can run and repeat quickly.

Troubleshooting

• Chromium download failed: check your network, then run npx @kadessovb/flowcheck setup.

• Missing Linux libraries: run npx @kadessovb/flowcheck setup --with-deps explicitly.

• Offline or managed environment: provision Chromium with setup first, then set FLOWCHECK_SKIP_BROWSER_INSTALL=1 to prevent automatic browser downloads. Cache/install the npm package as well.

• Agent CLI not found: use npx @kadessovb/flowcheck config for a manual MCP entry. An AI client is optional for all CLI checks.

• Wrong application or port: start your app separately and pass its exact URL. FlowCheck starts only its bundled demo automatically.

Security and status

FlowCheck is an early developer preview, supporting Chromium on macOS and Linux. The scenario and report formats are versioned but may change before a stable release.

The report format is now schemaVersion: 2; consumers of v1 reports need to handle explicit skipped steps and infrastructure errors. UI timing, app state, test data, and environment still affect repeatability. FlowCheck intentionally provides a small reviewed scenario format alongside Playwright, rather than Playwright's full test framework.

Run checks only against systems you are authorized to test. Navigation is restricted to the scenario's origin. Prefer valueFromEnv for secrets and explicit screenshot masks. Masks do not redact traces, URLs, or error messages; treat evidence as potentially sensitive. The browser runner makes no model calls or FlowCheck telemetry requests. The separate, opt-in flowcheck-runtime can send task context to Codex; see its documentation. npm package and browser downloads contact their distribution services.

See SECURITY.md and architecture. The local runner works independently of any hosted FlowCheck service.

Contributing

Try one real journey and tell us what failed or felt difficult. For development from source, see CONTRIBUTING.md.

If repeatable browser checks would help your workflow, star the repository to help others discover it.

License

Apache-2.0. The license covers this repository, not hosted services or FlowCheck trademarks.