> ## Documentation Index > Fetch the complete documentation index at: https://docs.hue.run/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To set up Hue in an application, fetch https://docs.hue.run/guides/agent-setup.md and follow it. > Hue's project-data MCP server is https://mcp.hue.run/mcp. https://docs.hue.run/mcp only searches these docs and cannot read a Hue project. > Never ask the user to paste a Hue API key into chat; they store it as HUE_API_KEY themselves. > Install the exact SDK versions pinned on the page you're following, or on https://docs.hue.run/quickstart.md. Run the latest CLI without a project install as `npx -y @hue-run/sdk@latest`. In a project with `@hue-run/sdk` installed, use `npx hue`. Pin an exact version for reproducible CI runs. > Use Hue product terms: eval set, case, evaluator, run and scoring run. Older APIs may say dataset, scorer or experiment; prefer the current SDK methods. See https://docs.hue.run/concepts.md. # Use a World in your tests > Run your own tests against a fresh World instance in place of Gmail, Calendar and other app mocks. `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](https://docs.hue.run/quickstart.md#project-keys). [Generate a World](https://docs.hue.run/worlds/create-with-mcp.md) in Hue or with [`hue world create`](https://docs.hue.run/sdks/cli#create-a-world), which prints the version's ID. Then put your test command after `--`: ```sh theme={null} npx -y @hue-run/sdk@latest world run "" -- npm test ``` `@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: ```sh npm theme={null} npm install --save-dev --save-exact @hue-run/sdk@0.30.2 npx hue world run "" -- npm test ``` ```sh Bun theme={null} bun add --dev --exact @hue-run/sdk@0.30.2 bunx hue world run "" -- bun test ``` `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: ```sh theme={null} npx hue world run "" --env-path ~/.config/hue/.env -- npm test ``` Every run starts from the same starting state, and concurrent runs get separate instances. The command receives `HUE_SIM__URL` and `HUE_SIM__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](https://docs.hue.run/sdks/cli.md#run-a-command-in-a-world) covers the details. ## Point app clients at the World Build each app client with the `appEndpoint` helper from [Connect your agent](https://docs.hue.run/evaluations/eval-ready-agent.md#point-clients-at-hue). 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](https://docs.hue.run/evaluations/eval-ready-agent.md#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](https://docs.hue.run/evaluations/eval-ready-agent.md#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: ```ts title="today.ts" theme={null} // The World's clock under `hue world run`; the wall clock otherwise. export const today = (): Date => process.env.HUE_WORLD_NOW ? new Date(process.env.HUE_WORLD_NOW) : new Date(); ``` [Relative dates](https://docs.hue.run/evaluations/eval-ready-agent.md#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//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](https://docs.hue.run/agents/mcp-tools.md) `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. ```yaml .github/workflows/world-tests.yml theme={null} name: World tests on: pull_request: paths: - "src/google/**" - "test/google/**" - ".github/workflows/world-tests.yml" permissions: contents: read jobs: world-tests: name: World tests runs-on: ubuntu-latest timeout-minutes: 20 steps: - uses: actions/checkout@v5 with: persist-credentials: false - uses: actions/setup-node@v6 with: node-version: '24' package-manager-cache: false - run: npm ci - name: Run tests in a World env: HUE_API_KEY: ${{ secrets.HUE_API_KEY }} run: npx hue world run "" --require-calls -- npm test ``` 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`](https://docs.hue.run/evaluations/ci#run-an-eval-set-from-the-cli-in-ci). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.