RabbinatixDocs
Sign inGet started

Run and observe

Test server

Every system gets a test server URL that answers like its declared endpoints, so frontends can start before the backend exists.

Open Test server in the app

What the test server does

Every system you own has a test server (often called a mock server). It is a stand-in for the system's API. It answers each provider endpoint the system declares, with example data made from the endpoint's response shape. The example respects types, enums, formats and nullable fields, so it is valid against the contract.

The test server works for endpoints that aren't built yet. "Built" means the real API has been programmed and is running somewhere. An endpoint marked To do or In progress answers the same way as a deployed one.

Who calls it

Rabbinatix doesn't call the test server for you. Another team's app or service does, while the real API isn't ready. For example:

  • Team A owns Users API. They declare GET /users/{id} in Rabbinatix but haven't built it yet.
  • Team B builds a mobile app, or a backend service, that needs a user's name. Their app can't call Team A's API, because it doesn't exist yet.
  • Team B copies the test server address of GET /users/{id} and uses it in place of the real API address. Their app now gets example users and they can keep working.
  • When Team A ships the real API, Team B switches the address to the real one. Nothing else changes.

The caller can be a web or mobile app, a backend service, an automated test or a person with curl or a browser. Use it only while developing and testing: the answers are made up, never real data.

Before you start

Two things have to be true before the test server answers:

  1. The endpoint is on the system's APIs tab. The test server answers only the endpoints a system *provides*. The calls a system makes to other systems (its Uses tab) are answered by those other systems' test servers. A system that provides nothing has no Test server.
  2. The endpoint is published. The test server reads only what is published to Development. If your organization uses Review before publishing, a new or changed endpoint stays in your unpublished changes (the Unpublished · N changes badge at the top of the page) until you publish it. In Test server such an endpoint has a Draft badge. Click the badge, or Review and publish, then Publish to Development.

An endpoint's status (To do, In progress, Deployed) doesn't matter. Only whether it is published does.

