Skip to main content
A workflow that fires when it should not is worse than one that never fires: it pages people at 3am for a demo, posts to a customer-facing channel during a rehearsal, or files tickets nobody asked for. Test before you enable.

​
Start Here: What a Test Incident Actually Isolates

/rootly test declares a Test Incident. It is the right tool, but its isolation is narrower than the name suggests.
Test incidents trigger workflows, and those workflows take real actions.A test incident is kept out of your metrics, and off your Rootly status pages — it is not shown there and subscribers are not notified. A status page update published for it still syncs to Statuspage.io if the page is connected to one. It is not isolated from the outside world. A workflow that pages on-call will page a real person. One that posts to Slack really posts. One that calls an HTTP endpoint really calls it, and one that files a Jira ticket really files it.The word “test” describes the incident’s accounting, not its scope of impact.
This is why the first thing to get right is not the workflow you are testing — it is every other workflow that will also see your test incident.

​
Before You Test: Guard the Production Workflows

New workflows start with the condition Kind is: Incident, which keeps test incidents out. A workflow fires on a test incident only when that condition has been removed or widened, so check every workflow that pages or notifies people for a Kind condition. Without one, your test fires them.
Use Kind is one of: Incident, Sub Incident when the workflow should also fire on sub-incidents — which is most notification workflows, since a sub-incident is still a real incident someone needs to hear about. Kind is: Incident alone silently excludes them. Prefer either positive form to an exclusion list. Kind is none of: Test / Training Incident, Sub Test / Training Incident, … breaks silently the next time a new kind is added; naming the kinds you want keeps working. See Conditions for the full recipe and Incident Kind for every kind and what each triggers.
Do this once, across your paging and notification workflows, rather than per test. It is the difference between testing being routine and testing being an event that requires warning people first.

​
Rehearsing a Workflow

1

Build it disabled

A disabled workflow does not run automatically from events. Build and save it disabled so a matching event during authoring cannot fire a half-finished workflow. You will enable it before the manual run below — disabled is for authoring, not for testing. See the Enabled setting on Workflows.
2

Narrow the actions first

If the workflow will eventually page someone or post publicly, point those actions somewhere harmless for the rehearsal — your own user, a scratch channel — and widen them once the logic is right. Testing the logic and testing the delivery at the same time makes a failure ambiguous.
3

Declare a test incident

Run /rootly test. The manual run in the next step executes the workflow’s actions without evaluating its run conditions, so this rehearsal tests the actions, not the conditions — see Testing Conditions Specifically.
4

Enable it, then run it manually

A manual run only reaches enabled workflows — the trigger button lists and executes enabled ones only, so a workflow left disabled is silently skipped rather than refused. Enable it now, with the actions still pointed somewhere harmless and the conditions still narrow.Then trigger it against that incident from the web UI. A manual run executes immediately for that specific incident, which is what lets you test a workflow whose real trigger is awkward to produce. See Manually Running Workflows.
Some organizations require a workflow to carry the Slack Command trigger before it can be run manually. If your workflow does not appear in the trigger list, that is why — add the trigger, or produce the real event instead.
5

Read what happened

Check the workflow’s run, the incident timeline, and wherever the actions were meant to land. By default an action that failed halts the run and later actions do not execute, so a workflow that appears to have done nothing may have failed at step one. An action with Skip on Failure enabled is the exception — the run continues past it, which is worth knowing before you conclude a later action never fired.
6

Widen it, then watch the first real run

Point the actions at their real targets and open the conditions up. Conditions that pass on a test incident you constructed do not always pass on a real one, so the first production firing is part of the test.

​
Testing Conditions Specifically

Most workflow bugs are condition bugs — it fired when it should not have, or did not fire when it should. Run conditions are evaluated only when a trigger event fires the workflow; a manual run skips them. To exercise them with a test incident, temporarily add Test / Training Incident to the workflow’s Kind condition, then produce the trigger event — declaring the test incident is enough for an Incident Created trigger. Give each test incident the attributes your conditions read, such as severity, services, and environment. Test both directions. Declaring one test incident that matches proves the workflow can fire; it does not prove the workflow is selective. Declare a second that should not match, and confirm nothing happened. A condition that is broader than intended looks identical to a correct one until something it should have excluded comes along.
The workflow editor shows each Kind by its label, such as Sub Test / Training Incident. The API and audit-log payloads use the identifier underneath, test_sub, so use identifiers when you define a workflow through the API or Terraform.

​
When You Are Done

  • Resolve or cancel the test incidents. They are excluded from metrics, but an open test incident still appears in lists and still has an active lifecycle.
  • Restore any actions you narrowed for the rehearsal, and remove Test / Training Incident from the Kind condition if you added it.
  • Consider locking the workflow once it matters. Locking restricts edits to Admins and Owners, which protects a tested workflow from a well-meaning tweak that is never tested.

Conditions

Condition recipes, including the Kind guard this page depends on.

Manual Runs

Running a workflow on demand from Slack or the web UI.

Incident Kind

Every kind and what each one triggers.