Simulating Workflows

Workflow simulation is a local execution environment that compiles your workflow to WebAssembly (WASM) and runs it on your machine. It allows you to test and debug your workflow logic before deploying it. The simulator makes real calls to public testnets and live HTTP endpoints, giving you high confidence that your code will work as expected when deployed.

When to use simulation

Use workflow simulation to:

  • Test workflow logic during development: Validate that your code behaves correctly before deploying.
  • Debug errors in a controlled environment: Catch and fix issues locally without deploying to a live network.
  • Test different trigger types: Manually select and test how your workflow responds to cron, HTTP, or EVM log triggers.
  • Verify onchain interactions: Test read and write operations against real testnets.

Basic usage

The cre workflow simulate command compiles your workflow and executes it locally.

Basic syntax:

cre workflow simulate <workflow-name-or-path> [flags]

Example:

cre workflow simulate my-workflow --target staging-settings

What happens during simulation

  1. Compilation: The CLI compiles your workflow to WebAssembly (WASM).
  2. Trigger selection: You're prompted to select which trigger to test (cron, HTTP, or EVM log).
  3. Execution: The workflow runs locally, making real calls to configured RPCs and HTTP endpoints.
  4. Output: The simulator displays logs from your workflow and the final execution result.

Prerequisites

Before running a simulation:

  • CRE account & authentication: You must have a CRE account and be logged in with the CLI. See Create your account and Log in with the CLI for instructions.
  • CRE CLI installed: You must have the CRE CLI installed on your machine. See CLI Installation for instructions.
  • Project configuration: You must run the command from your project root directory.
  • Valid workflow.yaml: Your workflow directory must contain a workflow.yaml file with correct paths to your workflow code, config, and secrets (optional).
  • RPC URLs configured: If your workflow interacts with blockchains, configure RPC endpoints in your project.yaml for the target you're using. Without this, the simulator cannot register the EVM capability and your workflow will fail. See Project Configuration for setup instructions.
  • Private key: Set CRE_ETH_PRIVATE_KEY in your .env file if your workflow performs onchain writes.

Interactive vs non-interactive modes

Interactive mode (default)

In interactive mode, the simulator prompts you to select a trigger and provide necessary inputs.

Example:

cre workflow simulate my-workflow --target staging-settings

What you'll see:

Workflow compiled

🚀 Workflow simulation ready. Please select a trigger:
1. [email protected] Trigger
2. [email protected] Trigger
3. evm:ChainSelector:[email protected] LogTrigger

Enter your choice (1-3):

Select a trigger by entering its number, and follow any additional prompts for trigger-specific inputs.

Non-interactive mode

Non-interactive mode allows you to run simulations without prompts, making it ideal for CI/CD pipelines or automated testing.

Requirements:

  • Use the --non-interactive flag
  • Specify --trigger-index (0-based index of the trigger to run)
  • Provide trigger-specific flags as needed (see Trigger-specific configuration)

Example:

cre workflow simulate my-workflow --non-interactive --trigger-index 0 --target staging-settings

The --broadcast flag

By default, the simulator performs a dry run for onchain write operations. It prepares the transaction but does not broadcast it to the blockchain.

To actually broadcast transactions during simulation, use the --broadcast flag:

cre workflow simulate my-workflow --broadcast --target staging-settings

Use case: Use --broadcast when you want to test the complete end-to-end flow, including actual onchain state changes, on a testnet.

Trigger-specific configuration

Different trigger types require different inputs for simulation.

Cron trigger

Cron triggers do not require additional configuration. When selected, they execute immediately.

Interactive example:

cre workflow simulate my-workflow --target staging-settings

Select the cron trigger when prompted (if multiple triggers are defined)

Non-interactive example:

# Assuming the cron trigger is the first trigger defined in your workflow (index 0)
cre workflow simulate my-workflow --non-interactive --trigger-index 0 --target staging-settings

HTTP trigger

HTTP triggers require a JSON payload.

Interactive mode:

When you select an HTTP trigger, the simulator prompts you to provide JSON input. You can:

  • Enter the JSON directly
  • Provide a file path (e.g., ./payload.json)

