Verifying FSM State Transitions

1. The Philosophy of Testing

In programming, testing isn't just about running your code to see if it crashes. It's a systematic process of proving that your code behaves exactly as you intended under various conditions. A good test script doesn't just check the "happy path" where everything goes right; it also deliberately tries to break things to ensure your code handles errors gracefully.

We'll follow a simple but powerful pattern for our tests known as Arrange, Act, Assert:

1. Arrange: Set up the initial conditions for your test. This involves creating an instance of your FSM, defining its states, and setting up its transition rules.
2. Act: Perform the specific action you want to test. In our case, this will almost always be a call to FSM:transitionTo().
3. Assert: Check if the outcome of the action matches your expectation. Did the state change correctly? Did it correctly refuse to change? We'll use print() statements and check the output console to verify our results.

2. Setting Up the Test Script

Let's start by creating the environment for our test.

1. In the Roblox Explorer, navigate to ServerScriptService.
2. Create a new Script and name it FSM_Test.
3. Ensure this script is a sibling of your FSM ModuleScript, or adjust the path accordingly.

Inside FSM_Test, the first thing we need to do is get access to our module using require().

-- In FSM_Test Script

-- Arrange: Get the module we want to test
local FSM = require(script.Parent.FSM)

print("FSM Module loaded. Beginning tests...")

This simple setup is the foundation for any script that uses your module.

3. Writing Test Cases

We will use a simple "light switch" as the subject for our test. It's a classic example because its states (On, Off) and transitions (FlickOn, FlickOff) are universally understood.

Test Case 1: A Valid Transition

Let's test the most basic functionality: a simple, permitted transition from Off to On.

Arrange: We create a new FSM, define On and Off states with enter callbacks that print to the console, and define a transition from Off to On.

Act: We call transitionTo("On").

Assert: We expect to see the "Entering On" message and confirm the final state is On.

-- In FSM_Test Script, after requiring the module

-- ARRANGE
local lightSwitch = FSM.new("Off") -- Start in the "Off" state

lightSwitch:defineState("Off", {
    enter = function(prevState) print(" -> Light is now Off. Came from: " .. tostring(prevState)) end,
    exit = function(nextState) print(" <- Exiting Off. Going to: " .. nextState) end
})

lightSwitch:defineState("On", {
    enter = function(prevState) print(" -> Light is now On. Came from: " .. prevState) end,
    exit = function(nextState) print(" <- Exiting On. Going to: " .. nextState) end
})

lightSwitch:defineTransitions({
    { from = "Off", to = "On" },
    { from = "On", to = "Off" }
})

print("--- TEST CASE 1: Valid Transition ---")
print("Initial state:", lightSwitch.currentStateName)

-- ACT
lightSwitch:transitionTo("On")

-- ASSERT
print("Final state:", lightSwitch.currentStateName)
print("-------------------------------------\n")

-- Expected Output for Test Case 1:
-- Initial state: Off
-- <- Exiting Off. Going to: On
-- -> Light is now On. Came from: Off
-- Final state: On

Test Case 2: An Illegal Transition

What happens if we try to transition to a state that isn't allowed by our rules? Let's add a Broken state but provide no rule to transition to it.

Arrange: The FSM is currently in the On state from the previous test.

Act: We attempt to call transitionTo("Broken").

Assert: We expect to see the warning message from our transitionTo function, and the state should remain On.

-- Add this after the code from Test Case 1

lightSwitch:defineState("Broken", {
    enter = function() print("This should never be printed!") end
})

print("--- TEST CASE 2: Illegal Transition ---")
print("Initial state:", lightSwitch.currentStateName)

-- ACT
lightSwitch:transitionTo("Broken") -- This transition is not defined

-- ASSERT
print("Final state:", lightSwitch.currentStateName)
print("---------------------------------------\n")

-- Expected Output for Test Case 2:
-- Initial state: On
-- FSM Error: Transition from 'On' to 'Broken' is not permitted. (A warning in the console)
-- Final state: On

Test Case 3: A Guarded Transition

This is the most important test. We need to verify that our guard conditions work, both when they pass and when they fail. Let's say we can only transition to Off if a condition isPowerOn is true.

Arrange: We'll need a new FSM instance or redefine the transitions for our existing one to include a guard. Let's redefine for simplicity.

Act & Assert (Failure): We'll set isPowerOn to false and try to transition to Off. We expect the transition to be silently blocked.

Act & Assert (Success): We'll then set isPowerOn to true and try again. This time, we expect the transition to succeed.

-- Add this after the code from Test Case 2

-- Re-arranging transitions to include a guard
local isPowerOn = false
lightSwitch:defineTransitions({
    { from = "Off", to = "On" },
    { from = "On", to = "Off", guard = function()
        print("Guard check: isPowerOn is", isPowerOn)
        return isPowerOn
    end}
})

print("--- TEST CASE 3: Guarded Transition ---")
print("Initial state:", lightSwitch.currentStateName)

print("\nPart A: Guard fails")
isPowerOn = false
lightSwitch:transitionTo("Off")
print("State after failed guard:", lightSwitch.currentStateName)

print("\nPart B: Guard succeeds")
isPowerOn = true
lightSwitch:transitionTo("Off")
print("State after successful guard:", lightSwitch.currentStateName)
print("---------------------------------------\n")

-- Expected Output for Test Case 3:
-- Initial state: On

-- Part A: Guard fails
-- Guard check: isPowerOn is false
-- State after failed guard: On

-- Part B: Guard succeeds
-- Guard check: isPowerOn is true
-- <- Exiting On. Going to: Off
-- -> Light is now Off. Came from: On
-- State after successful guard: Off

This small script has now successfully verified the core logic of our FSM module! It confirms that legal transitions work, illegal ones are blocked, and guards are respected.

4. Viewing Real-World Test Examples

The simple script we wrote is a form of a "unit test." Developers use this pattern constantly. The following resources show how others in the Roblox community apply these same principles to test their FSMs.

First, the GitHub repository for a popular FSM library contains an "Example usage" section that is, in fact, a perfect self-contained test script.

This next video shows a more "in-game" style of testing, using game elements to trigger state changes and the output log to verify them.

Conclusion

You have successfully built and, more importantly, verified a reusable FSM module. This is a significant milestone. By writing a dedicated test script, you've gained confidence that your tool is not only powerful but also predictable and reliable.

Key Takeaways:

• Testing is a systematic process of verifying your code's behavior.
• The Arrange, Act, Assert pattern provides a clear structure for writing test cases.
• A good test script checks not only for successful operations but also for correct handling of errors, invalid inputs, and boundary conditions (like guards).
• Verifying transitions can be as simple as printing the current state to the console and checking that it matches your expectation.

Our FSM module is now "production-ready." We have a robust, tested tool in our developer toolkit. We are now fully prepared to apply it to the complex, real-world problems you wanted to solve.

In our next lesson, we will begin Module 4 and dive into our first major application: using our new FSM to design and implement the AI for a non-player character.