Docs

Getting started

QA Reef's automation core is being extracted into an open, MIT-licensed package (packages/core) — what it needs to run, and the concepts it's built from.

Requirements

Requirement	Why
Node 22	Runtime for the flow runner, Operator, and adapters.
Playwright (Chromium)	Drives the real browser — navigation, input, screenshots, tracing.
macOS, for on-device OCR — or —	Apple Vision (~94% mean word recall, measured internally) reads the screen locally.
a 27B-class vision model reachable over the network (e.g. self-hosted via Ollama)	The non-macOS OCR path — degrades gracefully, never a hard macOS requirement.
An OpenRouter key	Powers the cheap text model deciding each Operator step, and the chat agent. Local Ollama covers zero-cost decisions.

Quickstart (shape of it)

Not published yet — the link goes live at launch. Install/run shape it's being built toward:

npm install
export OPENROUTER_API_KEY=...   # cheap text model for the Operator
npm run flow -- flows/*.flow.js # run flows, screenshot+trace on failure
npx playwright show-trace artifacts/<flow>/trace.zip

Core concepts

flow(name, opts, fn) — the flow/test runtime: named steps, a screenshot per step, a trace on failure.
Operator — look() OCRs the screen → an LLM decides the next action (stamped decided_by) → the mouse moves on a jittered path → click()/type()/press()/scroll(). run(goal) loops until the model reports done.
Adapters — OCR and LLM calls go through an interface: swap Apple Vision/vision-model or OpenRouter/Ollama without touching the loop.
Traces — one JSON line per step: screenshot path, OCR'd words, decision, action. Stable on purpose.

PASS / FAIL / UNMEASURED

Checks and runs report three states, not two. UNMEASURED covers a check that never got a clean look — page never loaded, viewport drifted — and never collapses into FAIL. See the blog post.

Not published yet

The repository link, package name, and CLI surface aren't final. Want to build against this early? Email us.