Testing workflows

Once you've built your workflow, you'll want to test it to make sure it works as expected. Knock provides a number of tools to help you test your workflows.

You can use the Knock workflow test runner to test an end-to-end workflow or a single channel step, and verify that it works as expected.

To use the workflow test runner, navigate to the workflow you want to test and click "Run a test." You'll have options to select the workflow's recipient, actor, tenant, and input any data that you'd like to pass to the workflow.

Two things to know about workflow test configuration:

• The recipient and actor fields can contain either a user or an object. Use the toggle above the field to switch between these options.
• The data field starts with the data your workflow's templates reference, and refreshes when those references change. Click the reset button to clear it. See editing test data below.

After clicking "Run test," you'll see a confirmation with a link to review what your test ran and sent. Learn more about debugging workflows.

Note that trigger frequency is not enforced during test runs. Settings like "once per recipient" are bypassed — each time you run a test, the workflow will execute for the selected recipient regardless of your frequency setting. To validate trigger frequency as it behaves in production, use the trigger API.

You can also use the workflow test runner to run a test payload for a source event trigger. If your workflow is triggered by an event, you will automatically see a JSON payload of the last received event that you can use to run a test. You can edit this payload or click "Fetch latest event" to get the most recent from your source. After the test, "View event run" opens the source event log.

The data field has two views, which you can switch between with the "Visual" and "JSON" toggle:

• Visual. Each top-level key in your data is its own field. If your workflow has a trigger data schema, the fields it defines are listed first under "Expected fields," with required fields marked with an asterisk. Any other keys appear under "Additional data." Nested objects and arrays open as collapsible sections. Click "Add field" to add a key.
• JSON. The raw JSON payload, for pasting or editing data in bulk.

If your workflow doesn't have a trigger data schema yet, click "Validate incoming data" to create one without leaving the test runner. The schema editor uses your current test data as the starting point when you click "Generate schema." Once a schema exists, click the edit icon next to "Expected fields" to change it. Like other workflow changes, schema changes need to be committed before they apply to API triggers.

To reproduce a workflow run, open it in the workflow debugger and click "Open in test runner" in the "Workflow trigger" section. The workflow opens in a new tab with the test runner prefilled with the run's recipient, actor, tenant, and data, which you can edit before running the test.

The test runner includes a few settings that control how the workflow executes during a test run:

• Sandbox mode. When enabled, all messages sent from the workflow are forced to send in sandbox mode. Knock generates and previews the messages without delivering them to the underlying providers, regardless of how sandbox mode is configured on each channel. This is useful for testing a workflow end-to-end without sending real notifications to your recipients.
• Skip delays. When enabled, all delay steps in the workflow are force skipped. The workflow runs straight through without waiting, which lets you verify the full execution path without waiting for delays to elapse.

You can also apply both of these settings when triggering a workflow via the API using the settings.sandbox_mode and settings.skip_delay properties, which is useful when testing workflows programmatically.

You can also use the test runner to run a single channel step instead of the full workflow. This is useful when you're iterating on one message that sits behind delays, branches, or conditions.

To test a single step, click "Run a test," select "One step," and choose the step from the dropdown. Then click "Run step test." When you open the test runner from a step's template editor, "One step" is already selected with that step chosen.

Only the selected step runs, so if your step's template references data that an earlier step produces (such as a fetch response), add that data to the "Data" field for your test. Once your test is complete, the workflow debugger will show any other workflow steps that didn't run as "Not started."

Channel-level conditions, recipient preferences, and send windows apply during a single-step test, but the step's own conditions are ignored.

You can run any channel step that sends a message on its own. Function steps and in-app guide steps run only as part of a full workflow test. Fetch and AI agent functions have their own test runner in the template editor. Learn more about testing fetch functions and testing AI agent functions.

You can also run a single step through the Management API by passing a step_id to the run workflow endpoint.

You can also generate workflow runs using the workflow run command from the Knock CLI. You can learn more in our CLI reference.