Latest / Software Testing with Fexingo: QA, Automation, and Reliable Software Engineering / How to Test State Machines Without Getting Lost in Transitions
Transcript
- Lucas: So there's this moment in every QA engineer's life where a bug slips through, and you know it's not because you didn't test enough—it's because you tested the wrong way. Today I want to talk about state machines, and why they're the hidden culprit behind some of the most frustrating production bugs. Luna: State machines? You mean like, the vending machine diagrams from comp sci class? Lucas: Exactly. But they're everywhere in modern software. Think about a payment gateway. A user's transaction can be pending, authorized, captured, refunded, or voided. Each of those states has rules about what can happen next. And if you test it like it's a linear flow, you're going to miss the moments where reality takes a sharp turn. Luna: Give me a real example. What kind of bug are we talking about? Lucas: I remember a case from a few years ago—a subscription service. Users could start a free trial, and during that trial they could cancel, which moved the subscription into a 'cancelled' state. Seemed simple. But if the user cancelled and then immediately reactivated before the trial expired, the system would crash. The state machine had a transition from 'cancelled' to 'active' that was missing a guard—it didn't check if the trial was still valid. Luna: So the code allowed a transition that shouldn't have been possible. How would you catch that with tests? Lucas: The first step is to actually model your state machine explicitly. Draw it out, or write it down. List every state, every event that can trigger a transition, and every condition that must be true. Once you have that map, you can test each transition in isolation—not just the happy path, but every single edge case. Luna: Okay, so you're saying we should write a test for each arrow in the diagram? Lucas: Yes, and also for the arrows that don't exist. A lot of bugs come from illegal transitions being allowed. So you want a test that says, 'If I'm in state X and event Y happens, then the system should throw an error or ignore it.' Those negative tests are just as important as the positive ones. Luna: That makes sense. But how do you structure the code so those tests aren't a nightmare to maintain? Lucas: Good question. One approach is to use a table-driven test. You define all your states and transitions in a table, and then your test iterates over it. That way, when you add a new state, you just add a row. It keeps the test suite clean and makes it obvious what's covered. Luna: So you're trading a bit of boilerplate for a lot of clarity. Lucas: Exactly. And it forces you to think about the full matrix of possibilities. You start to ask questions like, 'What happens if the user cancels while the payment is still processing?' That's a race between two events, and without a clear state machine, it's easy to miss. Luna: Right. And I've seen systems where those races cause real chaos. It's not just about the happy path. Lucas: Now, a lot of teams rely on code coverage percentages to feel good about their tests. But with state machines, coverage is even more misleading. You can have 100 percent line coverage and still miss half the transitions. That's why I like to think in terms of transition coverage instead. Luna: Transition coverage—so you're counting the arrows you've tested, not the lines of code? Lucas: Exactly. You want to know that every possible transition has been exercised at least once, and ideally both the valid and invalid versions. There are tools that can help generate that matrix for you, but honestly, the act of writing it out by hand is where the value lies. It forces you to confront the complexity. Luna: What about unreachable states? I remember a project where we had a status that could never actually happen because of the way the code was written. But we didn't realize it until months later. Lucas: That's a great point. Unreachable states are a sign that your model is wrong, or that you've over-engineered the system. When you draw the state machine, you should be able to trace a path from the initial state to every other state. If you can't, that's a red flag. Sometimes it's harmless, but often it means there's a logical flaw. Luna: So you'd want a test that verifies which states are actually reachable? Lucas: Yes. If you have a state that you believe is reachable, write a test that gets there. If you can't, either the test is wrong or the state is dead code. Either way, you've learned something valuable. Luna: And what about hidden state? Sometimes the state isn't just a single variable—it's a combination of things, like a flag plus a timestamp. Lucas: That's where it gets tricky. A state machine model assumes that all the relevant information is captured in the state itself. If you have hidden state, like a timer that expires or a dependency on an external system, then your tests need to account for that. You might need to inject a fake clock or mock the external service to control those variables. Luna: So the model is an abstraction, but the tests have to deal with the messy reality. Lucas: Right. And that's why it's so important to keep the state machine logic isolated from the rest of the code. If you can extract it into a pure function or a class with no side effects, then testing becomes much easier. You can test the transitions directly without having to set up a whole environment. Luna: That sounds a lot like the way we preach about separating concerns in general. Lucas: It is. But it's especially critical for state machines because the logic is so branchy. If it's buried in a bunch of if-else statements, the tests become convoluted. When you have a clean state machine, you can write tests that read like a specification: 'Given state A, when event B occurs, the next state is C.' Luna: I'm thinking about a project I worked on for an IoT device. The device had a state machine for its connection status—connecting, connected, disconnected, reconnecting. And we had a bug where it would get stuck in 'reconnecting' if a specific error occurred. How would you approach that? Lucas: That's a classic. You'd want a test that forces that error and verifies that the device eventually transitions to a healthy state. But you also need to think about timeouts. If the reconnection attempt takes too long, does it go back to 'disconnected'? That's another transition that needs a test. Luna: So it's about covering the loop paths, not just the linear ones. Lucas: Exactly. Loops are where a lot of bugs hide. If you have a state machine that can loop back on itself, you need to test that the loop terminates eventually, and that each iteration doesn't degrade performance or corrupt state. Luna: Let's talk about testing frameworks for a second. Do you have a favorite way to structure these tests in practice? Lucas: I'm a fan of behavior-driven development style—given, when, then. It maps nicely to state machines. You can even use a library like XState for JavaScript, which lets you define state machines as data and provides a test utility that generates all the possible paths. But even without a library, the principle holds. Luna: So you can be language-agnostic about it. Lucas: Definitely. The hard part isn't the tooling; it's the thinking. You have to sit down and ask, 'What are all the states? What are all the events? What are the guards?' If you can answer those questions, the tests almost write themselves. Luna: And if you can't answer those questions, that's a signal that the code itself is too complex. Lucas: That's a great way to put it. Testing a state machine is really a way of validating your design. If the model is too complex to test, maybe the model is wrong. Sometimes you need to simplify the state machine itself, combine states, or change the events. Luna: I've found that state machines often hide in user interfaces too. Like a multi-step form with a back button—that's a state machine. Lucas: Absolutely. And those are some of the most user-facing state machines. If you get those wrong, people see it immediately. But they're also easy to test with the same approach. You just define the states as the steps, and the events as the user actions—submit, back, cancel. Luna: Have you ever come across a project where they actually used a state machine library, and it made a difference? Lucas: Yes, a fintech client of mine—they had a complex loan application process. They used a state machine library and it reduced their bug count significantly. But the key was that they also wrote tests for every transition, so when they added a new feature, they could be confident it wouldn't break existing flows. Luna: That's the kind of certainty you want in a financial system. Lucas: Right. And that brings me to something I think is worth saying: if today's conversation has given you a new way to think about testing, that's exactly what we're here for. And if you find value in these episodes, the way we keep them ad-free is through listener support. You can buy me a coffee at buy me a coffee dot com slash fexingo. It helps us keep going. Luna: Yeah, and it's a small way to say thanks for the insight. We appreciate it. Lucas: Now, let's get back to the nitty-gritty. One more pitfall I want to mention: testing state machines in isolation is great, but you also need integration tests to make sure the state machine plays well with the rest of the system. A transition might be correct in the unit test, but fail when the database is involved, or when there's a network call. Luna: So unit tests for the logic, integration tests for the boundaries. Lucas: Exactly. And for those integration tests, you want to use realistic data. That's something we've talked about before—test data diversity matters. But with state machines, you also need to test the transitions in the context of actual system state, like a row in a database with a specific status. Luna: That reminds me of a time when we forgot to update the state in the database after a successful transition. The in-memory state was correct, but the persisted state was stale. Lucas: Classic. That's why your integration tests should verify both the in-memory state and the persisted state. After a transition, you check that the database has the new status, and that any related records are updated. Luna: And what about concurrency? Two events happening at the same time can cause the state machine to behave unexpectedly. Lucas: We touched on that earlier with the payment race. Concurrency is a whole other beast. You might need to introduce locks or make the transitions atomic. But testing concurrent state machines is tricky because it's hard to reproduce the timing. That's where property-based testing can help—you throw random event sequences at the state machine and check that it never ends up in an invalid state. Luna: That sounds like a powerful tool to have in your arsenal. Lucas: It is. And it's a natural extension of the table-driven tests I mentioned earlier. You start with the deterministic tests, and then you add a layer of randomness to shake out the edge cases you didn't think of. Luna: So to wrap it up: draw the state machine, test each transition, include the illegal ones, watch out for hidden state, and use integration tests for the real world. Did I miss anything? Lucas: I'd add one more thing: don't forget to test the initial state and the final states. Sometimes people skip the edges of the diagram. But those are where the most critical invariants live—like 'a transaction can't be refunded before it's captured'. Luna: Good point. Those are the rules that make the system trustworthy. Lucas: So next time you're staring at a bug that only appears when someone does A, then B, then C—take a step back and ask if you're dealing with a state machine. If you are, you know exactly how to tackle it. Luna: And you'll have a test to prove it. Thanks, Lucas. Lucas: Thanks, Luna. That's all for today's episode. We'll be back with more testing wisdom soon.