Helpers and assertions to make Finitomata implementation easily testable.

Testing with Finitomata.ExUnit

There are several steps needed to enable extended testing with Finitomata.ExUnit.

In the first place, mox dependency should be included in your mix.exs project file

{:mox, "~> 1.0", only: [:test]}

Then, the Finitomata declaration should include a listener. If you already have the listener, it should be changed to Mox in :test environment, and the respecive Mox should be defined somewhere in test/support or like

@listener (if Mix.env() == :test, do: MyFSM.Mox, else: MyFSM.Listener)
use Finitomata, fsm: @fsm, listener: @listener
# or
# use Finitomata, fsm: @fsm, listener: {:mox, MyFSM.Listener}

If you don’t have an actual listener, the special :mox value for listener would do everything, including an actual Mox declaration in test environment.

use Finitomata, fsm: @fsm, listener: :mox

The last thing you need, import Mox into your test file which also does import Finitomata.ExUnit. That’s it, now your code is ready to use Finitomata.ExUnit fancy testing.

Example

Consider the following simple FSM

defmodule Turnstile do
  @fsm ~S[
    ready --> |on!| closed
    opened --> |walk_in| closed
    closed --> |coin_in| opened
    closed --> |switch_off| switched_off
  ]
  use Finitomata, fsm: @fsm, auto_terminate: true

  @impl Finitomata
  def on_transition(:opened, :walk_in, _payload, state) do
    {:ok, :closed, update_in(state, [:data, :passengers], & &1 + 1)}
  end
  def on_transition(:closed, :coin_in, _payload, state) do
    {:ok, :opened, state}
  end
  def on_transition(:closed, :switch_off, _payload, state) do
    {:ok, :switched_off, state}
  end
end

Of course, in the real life, one would not only collect the total number of passengers passed in the state, but also validate the coin value to let in or fail a transition, but for the demonstration purposes this one is already good enough.

We now want to test it works as expected. Without Finitomata.ExUnit, one would write the test like below

# somewhere else → Mox.defmock(Turnstile.Mox, for: Finitomata.Listener)
test "standard approach" do
  start_supervised(Finitomata.Supervisor)

  fini_name = "Turnstile_1"
  fsm_name = {:via, Registry, {Finitomata.Registry, fini_name}}

  Finitomata.start_fsm(Turnstile, fini_name, %{data: %{passengers: 0}})

  Finitomata.transition(fini_name, :coin_in)
  assert %{data: %{passengers: 0}} = Finitomata.state(Turnstile, "Turnstile_1", :payload)

  Finitomata.transition(fini_name, :walk_in)
  assert %{data: %{passengers: 1}} = Finitomata.state(Turnstile, "Turnstile_1", :payload)

  Finitomata.transition(fini_name, :switch_off)

  Process.sleep(200)
  refute Finitomata.alive?(Turnstile, "Turnstile_1")
end

At the first glance, there is nothing wrong with this approach, but it requires an enormous boilerplate, it cannot check it’s gone without using Process.sleep/1, but most importantly, it does not allow testing intermediate states.

If the FSM has instant transitions (named with a trailing bang, like foo!) which are invoked automatically by Finitomata itself, there is no way to test intermediate states with the approach above.

OK, let’s use Mox then (assuming Turnstile.Mox has been declared and added as a listener in test environment to use Finitomata)

# somewhere else → Mox.defmock(Turnstile.Mox, for: Finitomata.Listener)
test "standard approach" do
  start_supervised(Finitomata.Supervisor)

  fini_name = "Turnstile_1"
  fsm_name = {:via, Registry, {Finitomata.Registry, fini_name}}
  parent = self()

  Turnstile.Mox
  |> allow(parent, fn -> GenServer.whereis(fsm_name) end)
  |> expect(:after_transition, 4, fn id, state, payload ->
    parent |> send({:on_transition, id, state, payload}) |> then(fn _ -> :ok end)
  end)

  Finitomata.start_fsm(Turnstile, fini_name, %{data: %{passengers: 0}})

  Finitomata.transition(fini_name, :coin_in)
  assert_receive {:on_transition, ^fsm_name, :opened, %{data: %{passengers: 0}}}
  # assert %{data: %{passengers: 0}} = Finitomata.state(Turnstile, "Turnstile_1", :payload)

  Finitomata.transition(fini_name, :walk_in)
  assert_receive {:on_transition, ^fsm_name, :closed, %{data: %{passengers: 1}}}
  # assert %{data: %{passengers: 1}} = Finitomata.state(Turnstile, "Turnstile_1", :payload)

  Finitomata.transition(fini_name, :switch_off)
  assert_receive {:on_transition, ^fsm_name, :switched_off, %{data: %{passengers: 1}}}

  Process.sleep(200)
  refute Finitomata.alive?(Turnstile, "Turnstile_1")
