Custom workflows let you define the lifecycle states that test cases, test runs, and exploratory sessions move through in your projects. Testmo ships with a standard set of states for each of these entities, but you can add, edit, reorder, and remove states to match exactly how your team works.
Workflow configuration is available to administrators at Admin > Workflows.
How workflow states work
Each of Testmo's three manual testing entities has its own independent set of workflow states:
- Repository states apply to test cases in the test case repository.
- Runs states apply to manual test runs.
- Sessions states apply to exploratory test sessions.
States are displayed as colored icons throughout the product wherever a test case, run, or session appears. Users can manually assign any active state to a record, and certain transitions can also happen automatically based on workflow settings (see Workflow settings below).
Every entity must have exactly one default state. The default state is assigned automatically when a new record is created and is also used as the fallback when a state is deleted.
Workflow settings
Each entity type has a Workflow settings button at the top of its workflow page. These settings control automatic state transitions and default filtering behavior.
Repository settings
The repository settings dialog ("Settings for cases") controls which test case states are included when adding cases to a new run.
The setting "Only include cases with the following states in new runs by default:" lets you select one or more states from a checklist. When a user creates a new run, only test cases currently in one of the selected states will be added by default. If you leave this list empty, test cases in any state are included.
This is useful when your repository contains cases in multiple lifecycle stages and you want runs to automatically exclude drafts, rejected cases, or retired cases without requiring users to manually filter each time.
Runs settings
The runs settings dialog ("Settings for runs") configures automatic state transitions triggered by user activity:
- When the first note or result is added — the state to assign automatically when a run receives its first entry. Defaults to In progress.
- When a run is closed — the state to assign automatically when a run is closed. Defaults to Done.
Either field can be left empty to disable that automatic transition.
Sessions settings
The sessions settings dialog ("Settings for sessions") works the same way as runs settings, but for exploratory sessions:
- When the first note or result is added — defaults to In progress.
- When a session is closed — defaults to Done.
Automatic transitions reduce the need for users to manually update states at predictable moments in the workflow, keeping state data consistent without adding friction.
Creating states
To add a new state, select the entity tab (Repository, Runs, or Sessions) and click the State button. The "Add state" dialog has two tabs.
State tab
- Name — The display name shown throughout the product. Required.
- Select icon — An icon picker where you choose an icon to represent the state. A row of suggested icons is shown below the picker for quick selection. You can also enter any valid icon name directly.
- Color — An optional 6-digit hex color code applied as an overlay on the icon. When left blank, the icon uses its default color.
Choosing a distinct color for each state makes it easy to identify where a record sits in the lifecycle at a glance, particularly in list views and reports where many records appear together.
Projects tab
The Projects tab controls which projects the state is available in.
- This state applies to all projects — the state appears in every current and future project. This is the default selection.
- This state applies to the following projects only: — selecting this option reveals a project list where you can choose one or more specific projects.
Scoping states to specific projects is useful when different teams or products have meaningfully different testing processes. For example, a hardware project might need a Hardware validation state that has no relevance to software-only projects.
Editing states
Click the edit icon on any state row to open the "Edit state" dialog. All fields from the creation dialog are available, with one exception: the Enabled and project scope controls are disabled for the default state, since the default state must always apply to all projects and remain enabled.
Managing states from the state table
The state table on each workflow page offers several inline controls in addition to the edit action.
- Reordering — States can be dragged into any order using the handle on the left of each row. The display order in the table is the order states appear in dropdowns and pickers throughout the product.
- Enabled toggle — Each state has an enabled/disabled toggle. Disabling a state hides it from dropdowns when users assign states, but records already in that state are not affected. This is useful for phasing out a state you no longer want new records to enter without disrupting existing data.
- Default toggle — Clicking the Default toggle for a non-default state shows a confirmation prompt. On confirmation, that state becomes the new default for the entity. The previous default loses its default designation but remains active. Only one state per entity can be the default at any time.
- Deleting a state — Click the delete icon on a state row to remove it. Before deleting, Testmo warns that all records currently in that state will be automatically reassigned to the default state. The delete option is not available for the default state.
Use cases and examples
Modeling a review gate before runs: If your process requires test cases to be reviewed and approved before they are included in a test cycle, you can use repository states to enforce this. Keep Draft for cases being written, add a custom Approved state for reviewed cases, and configure repository settings to only include Approved cases in new runs by default. Writers work in Draft; leads promote cases to Approved when they are ready.
Tracking sign-off on completed runs: Runs and sessions default to Done when closed, but if your process requires a separate sign-off step, you can add a Pending sign-off state and configure runs not to auto-transition on close. After a run is closed, a lead manually sets it to Done once they have reviewed results, giving the state a clear meaning beyond just "closed."
Scoping states to teams: If one team uses a Blocked state for runs waiting on an external dependency, but other teams find the state confusing and irrelevant, you can restrict that state to the relevant projects rather than showing it globally. Teams that do not need it never see it in their dropdowns.
Phasing out an old state: If you rename a lifecycle stage or consolidate two states into one, you can disable the old state instead of deleting it. Records already in that state retain it for historical accuracy, but no new records can be assigned the disabled state. This is preferable to deletion when you want to preserve the meaning of historical data.