Skip to main content
hue world run starts a fresh instance of a World version, runs your test command with the instance’s app URLs and world token in its environment, and finishes the instance when the command exits. Each test run gets its own emulator, as with Testcontainers, LocalStack or firebase emulators:exec. Your code keeps its production app clients, and Hue answers their calls from the World’s records in each app’s own format, so you no longer maintain mock responses.

Run your tests in a World

You need a World version and a Read and write project key. Generate a World in Hue or with hue world create, which prints the version’s ID. Then put your test command after --:
@latest looks the package up on npm on every run, and a machine without npm’s cache, such as a fresh CI runner, downloads it each time. Keep it for a first try. For repeat use, add the SDK as a pinned dev dependency and run its hue binary:
hue world run reads HUE_API_KEY from the environment first, then from a dotenv file named with --env-path, then from ./.env.hue in the working directory, the file hue login writes. The command under test never receives the key. To keep the key out of the repository, export it in your shell or keep the file elsewhere:
Every run starts from the same starting state, and concurrent runs get separate instances. The command receives HUE_SIM_<SURFACE>_URL and HUE_SIM_<SURFACE>_ALIAS for each app surface, HUE_WORLD_TOKEN, HUE_WORLD_EXPIRES_AT, HUE_WORLD_NOW, HUE_MCP_CONFIG and the rest of the instance’s variables. HUE_WORLD_TOKEN works until the instance finishes or expires at HUE_WORLD_EXPIRES_AT (RFC 3339, from 0.30.1). hue world run finishes the instance when the command exits, so don’t refresh the token. When the command exits, the CLI prints the calls it made, what it changed and any coverage gaps, then exits with the command’s exit code. From 0.30.1, when no call reached the World, it adds Warning: no app calls reached the World. The command may still be using a mock or the real app. A test that stubs the app client never reaches the World, and neither does a client still pointed at the real app. In CI, add --require-calls, which turns that warning into exit code 1 when the command otherwise succeeded. The CLI reference covers the details.

Point app clients at the World

Build each app client with the appEndpoint helper from Connect your agent. When HUE_WORLD_TOKEN is set, the helper returns the World’s URL and token, and it throws instead of calling the real app when the World has no URL for it. Without HUE_WORLD_TOKEN, it returns your production values.
  • For googleapis, follow Direct REST clients. One rootUrl serves both Gmail and Calendar, as www.googleapis.com does, and HUE_SIM_GOOGLE_GMAIL_REST_ALIAS and HUE_SIM_GOOGLE_CALENDAR_REST_ALIAS also work per service.
  • If your app stores each user’s app connection, store the World’s values on a test user, as Integrations saved in your app describes.
Skip tests that need the World when HUE_WORLD_TOKEN is not set, so a plain test run never reaches a real account.

Use the World’s date

A World has its own clock, which is not the day your tests run, and its records are dated relative to it. Take “today” from HUE_WORLD_NOW in the code under test and in the dates your tests expect:
today.ts
Relative dates covers Python and wrapper scripts. HUE_WORLD_NOW is the World’s clock when the instance starts. After that, the clock moves a fixed step with each write the World receives, not with wall-clock time. In code that schedules work, such as a timer or a reminder for tomorrow, compute each delay from HUE_WORLD_NOW. Otherwise, in a World dated in the past, each due time is already past by the wall clock, so every timer fires at once. To test what happens later, jump a running instance’s clock forward with POST /api/v1/instances/<instance ID>/clock and a Read and write project key. The body takes a requestId and either bySeconds or a later RFC 3339 to. GET on the same path reads the clock, and the MCP tools advance_world_clock and get_world_clock do the same. Clock jumps serve LinkedIn, X and Gmail instances. hue world run prints the instance ID before the command starts. The command under test can’t move the clock, because it never receives a project key.

Run the tests in CI

This GitHub Actions workflow runs the tests in a World when a pull request changes the Google integration, with the CLI that npm ci installs from your pinned dev dependency. HUE_API_KEY is the only secret. The World answers in place of Gmail and Calendar, so the job needs no Google credentials.
.github/workflows/world-tests.yml
Replace the paths with the files that reach the apps, and npm test with your test command. The step fails when the tests fail or no app call reached the World, and its log lists the calls, writes and coverage gaps. If you make the check required, see the note on paths.