end

That looks better, but there is still too much of boilerplate. Let’s see how it’d look like with Finitomata.ExUnit.

describe "Turnstile" do
  setup_finitomata do
    parent = self()
    initial_passengers = 42

    [
      fsm: [implementation: Turnstile, payload: %{data: %{passengers: initial_passengers}}],
      context: [passengers: initial_passengers]
    ]
  end

  test_path "respectful passenger", %{passengers: initial_passengers} do
    :coin_in ->
      assert_state :opened do
        assert_payload do
          data.passengers ~> ^initial_passengers
        end
      end

    :walk_in ->
      assert_state :closed do
        assert_payload do
          data.passengers ~> one_more when one_more == 1 + initial_passengers
        end
      end

    :switch_off ->
      assert_state :switched_off
      assert_state :*
  end

With this approach, one could test the payload in the intermediate states, and validate messages received from the FSM with assert_receive/3.

No other code besides assert_state/2, assert_payload/1, and ExUnit.Assertions.assert_receive/3 is permitted to fully isolate the FSM execution from side effects.

Custom environments

In the bigger application, it might be not convenient to declare mocks for each and every case when Finitomata/Infinitomata might have been called under the hood.

For such cases, one might pass mox_envs: :finitomata to an FSM declaration, or set such a config options as config :finitomata, :mox_envs, :finitomata. That would result in mocks implemented for listener: :mox in this environment(s) only.

Then the tests should have been split into two groups assuming the finitomata tests were generated with the mix task (see below)

mix test --exclude finitomata
MIX_ENV=finitomata mix test --exclude test --include finitomata

Don’t forget to add :finitomata env to the list of envs where mox is installed

Test Scaffold Generation

 mix finitomata.generate.test --module MyApp.FSM

Testing without Mox

If you’d rather not depend on Mox, declare the FSM with the built-in Finitomata.ExUnit.Listener instead of :mox:

use Finitomata, fsm: @fsm, listener: Finitomata.ExUnit.Listener
# or, test-only:
# @listener if Mix.env() == :test, do: Finitomata.ExUnit.Listener
# use Finitomata, fsm: @fsm, listener: @listener

Everything else (setup_finitomata/1, test_path/3, assert_transition/3, assert_state/2, assert_payload/1) works exactly the same — just drop import Mox. See Finitomata.ExUnit.Listener for details.

Matching the payload

assert_payload/1 matches the carried payload with the ~> operator, whose left-hand side is a (possibly nested) path resolved with get_in/2. The payload therefore has to implement the Access behaviour — the easiest way is to declare it with defstate/1 (which builds an Estructura.Nested), or to use a struct that derives Access. A plain map works out of the box.

Asserting failures

A failed transition (a soft event?, an {:error, _} from on_transition/4, or a raise) does not notify the listener, so there is nothing to assert_receive. Use assert_no_transition/3 to assert that the FSM stayed put and to inspect the error:

assert_no_transition ctx, :reject? do
  assert %Finitomata.Error{reason: :rejected} = last_error
  assert :started = state.current
end

Inside the block, state (the whole Finitomata.State.t/0), payload, and last_error are bound for plain assertions.

Timer transitions

In test_path/3, the :_ clause stands for a timer tick (Finitomata.timer_tick/2); the payload is read straight from the running FSM, so timer-driven on_timer/2 callbacks can be asserted just like regular transitions:

test_path "ticking", _ctx do
  :_ ->
    assert_state :processing do
      assert_payload do: processing ~> true
    end
end

Configurable timeouts

The assert_receive timeout used while awaiting transition notifications (default 1_000 ms), the refute_receive timeout used by assert_no_transition/3 (default 100 ms), and the message-flush timeout (default 100 ms) are all configurable:

config :finitomata,
  ex_unit_assert_receive_timeout: 5_000,
  ex_unit_refute_receive_timeout: 200,
  ex_unit_flush_timeout: 200

Property-based testing

event_generator/1 returns a StreamData generator over the FSM’s events, which can be combined with ExUnitProperties to fuzz event sequences and assert global invariants (for instance, that the FSM never crashes and always rests in a valid state).