> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atonom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Test & mock tool calls

> Test scripts with sample inputs and mock responses for tool calls.

Use `eval` to exercise a local script in the sandbox, then use `run --no-save` to verify the stored version through the platform. A passing mock test validates your Lua logic, not the availability or permissions of a live capability.

Configure [sandbox access](/atonom-script/cli/install#connect-the-sandbox-optional) before using `eval`. If your setup does not include a sandbox, go to [Test the platform path](#test-the-platform-path).

## Run a chunk or a transform

```sh theme={null}
atonom eval -c 'return { answer = 42 }' --json
printf 'return 42\n' | atonom eval - --json
atonom eval .atonom/scripts/order-total.lua \
  --transform '{"qty":2,"unit_price":12.5}' --json
```

The last command uses the script from [Your first Lua tool](/atonom-script/cli/first-tool). Run it from your script workspace and substitute your actual file path. `eval` resolves files from the current directory, not from `.atonom/scripts/` automatically.

Raw `eval` returns the chunk's top-level return value. `--transform` binds the JSON object as `context` and appends `return transform(context)`. Do not add a top-level return to a stored transform file that you plan to test with this flag.

`--bindings '{"region":"west"}'` binds keys as Lua globals. If both bindings and `--transform` specify `context`, the transform context wins.

## Mock a host call

Save this example as `search-summary.lua` in your working folder:

```lua theme={null}
function transform(context)
  if type(context.query) ~= "string" or context.query == "" then
    error("query is required")
  end

  local result, err = atonom.toolcall("web_search", { query = context.query })
  if err then
    return { ok = false, error = err }
  end
  if type(result) ~= "table" or type(result.hits) ~= "table" then
    error("search result must contain hits")
  end

  return { ok = true, count = #result.hits }
end
```

Test a nonempty result:

```sh theme={null}
atonom eval search-summary.lua \
  --transform '{"query":"acme"}' \
  --trap-result '{"hits":[{"title":"Acme"}]}' --json
```

Expect `DONE` with `value: {"ok":true,"count":1}`. The CLI consumes the supplied response when the script traps; it does not call a real search tool.

Test no results and a host failure:

```sh theme={null}
atonom eval search-summary.lua \
  --transform '{"query":"acme"}' --trap-result '{"hits":[]}' --json

atonom eval search-summary.lua \
  --transform '{"query":"acme"}' \
  --trap-result '{"ok":false,"error":"forbidden"}' --json
```

The host-failure case returns `{ok:false,error:"forbidden"}` as a normal value, so eval still exits `0`. The script deliberately handles the failure instead of throwing it.

## Result envelopes and multiple calls

Repeat `--trap-result` once for each call, in execution order. Results are positional, not matched by capability name.

A bare value is wrapped as `{"ok":true,"value":...}`. An object containing an `ok` key is treated as a complete host-result envelope. To return application data that itself has an `ok` field, wrap it explicitly:

```sh theme={null}
atonom eval -c 'return atonom.toolcall("example", {})' \
  --trap-result '{"ok":true,"value":{"ok":false,"reason":"not_ready"}}' --json
```

`--trap-echo` answers remaining traps by returning their arguments. Use it for plumbing checks, not as a substitute for realistic fixtures. The default maximum is **16 fulfilled traps**; adjust with `--max-traps N` only when the expected call sequence needs it.

No response, or exceeding the limit, exits `3`. Inspect `unanswered_trap`. After fixing the fixture or script, rerun eval from the beginning. Continuations are intentionally omitted from JSON output.

## Test the platform path

For a linked script whose diff has been reviewed:

```sh theme={null}
atonom push 42 --json
atonom run 42 --no-save --inputs-file fixtures/order.json --json
```

Create `fixtures/order.json` with a JSON object, for example `{"qty":2,"unit_price":12.5}`. `--inputs` and `--inputs-file` are mutually exclusive. Missing inputs default to `{}`.

`run --no-save` tests whatever is stored at execution time. Coordinate with other editors when exact-version validation matters. Live host capabilities may have side effects; choose appropriate development fixtures and tools.

## A useful test checklist

* Normal input produces the expected JSON shape and value.
* Missing fields and wrong types follow the intended error contract.
* Empty collections stay arrays when required.
* Host calls use the expected capability name and argument shape.
* Success, empty results, and host errors are covered.
* Repeated calls terminate and stay within resource limits.
* The stored version passes a platform test after sync.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.