Find the endpoint's address

  1. Open Test server in the sidebar.
  2. Pick the system that provides the API in System at the top right. (From a system's page, Test server in its … menu opens it with that system picked.)
  3. Pick an endpoint in the list.
  4. Click Copy endpoint URL. That is the full address to call.
  5. If the path has values like {id}, replace them with real ones, such as /users/42.

Copy URL under Test server copies only the system's base address. On its own it answers nothing: you have to add an endpoint's path after it.

You can also open an endpoint in the endpoint editor and go to its Test server tab. It shows the Test server URL for that one endpoint, a button per declared status, and the example body for the status you pick.

The URL shape

The base URL ends with your organization ID, the project ID and the system ID. You add the endpoint's path after it:

<test server address>/<organization id>/<project id>/<system id>/<endpoint path>

For example, if Auth Service declares GET /api/v2/users/{id}, you call:

curl <test server address>/acme/main/auth-service/api/v2/users/42

Path parameters such as {id} or :id match any value. When two declarations fit, an exact path wins over one with parameters. Copy the base URL from Test server rather than typing it: the IDs in it are your organization's own.

Every answer has the headers content-type: application/json and x-rabbinatix-mock: true, and x-rabbinatix-endpoint with the ID of the endpoint that answered.

Choose the response

By default the test server answers with the first 2xx response the endpoint declares. To get another declared response, ask for its status:

HowExample
Query parameter?__status=404
HeaderX-Mock-Status: 404

The status must be one the endpoint declares. If it isn't, the test server answers 404 and says which response is missing. Use this to build and test your error states, such as an expired session or a payment that was declined.

Other example values

The same request always returns the same body. To get other values, add a sample key. A sample key is any word you choose:

HowExample
Query parameter?__seed=abc
HeaderX-Mock-Seed: abc

The same sample key always gives the same body, so tests stay stable. A different sample key gives different values with the same shape. Use one sample key per test record, for example ?__seed=user1 and ?__seed=user2 for two different users.

In Test server, type a value in Sample key (optional) to preview what that sample key returns. The copied endpoint address then includes it.

Choose the API version

When two versions of an API have the same path, for example after Copy to new version on paths without a version in them, the newest version answers. To get another one, ask for it:

HowExample
Query parameter?__version=v1
HeaderX-Mock-Version: v1

A version the API doesn't have is refused with a 404 that names the versions it has, so a typo doesn't quietly get another version.

Where the example values come from

Nothing is stored. Each answer is made up when the call arrives, from the endpoint's declared response shape:

  • each field in the shape becomes a field in the answer, with the declared type;
  • the field name picks a fitting value: email gives an address at example.com, a field ending in name gives a person's name, createdAt gives a date, status gives active and so on;
  • an enum picks one of its values; a list gets 1 to 3 items;
  • anything else gets a plain placeholder such as string or 42.

Without a sample key you always get the same typical values. With a sample key the picks change.

Use it from a frontend

Point your app's API base URL at the test server while the real endpoint isn't ready:

// environment.development.ts
export const environment = {
  apiBase: '<test server address>/acme/main/auth-service',
};
const res = await fetch(environment.apiBase + '/api/v2/users/42');

The test server allows cross-origin calls, so a dev server on localhost can call it directly. Switch apiBase to the real service when the endpoint goes live. Run the contract watcher in development to see whether the real responses still match.

Run it on your machine

The test server can also run on your own computer or in your CI pipeline. It answers exactly like the hosted one: the same example values, __status, __seed, __version and Validate requests. Calls to it never leave your machine, so it is faster, works offline once started, and has no limit on calls.

You need Node.js 20 or later and an API token with the read scope (Integrations → API tokens). The address to use is under Integrations → API & CI.

export RABBINATIX_API="<API address from Integrations → API & CI>"
export RABBINATIX_TOKEN="cm_live_…"
npx -y rabbinatix mock --system auth-service

It loads the system's published APIs once, then lists them and answers at http://127.0.0.1:4010. There is no organization, project or system ID in the address: call the endpoint's path directly, such as http://127.0.0.1:4010/api/v2/users/42. Each call is printed with its answer.

  • --system takes the system's ID or its name. Test server shows the command with the ID filled in.
  • After you publish a change, type r and Enter to load the system again. Stop it with Ctrl+C.
  • --port 5000 picks another port. --host 0.0.0.0 lets other machines or containers reach it.
  • --save orders.mock.json also writes what it loaded to a file. --from orders.mock.json starts from that file without calling Rabbinatix and without a token. Commit the file so tests in CI use the same APIs every time.
  • --quiet stops printing each call. --help lists every option.

Each start, and each r, is one call to Rabbinatix. The calls your app makes to the test server aren't.

When a call doesn't match

AnswerMeaning
400 Use /{org}/{project}/{system}/<path>.The URL is missing the organization, project or system ID
404 No mock for system …The system has no published provider endpoints. Check its APIs tab, and publish your changes if the endpoints have a Draft badge
404 No declared endpoint for …No published endpoint fits this method and path; the body lists the declared ones. Often the address is only the base address with no endpoint path, or the method is wrong (a browser always sends GET), or the endpoint is still in your draft
404 … declares no … responseYou asked for a status the endpoint doesn't declare
400 This request doesn't match …Validate requests is on and the call doesn't fit the declared request; problems lists each one

Validate requests

By default the test server answers any call that fits a declared method and path. Turn on Validate requests on the endpoint editor's Test server tab (you need to be allowed to edit endpoints) and it checks each call against the provider's declared request first:

  • required query parameters and headers are there;
  • an Authorization header is sent when the endpoint requires bearer or basic auth;
  • the JSON body of a POST, PUT or PATCH has the declared fields and types (null where null isn't allowed, missing required fields, wrong types).

A call that doesn't fit gets a 400 with the header x-rabbinatix-mock-rejected: true and a body like:

{
  "error": "This request doesn't match POST /api/v2/login as declared.",
  "problems": [{ "pointer": "request.password", "message": "request.password is required but was not sent" }]
}

Your frontend then fails against the test server the same way it would fail against the real provider, before the provider exists. The setting is per endpoint and the whole team sees it.