Skip to content

Test in the emulator

Run your vertices with real tokens and services, then check what they did.

  1. Start the emulator, and upload your application with npm run emulate.

  2. Services. On the Services page, add the credentials and values that your services need. Then select them for the application, and on each vertex’s Services tab.

  3. Settings. If the vertex has a settings page, click Configure, and save valid settings.

  4. Inputs. On the vertex’s Receivers tab, choose the receiver and bind its inputs to signals. Only compatible signals are listed. Add more on the Signals page.

    A vertex’s Receivers tab, with each input bound to a test signal.

  5. Run. Click Run, and use the page if the vertex has one.

  6. Check. The Emulator tab shows the outputs. Console shows your logs.

A vertex that stays active, such as a dashboard, runs until you stop it. Stopping calls your onStop handler.

  • A run completes when the vertex sends on a standard or failure transmitter. A stream transmitter does not complete it.
  • A failure output still gives the status VERTEX_RUN_STATUS_SUCCEEDED. Check the output’s mode to tell.
  • The next run replaces the recorded outputs, so save what you need.

See Transmitter modes.

Your pages get real tokens in the emulator, so you can test your access rules. Call a protected route without a valid token. Use the address from executorUrl in the vertex’s API response:

Terminal window
curl -i https://exec-….emulator.localhost:51003/api/items # 401
curl -i -H "Authorization: Bearer invalid" \
https://exec-….emulator.localhost:51003/api/items # 403

Also try the settings page’s token, and a token from an earlier run. See Endpoint security.

The Resources tab shows CPU time, wall time, and memory for each entry point. Compare each invocation with the limits in runtime.json.

The Resources tab, with CPU time, wall time, and memory for each entry point.

Test with the largest inputs that you support, and keep a margin. If you come close to a limit, do less work, or raise the limit.

The emulator has no graph, so a small JavaScript program stands in for each exchange that your vertex dispatches. The emulator creates a starter program. Edit it, and apply it before you run.

Everything in the interface is also available through the emulator’s API. Its reference is at http://localhost:51001/docs/, with OpenAPI files for REST and Connect.

Terminal window
# The uploaded application, and its generation
curl -s http://localhost:51001/v1/emulator/state
# A vertex: readiness, page addresses, and its latest run
curl -s http://localhost:51001/v1/emulator/vertices/greeting
# Start a run
curl -s -X POST http://localhost:51001/v1/emulator/vertices/greeting/run:start \
-H "Content-Type: application/json" -d '{"generation": "<generation>"}'
  • Each change needs the current generation from the state. If a request fails with ABORTED, read the state again, and retry.
  • When a vertex cannot run, runReadiness in the vertex response says why.
  • The page addresses carry the browser token in the #mb_token fragment.

The API never returns saved secrets, so it is safe to let a coding agent use it.

With the adapt-emulator skill, a coding agent can run these checks for you:

Test ticket_form/ in the emulator. Run the vertex with test signals, check the
outputs, check that the API rejects missing and invalid tokens, and measure the
resource use. Record the results.

You still enter the secrets on the Services page, and sign in for OAuth2 consent.

The rest of the graph, parallel sessions, and how an update treats deployed state. Test parallel sessions and old data in unit tests, and record what you could not test.