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 package link goes live at launch. This is the install-and-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) is 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, so you can 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.