Run and observe
Contract watcher
Download one file, start it in your frontend in development, and every real API call is checked against your contracts.
Open Systems in the appWhat the watcher does
The contract watcher is a small script you add to a frontend while you develop. It watches every API call your app makes and checks the request and the response against the contracts in Rabbinatix. When something doesn't match, you see it in the browser console and in a badge on the page.
It covers fetch and XMLHttpRequest, so it works with Angular's HttpClient, axios and plain fetch. It is one file with no extra libraries, and nothing to install. Phone apps (Android, iOS, Flutter, React Native) and backends traced with OpenTelemetry get the same checks: see Phone apps and OpenTelemetry.
Download it
- Open the frontend system in Systems. It must consume at least one API.
- Go to the Uses tab and click Contract watcher. It is also in the … menu at the top of the system page.
- Under Hosts, check which API origin belongs to which system. The table starts with the systems this one calls. Click Host to add a row, such as
api.acme.com. Use/for your dev server's own origin, for example when it proxies API calls. Calls to a provider's test server are checked without a host. - Pick your framework under Start it in development and click Copy.
- Click Download.
You get rabbinatix-watch-<system>.zip with three files:
Put the files in your project, for example in src/dev/.
Start it in development
Start the watcher before your app, inside a branch that only runs in development. The dynamic import() keeps it out of production builds.
Angular (src/main.ts):
async function start() {
if (typeof ngDevMode === 'undefined' || ngDevMode) {
const { watchContracts } = await import('./dev/rabbinatix-watch.js');
watchContracts();
}
await bootstrapApplication(AppComponent, appConfig);
}
start();Vite (React, Vue, Svelte):
if (import.meta.env.DEV) {
const { watchContracts } = await import('./dev/rabbinatix-watch.js');
watchContracts();
}Next.js (instrumentation-client.ts, Next 15.3 or later):
if (process.env.NODE_ENV === 'development') {
import('./src/dev/rabbinatix-watch.js').then(({ watchContracts }) => watchContracts());
}When it starts, the console says Rabbinatix watcher with the number of APIs and the date of the contracts.
What it reports
Only JSON is checked. Repeats are counted, not printed again.
Read the findings
- Console: one message per call and new problem.
- Badge: bottom right, red for breaking and amber for warnings. Click it for the list. Each item links to the contract in Rabbinatix. Hide hides it until the next finding; Clear empties the list.
- In code:
window.__rabbinatix.findings(),.clear()and.failed().
The README in the download explains the options: hosts, warnOn, failOn, ignore, sample, maxBodyBytes and undeclared. With failOn: 'breaking' you can fail end-to-end tests on breaking findings.
Reporting to Rabbinatix
Each download carries a key that lets the watcher report what it finds. A few seconds after a finding, the watcher sends it to Rabbinatix. It sends what was expected and found, never the values from your app. It also sends the calls it checked: which API, the status and the timing, not the URL.
In Rabbinatix:
- Findings show on the connection's page under Mismatches seen in development, with their level, count and when they were last seen.
- Calls no contract covers show on the frontend's Uses tab under Declare this API?. Declare opens the endpoint editor with the call filled in. Not now hides it for everyone.
- The calls become recorded calls of the flows that make them. See Real logic and real traffic.
To keep findings in the browser only, start it with watchContracts({ share: false }).
Keep it up to date
The contracts are inside the file. When an API the frontend consumes changes, the Uses tab shows "Contracts changed since your last watcher download" with Download again. Download again and replace the files.
Check a recording
Calls you recorded elsewhere can be checked the same way: save the browser's Network tab with Save all as HAR (or export a HAR from a proxy), then run, next to the downloaded watcher:
npx -y rabbinatix watch import session.har --watcher src/dev/rabbinatix-watch.jsIt checks every call against the contracts in the watcher, prints the findings, and reports them with the watcher's key, like the watcher does: drift on the connection page, unknown calls as Declare this API?. Values seen are never sent. --no-share only prints. More: The rabbinatix CLI.
A file of OpenTelemetry traces in JSON works the same way (see OpenTelemetry).
Phone apps
A phone app can't run the browser watcher, so it sends each call it makes to your computer, and the rabbinatix CLI checks it there with the same contracts. What your app sends and receives stays on your computer; findings go to Rabbinatix like the browser watcher's.
- Download the watcher as above. The download has a
phone/folder with one file per platform. In the dialog, the Android, iOS, Flutter and React Native tabs show how to start it. - Copy your platform's file into your app and start it in debug builds only:
- In a terminal, next to
rabbinatix-watch.js:
npx -y rabbinatix watch listenRun your app. Each new finding prints in the terminal as it happens; Ctrl+C stops it with a summary.
The Android emulator reaches your computer at 10.0.2.2 and the iOS simulator at 127.0.0.1, which the files use by default. For a phone on your network, start the listener with --host 0.0.0.0 and give the file your computer's address and the code the terminal shows. Android debug builds must allow plain HTTP to your computer; the README in the download shows the setting.
OpenTelemetry
A service already traced with OpenTelemetry can send its traces to the same listener. Point its exporter at it:
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4012The exporter's default format (protobuf) and JSON both work, compressed or not. Or check a file of traces from a collector's file exporter, in either of its formats: npx -y rabbinatix watch import traces.json.
Each call the service makes (a client span) is checked. Traces don't hold bodies, so they show status codes your contract doesn't handle, calls no contract covers, and, when your OpenTelemetry setup records request headers, the headers and auth a provider requires. Response fields need the browser watcher or a phone file.
@rabbinatix/watch) and framework adapters are planned. Today the watcher is the downloaded file.Related
- Test serverEvery system gets a test server URL that answers like its declared endpoints, so frontends can start before the backend exists.
- Real logic and real trafficRun test cases with every system answering through its real logic, and compare the flows you designed with the calls a running app makes.
- APIs and contractsDeclare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.
