Some bugs only appear at the boundary between states. An order that is in the "submitted" state behaves differently from one in "approved." A user who has just signed up behaves differently from one whose subscription has lapsed. State transition testing is the technique for systematically exercising these stateful behaviours — and finding the bugs that hide in transitions, not in any single state.
The basic idea
Any system with persistent state can be modelled as a finite state machine: a small set of named states, plus the events that move the system from one state to another. Drawing the model — even quickly on a whiteboard — makes it possible to test every state and every transition explicitly.
Consider a typical e-commerce order. The states might be:
- Draft — items in cart, not yet submitted.
- Submitted — payment captured, awaiting fulfilment.
- Approved — fraud check passed, ready to ship.
- Shipped — left the warehouse.
- Delivered — confirmed by the carrier.
- Cancelled — user or system cancelled before shipping.
- Refunded — money returned after delivery.
The transitions between them are not arbitrary. You cannot go from Draft directly to Delivered. You cannot Refund an order that is still Draft. The model captures these rules.
What to test
A complete state-transition test plan covers four things:
- Each state. Verify the system behaves correctly in every state. (Can a Draft order be edited? Can a Shipped order's address be changed?)
- Each valid transition. Verify every legal transition fires correctly. (Submitted → Approved on fraud check pass; Submitted → Cancelled on fraud check fail.)
- Each invalid transition. Verify illegal transitions are blocked. (Refunded → Shipped should fail; Delivered → Submitted should fail.)
- Each transition's side effects. Each transition is usually accompanied by side effects — emails sent, inventory adjusted, audit logs written. Verify those happen exactly when they should and not otherwise.
Item 3 is where the most bugs hide. Developers often handle valid transitions correctly but forget to block invalid ones, leaving "back-door" paths that can corrupt data.
A common failure mode
Imagine a developer adds a "Cancel order" button to the customer's order page. They wire it up to set the order's state to Cancelled. They test it manually with a fresh order. It works. They ship.
Two weeks later a customer cancels an order that has already shipped. The state changes to Cancelled, but the inventory was already decremented, the carrier already has the package, and now the system thinks the order is cancelled while the package is in transit.
A state transition test plan would have caught this: rule 3 says "test that Cancel fails when the order is in Shipped." The bug exists because the developer only tested valid transitions, not invalid ones.
Drawing the diagram
The fastest way to start is on paper or a whiteboard. Draw a circle for each state and an arrow for each transition. Label the arrow with the event that triggers it. Within minutes you will spot:
- States the spec did not name.
- Transitions the spec did not define.
- Transitions that "obviously" should not exist but technically still can.
Bring the diagram to a refinement meeting. Watch how quickly the team starts arguing about specific transitions. Those arguments are exactly the requirement gaps the diagram is meant to surface.
Beyond simple state machines
Real systems often have more nuance:
- Composite states. A "Shipped" state might internally have sub-states like "In transit" and "Out for delivery."
- Concurrent states. An order can be both "Awaiting payment" and "Awaiting fraud check" at once.
- Guards. A transition is only valid if some condition is true (e.g. Submitted → Approved only if fraud-score < 0.5).
- Time-based transitions. A Cart sitting idle for 24 hours auto-transitions to Abandoned.
For these, plain state diagrams stretch but still help. Some teams use UML statecharts; most stick with simpler notations and accept some imprecision.
State testing in automation
Automated state transition tests usually take this shape: set up an entity in a known state (often via direct database insert or an internal API), trigger the event, assert the new state is correct and the side effects fired. They are typically integration tests, not unit tests, because they exercise the persistence layer and any side effects.
Make sure your test framework can put the system into a state directly — clicking through the UI to recreate state for every test will turn a 30-second test into a 5-minute one and produce a slow, brittle suite.
What you should walk away with
State transition testing is the technique for stateful features. Draw the diagram, test every state, every valid transition, and especially every invalid transition. The next lesson — error guessing and exploratory heuristics — moves into less formal territory, where experience and pattern recognition take the lead.