> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Test a workflow offline
> Run a workflow's graph on your machine with faked agent steps and pre-answered approvals, then gate CI on it
After this guide, you run a workflow end to end on your machine, force each branch of its graph, and fail a CI job when a step breaks. Use it before every `lua push workflow`; for the real model and real approvers, [start a run on the platform](/build/workflows/operate-runs) instead.
*Verified against lua-cli 3.33.0.*
**Before you begin**
* A project with a [workflow](/concepts/workflows) listed under `workflows` on its `LuaAgent`. Only listed workflows are compiled.
* Signed in with `lua auth configure`. Code steps run with your credential, so a step that calls `Data`, `AI`, or `Channels` reaches the platform.
`lua test workflow` compiles the project without registering anything on the server and drives the graph in one process. Code steps run for real, agent steps return a fake reply, and approvals are answered from flags.
```bash theme={null}
lua test --ci workflow --name lead-outreach --input '{"leadId":"lead_abc123"}' --approve reviewDraft
```
```text Output theme={null}
๐ฆ Compiling code first...
๐จ Compiling...๐ Syncing YAML with manifest...โน๏ธ Server sync skipped โ nothing was sent to the server; `lua push` publishes.
โ
Compiled 4 primitives (1 agent, 1 trigger, 1 job, 1 workflow) in 540ms
๐งญ Running workflow locally: lead-outreach
[17:48:11] run local-1789235291603 ยท 4 planned step(s)
[17:48:11] loadLead ยท log ยท loading lead_abc123
[17:48:11] loadLead ยท completed
[17:48:11] draftEmail ยท completed
[17:48:11] reviewDraft ยท completed
[17:48:11] recordSend ยท completed
[17:48:11] run ยท completed
Workflow returned: Object โ fields: sent
Output:
{ sent: true }
โฆ
```
An agent step with an `outputSchema` returns an object shaped from the schema (strings `''`, numbers `0`, booleans `false`); without one it returns `{ text: '[fake:] ' }`. `--deny ` answers an approval with `approved: false` and `--signal ` supplies a `waitForSignal` payload. Tool steps and nested workflows cannot run offline: give them an output with `--step-output`.
A fake reply never satisfies a predicate, so complete the step the predicate reads with the output you want; the value is validated against the step's `outputSchema` before anything runs.
```bash theme={null}
lua test --ci workflow --name ticket-followup --input '{"ticketId":"TCK-1"}' \
--step-output 'loadTicket={"id":"TCK-1","priority":"high","text":"Checkout fails on Safari"}'
```
```text Output theme={null}
๐งญ Running workflow locally: ticket-followup
[17:53:49] run local-1789235629551 ยท 7 planned step(s)
[17:53:49] loadTicket ยท step-output supplied โ execute skipped
[17:53:49] loadTicket ยท completed
[17:53:49] summarise ยท completed
[17:53:49] conditional@2 ยท completed
[17:53:49] escalate ยท completed
[17:53:49] conditional@2.join ยท completed
[17:53:49] shape ยท completed
[17:53:49] record ยท completed
[17:53:49] run ยท completed
โฆ
```
With `"priority":"low"` the `escalate` line reads `skipped`. A value that does not match the schema stops before the run starts, with exit 2 and a line such as `step-output-schema --step-output draftEmail: $.subject: required; $.body: required; $.nope: not allowed`. The flag repeats and takes `@file`.
`--park ` stands in for a platform fault on that step. Offline the run cannot wait for a person, so it fails with exit 4 after printing what the platform would do.
```bash theme={null}
lua test --ci workflow --name lead-outreach --input '{"leadId":"lead_abc123"}' --deny reviewDraft --park loadLead
```
```text Output theme={null}
๐งญ Running workflow locally: lead-outreach
[17:49:45] run local-1789235385061 ยท 4 planned step(s)
[park:loadLead] EFFECT_IN_DOUBT โ the run would park here (lua workflows retry-step, or a desktop decision); offline it fails
[17:49:45] loadLead ยท failed ยท EFFECT_IN_DOUBT: --park loadLead: simulated platform-fault reclaim
[17:49:45] draftEmail ยท skipped
[17:49:45] reviewDraft ยท skipped
[17:49:45] recordSend ยท skipped
[17:49:45] run ยท failed ยท EFFECT_IN_DOUBT: --park loadLead: simulated platform-fault reclaim
โ Workflow failed: EFFECT_IN_DOUBT --park loadLead: simulated platform-fault reclaim
at step "loadLead"
```
On a terminal the driver offers `retry`, `skip`, `complete`, or `fail` instead. A step that throws is retried under its `retry` policy and prints ` ยท retry ยท attempt 2/3`; `--fast-retries` collapses the backoff waits. Sleeps and deadlines run on a virtual clock, and `--now ` sets its start, so a business-hours escalation needs no waiting.
To re-drive only what did not finish, seed the ledger from a platform run: each completed step whose upstream steps are also seeded keeps its output and `once()` effects, and the driver starts at the first pending step.
```bash theme={null}
lua test --ci workflow --name lead-outreach --input @lead.json --approve reviewDraft --from-run
```
The driver prints `[from-run] step(s) seeded from ` before the timeline. A run that does not exist exits 3.
`--agents live` sends each agent step to your agent through the platform. `--record` writes each live reply as a fixture (tool steps never run offline, so nothing else is recorded); `--fixtures` replays them without a model in the loop.
```bash theme={null}
lua test --ci workflow --name lead-outreach --input @lead.json --approve reviewDraft --agents live --record ./fixtures
lua test --ci workflow --name lead-outreach --input @lead.json --approve reviewDraft --fixtures ./fixtures
```
A fixture is `/..json` holding `{ input, output, ms }`; only `output` is replayed, and a step without one fails the run with exit 5:
```text Output theme={null}
โ Workflow failed: FIXTURE_MISSING FIXTURE_MISSING: no fixture for step "draftEmail" attempt 1 (fixtures/draftEmail.1.json)
at step "draftEmail"
```
In CI, stdin is not a terminal, so anything left unanswered ends the run with exit 2 and a line such as `APPROVAL_UNANSWERED approval "reviewDraft" needs --approve/--deny reviewDraft (no interactive stdin)`. `--ci` makes a prompt on a developer's terminal fail instead of waiting.
```bash theme={null}
set -e
lua compile --ci
lua test --ci workflow --name lead-outreach --input @test/lead.json --approve reviewDraft \
--step-output 'draftEmail={"subject":"Quick intro","body":"Hello Ada"}' --json --ledger-out ledger.json > approved.json
lua test --ci workflow --name lead-outreach --input @test/lead.json --deny reviewDraft --json > denied.json
```
`--json` prints one document on stdout, `{ "success": true, "data": { "status", "output", "exitCode", "ledger" } }`, sends the compile lines to stderr, and prints no timeline. The exit code is the verdict:
| Code | When |
| ---- | ---------------------------------------------------------------------------------------------------- |
| `0` | The run completed |
| `2` | A flag, input, or `--step-output` failed validation; an approval, signal, or resume was not answered |
| `3` | No workflow with that name; no workflows compiled; `--from-run` run not found |
| `4` | A step failed past its retries, or the run output failed `outputSchema` |
| `5` | A fixture is missing under `--fixtures` |
## Options you may need
### `lua workflows run` and `--env`
`lua workflows run ` is the same driver with every flag on this page plus `--env KEY=value`, a local overlay for `env.template('KEY')` placeholders; a placeholder with no value exits 2 with `env-template-missing`, and the values never reach the ledger.
### Job-tier steps
A step with `tier: 'job'` gets `ctx.workspace`, `ctx.exec`, and `ctx.$` only with `--workspace `, the checkout to run in; `--job-wall ` fakes a long coding turn as 14,400-second segments. See [Use the Job tier](/build/workflows/job-tier).
### The ledger
`--ledger-out ` writes the run as JSON: `runId`, `workflowId`, `graphHash`, `status`, `input`, `steps`, `state`, `effects` (settled `once()` results), `events`, and `output`. `--artefacts-dir ` backs `ctx.artefacts` on disk; without it, `put` and `get` throw.
## If it isn't working
A `toolStep` has no offline executor. Supply its output with `--step-output =` or a fixture; a nested `.workflow()` step reports `SUBRUN_NOT_SUPPORTED_OFFLINE` and takes the same fix.
A Job-tier step called `ctx.exec` or `ctx.$` without `--workspace `. Pass the directory the step should run in.
A step called `ctx.suspend()` and no terminal was attached to type its `resumeData`. Run the command in a terminal without `--ci`, or complete the step with `--step-output =`.
## Next steps
Start, watch, approve, and repair runs on the platform.
Every workflow flag and its default.
Exit codes, `--ci`, and the JSON envelope across the CLI.
Bindings, predicates, retries, and the script form.