Test & mock 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 before using eval. If your setup does not include a sandbox, go to Test the platform path.

Run a chunk or a transform

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. 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:

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:

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:

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:

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:

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.

Get Started

Webhooks

Identity Management

Integrations

Prompting

Atonom Script

Support

Test & mock tool calls

Run a chunk or a transform

Mock a host call

Result envelopes and multiple calls

Test the platform path

A useful test checklist

​Run a chunk or a transform

​Mock a host call

​Result envelopes and multiple calls

​Test the platform path

​A useful test checklist

Run a chunk or a transform

Mock a host call

Result envelopes and multiple calls

Test the platform path

A useful test checklist