Non-interactive mode:

Use the --http-payload flag with:

  • A JSON string: --http-payload '{"key":"value"}'
  • A file path: --http-payload @./payload.json (with or without @ prefix)

Example:

cre workflow simulate my-workflow --non-interactive --trigger-index 1 --http-payload @./http_trigger_payload.json --target staging-settings

EVM log trigger

EVM log triggers require a transaction hash and event index to fetch a specific log event from the blockchain.

Interactive mode:

When you select an EVM log trigger, the simulator prompts you for:

  1. Transaction hash (e.g., 0x420721d7d00130a03c5b525b2dbfd42550906ddb3075e8377f9bb5d1a5992f8e)
  2. Event index (0-based index of the log in the transaction, e.g., 0)

The simulator fetches the log from the configured RPC and passes it to your workflow.

Non-interactive mode:

Use the --evm-tx-hash and --evm-event-index flags:

cre workflow simulate my-workflow \
  --non-interactive \
  --trigger-index 2 \
  --evm-tx-hash 0x420721d7d00130a03c5b525b2dbfd42550906ddb3075e8377f9bb5d1a5992f8e \
  --evm-event-index 0 \
  --target staging-settings

Additional flags

--engine-logs (-g)

Enables detailed engine logging for debugging purposes. This shows internal logs from the workflow execution engine.

cre workflow simulate my-workflow --engine-logs --target staging-settings

--target (-T)

Specifies which target environment to use from your configuration files. This determines which RPC URLs, settings, and secrets are loaded.

cre workflow simulate my-workflow --target staging-settings

--verbose (-v)

Enables debug-level logging for the CLI itself (not the workflow). Useful for troubleshooting CLI issues.

cre workflow simulate my-workflow --verbose --target staging-settings

Understanding the output

When you run a simulation, you'll see the following output:

1. Compilation confirmation

Workflow compiled

This indicates your workflow was successfully compiled to WASM.

2. Trigger selection menu (interactive mode only)

If your workflow has multiple triggers, you'll see a menu:

🚀 Workflow simulation ready. Please select a trigger:
1. [email protected] Trigger
2. [email protected] Trigger
3. evm:ChainSelector:[email protected] LogTrigger

Enter your choice (1-3):

If your workflow has only one trigger, it will run automatically without this prompt.

3. User logs

Logs from your workflow code (e.g., logger.Info() calls) appear with timestamps:

2025-10-24T19:07:27Z [USER LOG] Running CronTrigger
2025-10-24T19:07:27Z [USER LOG] fetching por url https://api.example.com
2025-10-24T19:07:27Z [USER LOG] ReserveInfo { "totalReserve": 494515082.75 }

4. Final execution result

The simulator displays the value returned by your workflow:

Workflow Simulation Result:
 {
  "result": 47
}

5. Transaction details (if your workflow writes onchain)

If your workflow performs onchain writes, the simulator will show transaction information:

Without --broadcast (dry run):

The transaction is prepared but not sent. You'll see a zero address (0x0000...) as the transaction hash:

2025-10-24T23:01:50Z [USER LOG] Write report transaction succeeded: 0x0000000000000000000000000000000000000000000000000000000000000000

With --broadcast:

The transaction is actually sent to the blockchain. You'll see a real transaction hash:

2025-10-24T17:55:48Z [USER LOG] Write report transaction succeeded: 0x1013abc0b6f345fad15b19a56cabbbaab2a2aa94f81eb3a709058adf18a4f23f

Limitations

While simulation provides high confidence in your workflow's behavior, it has some limitations:

  • Single-node execution: Simulation runs on a single node (your local machine) rather than across a DON. There is no actual consensus or quorum, it is simulated.
  • Manual trigger execution: Time-based triggers (cron) execute immediately when selected, not on a schedule. You must manually initiate each simulation run.
  • Simplified environment: The simulation environment mimics production but is not identical. Some edge cases or network conditions may only appear in a deployed environment.

Despite these limitations, simulation is an essential tool for catching bugs, validating logic, and testing integrations before deploying to production.

Next steps

Get the latest Chainlink content straight to your inbox.