DEV Community: Ibé Dwi

Testing XState FSM using Jest

Ibé Dwi — Wed, 27 Dec 2023 10:27:35 +0000

After contributing to an open-source project, I've come to understand the importance of writing tests. One advantage of projects with tests is that we can quickly verify if existing features break when changes are made. In fact, when developing a feature, we can swiftly ensure it works as intended for given cases through testing.

This benefit is also true when writing finite state machines (FSM) using XState. Questions arose in my mind, "What if we could quickly verify our FSM works while we're creating it?" and "Does adding new features disrupt existing functionalities?"

In this article, I'll share how I incorporate testing when developing FSMs.

Before continuing, as a disclaimer, XState also offers a package for writing tests. Even more advanced, this package can automatically generate test cases. However, this article focuses on how I test the FSMs I've created against our own (imperative) test cases.

The application discussed in this article can be viewed in this repository.

Case Study

For me, one of the most exciting ways to learn is by using case studies.

In this article, I will use the "phone keypad" as a case study. For those who are unfamiliar, a "phone keypad" is a type of "keyboard" found on older mobile phones.

(Source https://www.gsmarena.com/nokia_3310-pictures-192.php)

Some functionalities we aim to achieve:

Pressing a button for the first time will select the character group on that button and choose the first character in the group.
Repeatedly pressing the same button will select characters according to their order.
If no button is pressed after a set time, the currently selected character will be inserted into the text.
Pressing a different button will insert the currently selected character into the text and change the selection to the first character on the newly pressed button.

Preparing the Project

Next.js

I am using Next.js 13 with the app directory and TailwindCSS. A tutorial on creating a Next.js project with the app router can be found at this link.



What is your project named? logs-understanding-fsm-with-xstate
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias (@/*)? Yes
What import alias would you like configured? @/*

`xstate` & `@xstate/react`

In this article, I am using XState version 4.



yarn add xstate@^4.38.1 @xstate/react@^3.2.2

`jest` & `ts-jest`

Install the following libraries:



 yarn add -D jest ts-jest @types/jest

jest: this library is used for testing.
ts-jest: this library allows us to directly run tests written in TypeScript without having to transpile to JS.
@types/jest: this is the type definition for jest.

Then, execute the following line to initialize Jest configuration with the ts-jest preset.



yarn ts-jest config:init

Folder Structure

Here is the folder structure:



next-app/
├─ src/
│  ├─ app/
│  │  ├─ phone-keypad/
│  │  │  ├─ page.tsx
│  │  ├─ ...
│  ├─ features/
│  │  ├─ phone-keypad/
│  │  │  ├─ constant.ts
│  │  │  ├─ phoneKey.fsm.spec.ts
│  │  │  ├─ phoneKeypad.fsm.ts
│  │  │  ├─ phoneKeypad.module.css
│  │  │  ├─ PhoneKeypad.tsx
│  │  ├─ ...
│  ├─ ../
├─ ...

.fsm are files that contain the definition and the test of our FSM

PhoneKeypad is a component that implements the state machine we will create and integrates it with the UI.

phone-keypad/page.tsx is the page where we display the created keypad.

Layering the application

Separating an application into distinct layers according to their responsibilities makes it easier to maintain. This principle is known as "separation of concern." In this article, I have divided the application into two layers: the UI layer (presentation layer) and the domain layer.

The UI Layer is the layer that consists of displays, such as web pages or components. The domain layer, on the other hand, is the layer that contains the business logic, which in this case is the FSM.

Domain Layer

Representation of the keypad

The first thing I did was create a representation of the keypad to be displayed. Based on the functionality criteria above, the keypad will be pressed one or several times to obtain the desired character. For example, on a Nokia 3310 phone, the number 2 key consists of 3 alphabets and 1 number:



'abc2'

To get the letter "b", I have to press the button twice. The first press will display the letter "a", and the second press within a certain period will display the letter "b".

There are at least two alternatives that I have thought of to represent the existing keys:

Using array of string (1-dimensional array)



   export const PHONE_KEYS = [
     '1',
     'ABC2',
     'DEF3',
     'GHI4',
     'JKL5',
     'MNO6',
     'PQRS7',
     'TUV8',
     'WXYZ9',
     '*',
     ' 0',
     '#'
   ]

or, as array of characters (2-dimensional array)



   export const PHONE_KEYS = [
     ["1"],
     ["A", "B", "C", "2"],
     ["D", "E", "F", "3"],
     ["G", "H", "I", "4"],
     ["J", "K", "L", "5"],
     ["M", "N", "O", "6"],
     ["P", "Q", "R", "S", "7"],
     ["T", "U", "V", "8"],
     ["W", "X", "Y", "Z", "9"],
     ["*"],
     [" ", "0"],
     ["#"],
   ];

Here, I am using the first option. There's no specific reason; it's just a personal preference.

Later on, this array can be used to create the keypad display. It would look something like this:

From the illustration of the mapping above, we can use the expression PHONE_KEYS[characterGroupIndex][characterIndex] to refer to a character

Finite State Machine

Considering the focus of this article is on how I test the FSM I created, I have already developed the FSM to be used.

Here is the context that will be used by this FSM:



export type MachineContext = {
  currentCharacterGroupIndex?: number;
  currentCharacterIndex?: number;
  lastPressedKey?: number;
  str: string;
};

currentCharacterGroupIndex is used to select a character group, and currentCharacterIndex is used to select a character within that group. For example, to refer to the character “A”, the value of currentCharacterIndex would be 0. To refer to the character “B”, the value used would be 1, and so on.

lastPressedKey is used to track the last pressed button. Lastly, str is used to store the text that we type.

The FSM recognizes one type of event, which are:



export type MachineEvent =
  | {
      type: "KEY.PRESSED";
      key: number;
    }

The event "KEY.PRESSED" informs the FSM that a button has been pressed. This event carries a "key" property that tells the machine which character group to use.

The overall behavior of the FSM can be seen in the following diagram:

The first functionality,

Pressing a button for the first time will select the character group on that button and choose the first character in the group.

is fulfilled when transitioning from the state "Idle" to "Waiting for key being pressed again". In the event that is sent, "KEY.PRESSED", there is an action named onFirstPress which will change the value of currentCharacterGroupIndex to the "key" carried by the "KEY.PRESSED" event and currentCharacterIndex to 0. In this action, we also store the "key" carried in the lastPressedKey property as a reference for the second functionality.

(Where the first functionality is fulfilled)

The second functionality,

Pressing the same button repeatedly will select characters in sequence.

is fulfilled when the state "Waiting for key being pressed again" receives the "KEY.PRESSED" event but the guard "isTheSameKey?" is satisfied. The "isTheSameKey?" guard checks whether the "key" brought by the "KEY.PRESSED" event is the same as the lastPressedKey property stored in the context. If satisfied, the onNextPress action on the event will be called. This action will increment the value of currentCharacterIndex. If the value of currentCharacterIndex reaches the last character, it will reset to 0.

(Where the second functionality is fulfilled)

The third functionality,

If no button is pressed after a set time, the currently selected character will be inserted into the text.

is fulfilled when no "KEY.PRESSED" event is received within 500ms while in the "Waiting for key being pressed again" state. In other words, the FSM will wait for 500ms before triggering the "after 500ms" event. The state will then transition to "Waited time passed" which subsequently transitions to the "Idle" state and triggers the actions "assignToString" and "removeSelectedKey" in sequence.

The "assignToString" action will add the character at currentCharacterGroupIndex and currentCharacterIndex to the context str. The "removeSelectedKey" action will clear the values of currentCharacterGroupIndex, currentCharacterIndex, and lastPressedKey.

It is important to note that in the "Waiting for key being pressed again" state, if a "KEY.PRESSED" event is received, the 500ms wait time will reset from 0.

(Where the third functionality is fulfilled)

The final functionality,

Pressing a different button will insert the currently selected character into the text and change the selection to the first character on the newly pressed button.

is fulfilled when in the "Waiting for key being pressed again" state, a "KEY.PRESSED" event is received but does not satisfy the guard "isTheSameKey?". This event will trigger the actions "assignToString", "removeSelectedKey", and "onFirstPress". Notably, the first two actions in this event are the same as when we add the currently referenced character to the string. Meanwhile, the "onFirstPress" action, which is last in the sequence, will update the properties currentCharacterGroupIndex, currentCharacterIndex, and lastPressedKey according to the "key" property brought by the "KEY.PRESSED" event.

(Where the fourth functionality is fulfilled)

The complete definition of the FSM can be viewed in the repository.

Testing the FSM

Finally, we get to the core of this article!

Before I knew about testing, what I did to verify my state machine was to test it directly alongside the UI! However, the more complex my FSM became, the harder it was to test certain states, especially states approaching the final state.

For me, there are two main benefits of testing the FSM I created:

During the development process, I can verify that the FSM I created works as intended without having to touch the UI. Returning to the principle of layering mentioned earlier, the FSM is in the logic layer while the UI is in the UI layer (presentation layer). The UI layer has no connection to the correctness of the logic layer.
If there are changes to the FSM, I can quickly re-verify whether my FSM still works as expected, as outlined in the test cases.

So, what needs to be tested?

For the case in this article, I take the existing functionalities as a reference for testing.

Writing Test Cases

First, I create a test file named phoneKey.fsm.spec.ts. Then, I add a test suite named “phoneKeypad”:



// phoneKey.fsm.spec.ts

describe("phoneKeypad", () => {
  // test cases will be written in here...
})

The first test case ensures that functionalities 1, 2, and 3 are met:



const waitFor = async (time: number) => new Promise((r) => setTimeout(r, time));

describe("phoneKeypad", () => {
  it("should be able to type using the keys", async () => {
    const fsm = interpret(phoneKeypadMachine)
    fsm.start();

    fsm.send({ type: "KEY.PRESSED", key: 0 });
    await waitFor(500);
    expect(fsm.getSnapshot().context.str).toBe("1");

    fsm.send({ type: "KEY.PRESSED", key: 1 });
    await waitFor(200);
    fsm.send({ type: "KEY.PRESSED", key: 1 });
    await waitFor(200);
    fsm.send({ type: "KEY.PRESSED", key: 1 });
    await waitFor(200);
    fsm.send({ type: "KEY.PRESSED", key: 1 });

    await waitFor(500);

    expect(fsm.getSnapshot().context.str).toBe("12");
  });
})

In the expression:



const fsm = interpret(phoneKeypadMachine.withConfig({})).start();

We interpret the already created phoneKeypadMachine using the interpret function. This function will return a running process based on the FSM we have created. This process is referred to as an “actor”.

As a note, the interpret function is deprecated in XState5. If you are using XState5, you can use the createActor function. (Ref)

The process stored in the fsm variable has not yet started. To run it, we can use the start method.



fsm.start();

Next, we simulate a button being pressed.
Before defining the test suite, we define a function named waitFor. This function is used to wait for a certain amount of time.

In these statements:



fsm.send({ type: "KEY.PRESSED", key: 0 });
await waitFor(500);
expect(fsm.getSnapshot().context.str).toBe("1");

We send the "KEY.PRESSED" event with key 0 to the state machine. Referring to the buttons we have created:



export const PHONE_KEYS = [
  '1',
  'ABC2',
  'DEF3',
  'GHI4',
  'JKL5',
  'MNO6',
  'PQRS7',
  'TUV8',
  'WXYZ9',
  '*',
  ' 0',
  '#'
]

the selected character is “1”. We then wait for 500ms. We check if the value of context.str is “1”. This set of statements tests functionalities 1 and 3.

Then, in the following statements:



fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(200);
fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(200);
fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(200);
fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(500);

expect(fsm.getSnapshot().context.str).toBe("12");

We send the "KEY.PRESSED" event four times with key “1”. To ensure that a character is only added after 500ms, each time we press the button with key “1”, we wait for 200ms. We know that the button with key “1” refers to the second character group, 'ABC2'. Pressing it four times before 500ms are up will select the fourth character, which is “2”.

At the end of these statements, we test whether the character “2” has been added to the existing str, so the current value of str should now be “12”.

Finally, we test the fourth functionality:



it("pressing different key will added the current key to string", async () => {
  const fsm = interpret(phoneKeypadMachine).start();

  fsm.send({ type: "KEY.PRESSED", key: 0 });

  fsm.send({ type: "KEY.PRESSED", key: 1 });

  fsm.send({ type: "KEY.PRESSED", key: 2 });

  await waitFor(500);

  expect(fsm.getSnapshot().context.str).toBe("1AD");
});

What we do in the above test case is more or less the same as what we did in the previous test case. We interpret the FSM, start the actor from the FSM, and send events according to the functionality requirements.

We can run the test using Jest. First, open the terminal and run the following command:



yarn test phoneKey.fsm

If everything goes smoothly, your terminal should display the following message:



 PASS  src/features/phoneKeypad/phoneKey.fsm.spec.ts
  phoneKeypad
    ✓ should be able to type using the keys (1628 ms)
    ✓ pressing different key will added the current key to string (508 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.962 s

All functionalities have been tested solely through the state machine! Now, it's time to integrate the FSM with the UI!

Integrating FSM into UI

I created a file named PhoneKeypad.tsx which will later be imported into a Next.js page.

Here is the UI component without integration with FSM:



"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";

export function PhoneKeypad() {
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            Text will be displayed here...
            {/* TODO: Add current str value */}
            {/* TODO: Add current selected character preview */}
            {/* TODO: Add blinking caret */}
          </p>
        </div>
        {PHONE_KEYS.map((key, index) => (
          <button
            key={index}
            className={[
              "w-[90px] h-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center",
              "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
            ].join(" ")}
            style={{
              userSelect: "none",
            }}
            // TODO: add "KEY.PRESSED" event
            onClick={() => {}}
          >
            <p className="text-2xl">{key[key.length - 1]}</p>
            <div className="gap-1 flex">
              <span>{key}</span>
            </div>
          </button>
        ))}
      </div>
    </div>
  );
}

The above code snippet includes placeholders for the text input by the user and buttons that will send the "KEY.PRESSED" event.

Integrating Machine

First, we import hooks to integrate XState into a React component. Here I use useInterpret and useSelector. In XState 4, useInterpret is a hook that returns an “actor” or “service” based on the given state machine. Unlike the interpret used in the test, the “service” returned here automatically starts and runs for the lifetime of the React component.

useInterpret returns a static reference from the FSM to the React component used only to interpret the FSM. Unlike useMachine, which flush all updates to the React component causing re-renders on every update, updates to the FSM used by useInterpret will not cause the React component to re-render.

Then how do we get the latest state from the FSM? We can use the useSelector hook to select which parts of the FSM we want to monitor and cause re-renders in our component.

For this case, there are at least 4 things we want to track:

Context currentCharacterGroupIndex and currentCharacterIndex to display the currently selected character
Context str to display the text that has been created
State isIdle used to display a “cursor” or “caret” indicating the machine is waiting for input from the user.

Here is how to use useInterpret and useSelector:



export function PhoneKeypad() {
  // ...
  const fsm = useInterpret(phoneKeypadMachine);
  const { currentCharacterGroupIndex, currentCharacterIndex, value, isIdle } = useSelector(
    fsm,
    (state) => ({
      currentCharacterGroupIndex: state.context.currentCharacterGroupIndex,
      currentCharacterIndex: state.context.currentCharacterIndex,
      value: state.context.str,
      isIdle: state.matches("Idle"),
    })
  );

  // ...
}

Then, we can use the value to complete the first TODO, “Add current str value”



"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";

export function PhoneKeypad() {
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {/* TODO: Add current str value */}
            {value}
            {/* TODO: Add current selected character preview */}
            {/* TODO: Add blinking caret */}
          </p>
        </div>
        {/* ... */}
      </div>
    </div>
  );
}

The second TODO, “Add current selected character preview”, is completed by adding a character preview using currentCharacterGroupIndex and currentCharacterIndex



// ...
export function PhoneKeypad() {
  // ...
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {/* TODO: Add current str value */}
            {value}
            {/* TODO: Add current selected character preview */}
            {selectedIndex != undefined &&
              selectedIndexElement != undefined && (
                <span>{PHONE_KEYS[selectedIndex][selectedIndexElement]}</span>
              )}
            {/* TODO: Add blinking caret */}
          </p>
        </div>
        {/* ... */}
      </div>
    </div>
  );
}

Lastly, to indicate that we will add text at the end of the existing text, we can add a caret or cursor when the FSM is in the “Idle” state



// ...
import classes from "./phoneKeypad.module.css";

// ...
export function PhoneKeypad() {
  // ...
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {/* TODO: Add current str value */}
            {value}
            {/* TODO: Add current selected character preview */}
            {selectedIndex != undefined &&
              selectedIndexElement != undefined && (
                <span>{PHONE_KEYS[selectedIndex][selectedIndexElement]}</span>
              )}
            {/* TODO: Add blinking caret */}
            <span
              className={[classes.blinkingCaret, isIdle ? "" : "hidden"].join(
                " "
              )}
            >
              |
            </span>
          </p>
        </div>
        {/* ... */}
      </div>
    </div>
  );
}

I also created a CSS module that will make the “caret” blink every 500ms:



/* phoneKeypad.module.css */
.blinkingCaret {
  animation: blink 500ms infinite;
}

@keyframes blink {
  50% {
    opacity: 0;
  }
}

Finally, we send the "KEY.PRESSED" event when a button is pressed:



"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";
import { phoneKeypadMachine } from "./phoneKeypad.fsm";
import classes from "./phoneKeypad.module.css";

export function PhoneKeypad() {
  // ...

  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        {/* ... */}
        {PHONE_KEYS.map((key, index) => (
          <button
            key={index}
            className={[
              "w-[90px] h-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center",
              "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
            ].join(" ")}
            style={{
              userSelect: "none",
            }}
            // TODO: add "KEY.PRESSED" event
            onClick={() => fsm.send({ type: "KEY.PRESSED", key: index })}
          >
            <p className="text-2xl">{key[key.length - 1]}</p>
            <div className="gap-1 flex">
              <span>{key}</span>
            </div>
          </button>
        ))}
      </div>
    </div>
  );
}

Here is the complete code snippet:



"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";
import { phoneKeypadMachine } from "./phoneKeypad.fsm";
import classes from "./phoneKeypad.module.css";

export function PhoneKeypad() {
  const fsm = useInterpret(phoneKeypadMachine);
  const { selectedIndex, selectedIndexElement, value, isIdle } = useSelector(
    fsm,
    (state) => ({
      selectedIndex: state.context.currentCharacterGroupIndex,
      selectedIndexElement: state.context.currentCharacterIndex,
      value: state.context.str,
      isIdle: state.matches("Idle"),
    })
  );

  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {value}
            {selectedIndex != undefined &&
              selectedIndexElement != undefined && (
                <span>{PHONE_KEYS[selectedIndex][selectedIndexElement]}</span>
              )}
            <span
              className={[classes.blinkingCaret, isIdle ? "" : "hidden"].join(
                " "
              )}
            >
              |
            </span>
          </p>
        </div>
        {PHONE_KEYS.map((key, index) => (
          <button
            key={index}
            className={[
              "w-[90px] h-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center",
              "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
            ].join(" ")}
            style={{
              userSelect: "none",
            }}
            onClick={() => fsm.send({ type: "KEY.PRESSED", key: index })}
          >
            <p className="text-2xl">{key[key.length - 1]}</p>
            <div className="gap-1 flex">
              <span>{key}</span>
            </div>
          </button>
        ))}
      </div>
    </div>
  );
}

When we run this application, it will look something like this:

Benefits of Testing

For instance, suppose this application is shipped, and we can continue with our lives peacefully. But one day, there's a request to add a feature!

Users can write text but can't delete it!

We can say there's a new functionality added, “User can delete text.”

What can we do to implement this functionality?

Adding Delete Functionality to the FSM

Firstly, of course, we add the delete function. Here, I add a new event named “DELETE.PRESSED” that can be sent when the FSM is in the “Idle” state.

This event will trigger an action named “onDeleteLastChar” that will delete the last character in str.

Do we immediately add this event to the UI? Certainly not!

Adding a New Test Case

After adding the delete functionality to the FSM, we need to write a test. Here's the test case I wrote to test this functionality:



describe("phoneKeypad", () => {
  // ...
  it("pressing delete will remove the last char", async () => {
    const fsm = interpret(phoneKeypadMachine.withConfig({})).start();

    fsm.send({ type: "KEY.PRESSED", key: 0 });

    fsm.send({ type: "KEY.PRESSED", key: 1 });

    fsm.send({ type: "KEY.PRESSED", key: 2 });

    await waitFor(500);
    expect(fsm.getSnapshot().context.str).toBe("1AD");

    fsm.send({ type: "DELETE.PRESSED" });
    expect(fsm.getSnapshot().context.str).toBe("1A");

    fsm.send({ type: "DELETE.PRESSED" });
    fsm.send({ type: "DELETE.PRESSED" });
    expect(fsm.getSnapshot().context.str).toBe("");
  });
});

To ensure this test is passed and the previous test cases are also passed, open the terminal and run the following command again:



yarn test phoneKey.fsm

If everything goes smoothly, your terminal should display the following message:



 PASS  src/features/phoneKeypad/phoneKey.fsm.spec.ts
  phoneKeypad
    ✓ should be able to type using the keys (1626 ms)
    ✓ pressing different key will added the current key to string (507 ms)
    ✓ pressing delete will remove the last char (514 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        4.621 s

What I like about having tests is that I can ensure all the existing functionalities still work according to the written test cases. If there are indeed changes to the functionalities, then the test cases should also change and adapt. But if not, I can still use the same test cases!

Adding a Delete Button

Finally, we only need to add a button to send the “DELETE.PRESSED” event from the UI



// ...
export function PhoneKeypad() {
  // ...
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        {/* ... */}
        <button
          className={[
            "col-start-3 col-end-3",
            "w-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center py-4",
            "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
          ].join(" ")}
          onClick={() => fsm.send({ type: "DELETE.PRESSED" })}
        >
          DEL
        </button>
        {PHONE_KEYS.map((key, index) => (
          // ...
        ))}
      </div>
    </div>
  );
}

Our application now looks like this:

Conclusion

In this article, I have shared how I test the FSM I created with XState4 imperatively using Jest. By writing tests, we gain the confidence that at least the FSM we created works according to the given test cases.

Please remember, XState version 5 (the latest) has slightly different APIs, but the principles are more or less the same. Additionally, XState also provides a package for testing with a model-based testing approach. This package can also automatically create test cases based on the provided state machine definition!

Thank you for reading my article! Have a nice day!

🇮🇩 Menguji FSM XState dengan Jest

Ibé Dwi — Tue, 26 Dec 2023 12:54:49 +0000

Setelah beberapa kontribusi saya ke salah satu open source, saya menjadi semakin paham tentang pentingnya menulis test. Salah satu keuntungan dari project yang memiliki tests adalah kita bisa dengan cepat memverifikasi apakah fitur yang sudah ada rusak ketika kita membuat perubahan. Bahkan, ketika membuat sebuah fitur, kita bisa dengan cepat memastikan apakah fitur itu sudah bekerja sesuai dengan kasus yang diberikan melalui test.

Keuntungan yang sama juga bisa didapatkan ketika menulis finite state machine (FSM) menggunakan XState. Pertanyaan yang muncul di kepala saya, “bagaimana jika kita bisa dengan cepat memverifikasi FSM kita bekerja saat kita sedang membuatnya?” dan “apakah fitur baru yang ditambahkan tidak merusak fungsionalitas yang sudah ada?”.

Di tulisan ini, saya akan berbagi tentang bagaimana saya menyertakan pengujian ketika mengembangkan FSM.

Sebelum lanjut, sebagai disclaimer, XState juga menyediakan package untuk menuliskan test. Lebih canggih lagi, package tersebut bisa membuat test cases secara otomatis. Tetapi, tulisan ini berfokus pada bagaimana saya menguji FSM yang sudah dibuat terhadap test cases yang kita buat sendiri (secara imperatif).

Aplikasi yang dibuat di tulisan ini dapat dilihat di repo ini.

Studi kasus

Bagi saya, salah satu belajar yang seru adalah dengan menggunakan studi kasus.

Untuk tulisan ini, saya akan menggunakan “phone keypad” sebagai studi kasus. Bagi kamu yang belum tahu, “phone keypad” ini adalah bentuk “keyboard” yang ada di handphone lama.

(Sumber: https://www.gsmarena.com/nokia_3310-pictures-192.php)

Beberapa fungsionalitas yang ingin dicapai:

Menekan sebuah tombol untuk pertama kali akan memilih grup karakter yang ada pada tombol tersebut dan memilih karakter pertama yang ada pada grup karakter.
Menekan tombol yang sama berulang-ulang akan memilih karakter sesuai dengan urutan.
Jika tidak ada tombol yang ditekan setelah waktu yang ditentukan, karakter yang dipilih saat ini akan dimasukkan ke dalam teks.
Menekan tombol yang berbeda akan memasukkan karakter yang terpilih saat ini ke dalam teks dan mengganti karakter yang sedang dipilih menjadi karakter pertama pada tombol yang ditekan.

Menyiapkan Project

Next.js

Saya menggunakan Next.js 13 dengan app directory dan TailwindCSS. Tutorial membuat project Next.js dengan app router dapat ditemukan di link ini.

What is your project named? logs-understanding-fsm-with-xstate
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias (@/*)? Yes
What import alias would you like configured? @/*

`xstate` & `@xstate/react`

Pada tulisan ini, saya menggunakan XState 4

yarn add xstate@^4.38.1 @xstate/react@^3.2.2

`jest` dan `ts-jest`

Install libraries berikut ini:

 yarn add -D jest ts-jest @types/jest

jest adalah library yang digunakan untuk testing.
ts-jest adalah library yang memungkinkan kita untuk langsung menjalankan test yang ditulis menggunakan TypeScript tanpa harus melakukan transpilasi ke JS.
@types/jest adalah type definition untuk jest

Kemudian, eksekusi baris berikut untuk menginisiasi konfigurasi jest dengan preset ts-jest

yarn ts-jest config:init

Struktur folder

Berikut adalah struktur folder:

next-app/
├─ src/
│  ├─ app/
│  │  ├─ phone-keypad/
│  │  │  ├─ page.tsx
│  │  ├─ ...
│  ├─ features/
│  │  ├─ phone-keypad/
│  │  │  ├─ constant.ts
│  │  │  ├─ phoneKey.fsm.spec.ts
│  │  │  ├─ phoneKeypad.fsm.ts
│  │  │  ├─ phoneKeypad.module.css
│  │  │  ├─ PhoneKeypad.tsx
│  │  ├─ ...
│  ├─ ../
├─ ...

.fsm adalah file yang berisi definisi dari state machine kita

PhoneKeypad adalah component yang mengimplementasikan state machine yang akan kita buat dan mengintegrasikannya dengan UI.

phone-keypad/page.tsx adalah halaman di mana kita menampilkan keypad yang sudah dibuat.

Membuat lapisan aplikasi

Memisahkan aplikasi menjadi beberapa lapisan (layer) terpisah sesuai dengan tanggung jawabnya membuat kita lebih mudah memelihara aplikasi kita. Prinsip ini dikenal dengan nama “separation of concern”. Di tulisan ini, saya membagi aplikasi ini menjadi 2 lapisan, UI layer (presentation layer) dan domain layer.

UI Layer adalah lapisan yang teridiri dari tampilan, misalnya halaman web atau component. Sedangkan domain layer adalah lapisan yang berisi business logic, dalam hal ini adalah FSM.

Domain Layer - FSM

Representasi keypad (tombol)

Hal yang pertama saya lakukan adalah membuat representasi dari keypad yang akan ditampilkan. Berdasarkan kriteria fungsionalitas di atas, keypad akan ditekan satu hingga beberapa kali untuk mendapatkan karakter yang diinginkan. Sebagai contoh, kita di handphone Nokia 3310, key nomor 2 terdiri dari 3 alfabet dan 1 angka:

'abc2'

Untuk mencetak huruf “b”, saya harus menekan tombol sebanyak 2 kali. Tekanan pertama akan menampilkan huruf “a”, dan tekanan kedua dalam kurun waktu tertentu akan menampilkan huruf “b”.

Setidaknya ada dua alternatif yang terpikirkan oleh saya untuk merepresentasikan keys yang ada:

Menggunakan array of string (1-dimensional array)

   export const PHONE_KEYS = [
     '1',
     'ABC2',
     'DEF3',
     'GHI4',
     'JKL5',
     'MNO6',
     'PQRS7',
     'TUV8',
     'WXYZ9',
     '*',
     ' 0',
     '#'
   ]

Atau sebagai array of characters (2-dimensional array)

   export const PHONE_KEYS = [
     ["1"],
     ["A", "B", "C", "2"],
     ["D", "E", "F", "3"],
     ["G", "H", "I", "4"],
     ["J", "K", "L", "5"],
     ["M", "N", "O", "6"],
     ["P", "Q", "R", "S", "7"],
     ["T", "U", "V", "8"],
     ["W", "X", "Y", "Z", "9"],
     ["*"],
     [" ", "0"],
     ["#"],
   ];

Di sini, saya menggunakan opsi pertama. Tidak ada alasan spesifik, hanya preferensi pribadi.

Nantinya, array ini dapat digunakan untuk membuat tampilan keypad. Kurang lebih seperti ini:

Dari ilustrasi pemetaan di atas, kita bisa menggunakan expression PHONE_KEYS[characterGroupIndex][characterIndex] untuk mengacu pada sebuah karakter.

Finite State Machine

Mengingat fokus tulisan ini adalah bagaimana saya menguji FSM yang saya buat, saya sudah membuat FSM yang akan digunakan.

Berikut adalah context yang akan digunakan oleh FSM ini:

export type MachineContext = {
  currentCharacterGroupIndex?: number;
  currentCharacterIndex?: number;
  lastPressedKey?: number;
  str: string;
};

currentCharacterGroupIndex digunakan untuk memilih grup karakter dan currentCharacterIndex digunakan untuk memilih karakter yang ada pada grup tersebut. Misanya, untuk mengacu pada karakter “A”, nilai dari currentCharacterIndex adalah 0. Untuk mengacu pada karakter “B”, nilai yang dipakai adalah 1, dan seterusnya.

lastPressedKey digunakan untuk melacak tombol terakhir yang dipencet. Yang terakhir, str digunakan untuk menyimpan teks yang kita ketik.

Event yang diterima oleh FSM ada 1, yaitu:

export type MachineEvent =
  | {
      type: "KEY.PRESSED";
      key: number;
    };

Event “KEY.PRESSED” memberi tahu FSM bahwa ada tombol yang ditekan. Event ini membawa property “key” yang akan memberi tahu mesin grup karakter mana yang akan digunakan.

Behavior keseluruhan dari FSM dapat dilihat pada diagram berikut:

Fungsionalitas pertama,

Menekan sebuah tombol untuk pertama kali akan memilih grup karakter yang ada pada tombol tersebut dan memilih karakter pertama yang ada pada grup karakter.

terpenuhi ketika transisi dari state “Idle” ke “Waiting for key being pressed again”. Pada event yang dikirim, “KEY.PRESSED”, ada action bernama onFirstPress yang akan merubah nilai dari currentCharacterGroupIndex menjadi “key” yang dibawa oleh event “KEY.PRESSED” dan currentCharacterIndex menjadi 0. Pada action ini kita juga menyimpan “key” yang dibawa di property “lastPressedKey” sebagai referensi untuk fungsionalitas kedua.

(Bagian di mana fungsionalitas pertama terpenuhi)

Fungsionalitas kedua,

Menekan tombol yang sama berulang-ulang akan memilih karakter sesuai dengan urutan.

terpenuhi ketika state “Waiting for key being pressed again” menerima event “KEY.PRESSED” tetapi guard “isTheSameKey?” terpenuhi. Guard “isTheSameKey?” mengecek apakah “key” yang dibawa oleh event “KEY.PRESSED” sama dengan property “lastPressedKey” yang disimpan di context. Jika terpenuhi, action onNextPress yang ada pada event akan dipanggil. Action ini akan menambah nilai dari currentCharacterIndex . Jika nilai currentCharacterIndex sudah mencapai karakter terakhir, nilainya akan kembali menjadi 0.

(Bagian di mana fungsionalitas kedua terpenuhi)

Fungsionalitas ketiga,

Jika tombol tidak diklik setelah waktu yang ditentukan, karakter yang dipilih saat ini akan dimasukkan ke dalam teks.

terpenuhi saat tidak ada event “KEY.PRESSED” yang diterima dalam kurun waktu 500ms saat berada pada state “Waiting for key being pressed again”. Atau dengan kata lain, FSM akan menunggu selama 500ms sebelum memicu event “after 500ms”. State akan transisi ke “Waited time passed”, yang kemudian transisi ke state “Idle” dan memicu action “assignToString” dan “removeSelectedKey” secara berurutan.

Action “assignToString” akan menambahkan karakter pada grup karakter currentCharacterGroupIndex dan karakter currentCharacterIndex ke dalam context str. Sedangkan action “removeSelectedKey” akan menghapus nilai dari currentCharacterGroupIndex, currentCharacterIndex, dan lastPressedKey.

Perlu diingat, pada state Waiting for key being pressed again, jika ada “KEY.PRESSED” yang diterima maka waktu tunggu “500ms” akan diulang dari 0.

(Bagian di mana fungsionalitas ketiga terpenuhi)

Fungsionalitas yang terakhir,

Menekan tombol yang berbeda akan memasukkan karakter yang terpilih saat ini ke dalam teks dan mengganti karakter yang sedang dipilih menjadi karakter pertama pada tombol yang diklik.

terpenuhi ketika pada state “Waiting for key being pressed again”, ada event “KEY.PRESSED” yang diterima tetapi tidak memenuhi guard “isTheSameKey?”. Event ini akan memicu action “assignToString”, “removeSelectedKey”, dan “onFirstPress”. Kalau kita perhatikan, 2 actions pertama pada event ini sama dengan ketika kita menambahkan karakter yang diacu saat ini ke dalam string. Sedangkan, action “onFirstPress” yang ada pada urutan terakhir akan memperbarui properties currentCharacterGroupIndex, currentCharacterIndex, dan lastPressedKey sesuai dengan property “key” yang dibawa oleh event “KEY.PRESSED”.

(Bagian di mana fungsionalitas keempat terpenuhi)

Definisi FSM yang lengkap dapat kamu lihat di repo.

Menguji FSM

Akhirnya kita masuk ke inti dari tulisan ini!

Sebelum mengenal testing, yang saya lakukan untuk memverifikasi state machine saya adalah dengan mengujinya langsung bersamaan dengan UI! Tetapi, semakin kompleks FSM yang saya punya, akan semakin sulit untuk menguji state yang ada pada tahap-tahap tertentu, misalnya state yang mendekati final state.

Bagi saya, ada 2 hal yang menguntungkan dengan menguji FSM yang saya buat:

dalam proses development, saya bisa memverifikasi bahwa FSM yang saya buat bekerja sesuai dengan keinginan saya tanpa harus menyentuh UI. Kembali ke prinsip layering di atas, FSM ada logic layer sedangkan UI berada pada UI layer (presentation layer). UI layer tidak ada sangkut pautnya dengan kebenaran dari logic layer.
Jika ada perubahan pada FSM, saya bisa dengan cepat memverifikasi kembali apakah FSM saya masih bekerja sesuai dengan ekspektasi yang ada sebelumnya, yang dituangkan dalam test cases.

Lalu, apa saja yang harus diuji?

Untuk kasus dalam tulisan ini, saya mengambil fungsionalitas yang ada sebagai acuan untuk testing.

Menulis test cases

Pertama, saya membuat sebuah file test bernama phoneKey.fsm.spec.ts. Kemudian, saya menambahkan sebuah test suite bernama “phoneKeypad”:

// phoneKey.fsm.spec.ts

describe("phoneKeypad", () => {
  // test cases will be written in here...
})

Test case yang pertama adalah saya memastikan bahwa fungsionalitas 1, 2, dan 3 terpenuhi:

const waitFor = async (time: number) => new Promise((r) => setTimeout(r, time));

describe("phoneKeypad", () => {
  it("should be able to type using the keys", async () => {
    const fsm = interpret(phoneKeypadMachine)
    fsm.start();

    fsm.send({ type: "KEY.PRESSED", key: 0 });
    await waitFor(500);
    expect(fsm.getSnapshot().context.str).toBe("1");

    fsm.send({ type: "KEY.PRESSED", key: 1 });
    await waitFor(200);
    fsm.send({ type: "KEY.PRESSED", key: 1 });
    await waitFor(200);
    fsm.send({ type: "KEY.PRESSED", key: 1 });
    await waitFor(200);
    fsm.send({ type: "KEY.PRESSED", key: 1 });

    await waitFor(500);

    expect(fsm.getSnapshot().context.str).toBe("12");
  });
})

Pada expression:

const fsm = interpret(phoneKeypadMachine.withConfig({})).start();

Kita menggunakan menginterpretasikan phoneKeypadMachine yang sudah dibuat menggunakan fungsi “interpret”. Fungsi ini akan mengembalikan proses yang berjalan berdasarkan FSM yang sudah kita buat. Proses ini disebut “actor”.

Sebagai catatan, fungsi interpret sudah deprecated pada XState5. Jika kamu menggunakan XState5, kamu bisa menggunakan fungsi createActor. (Ref)

Proses yang disimpan di dalam variable fsm belum berjalan. Untuk menjalankannya, kita bisa menggunakan method start

fsm.start();

Kemudian, kita mensimulasikan tombol dipencet.

Sebelum definisi test suite, kita mendefisinikan sebuah fungsi bernama waitFor. Fungsi ini digunakan untuk menunggu selama beberapa waktu.

Beberapa statement ini

fsm.send({ type: "KEY.PRESSED", key: 0 });
await waitFor(500);
expect(fsm.getSnapshot().context.str).toBe("1");

kita mengirim event “KEY.PRESSED” dengan key 0 ke state machine. Jika merujuk pada tombol yang sudah kita buat:

export const PHONE_KEYS = [
  '1',
  'ABC2',
  'DEF3',
  'GHI4',
  'JKL5',
  'MNO6',
  'PQRS7',
  'TUV8',
  'WXYZ9',
  '*',
  ' 0',
  '#'
]

karakter yang terpilih adalah “1”. Kemudian kita menunggu selama 500ms. Kita kemudian mengecek apakah nilai dari context.str adalah “1”. Kumpulan statements tersebut menguji fungsionalitas 1 dan 3.

Kemudian, pada statements berikut:

fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(200);
fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(200);
fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(200);
fsm.send({ type: "KEY.PRESSED", key: 1 });
await waitFor(500);

expect(fsm.getSnapshot().context.str).toBe("12");

Kita mengirim event “KEY.PRESSED” sebanyak 4 kali dengan key “1”. Untuk memastikan karakter hanya ditambahkan setelah 500ms, setiap kali memencet tombol dengan key “1” kita menunggu selama 200ms. Kita tahu bahwa tombol dengan key “1” akan mengacu pada grup karakter kedua, 'ABC2'. Memencet sebanyak 4 kali dalam sebelum 500ms terpenuhi akan membuat karakter yang dipilih adalah karakter ke-4, yaitu “2”.

Di akhir statement, kita menguji apakah karakter “2” sudah ditambahkan ke str yang sudah ada sehingga nilai str saat ini harusnya adalah “12”.

Yang terakhir, kita menguji fungsionalitas 4:

it("pressing different key will added the current key to string", async () => {
  const fsm = interpret(phoneKeypadMachine).start();

  fsm.send({ type: "KEY.PRESSED", key: 0 });

  fsm.send({ type: "KEY.PRESSED", key: 1 });

  fsm.send({ type: "KEY.PRESSED", key: 2 });

  await waitFor(500);

  expect(fsm.getSnapshot().context.str).toBe("1AD");
});

Yang kita lakukan pada test case di atas kurang lebih sama dengan apa yang kita lakukan pada test case sebelumnya. Kita menginterpretasikan FSM, menjalankan actor dari FSM, dan mengirim events sesuai dengan ketentuan fungsionalitas.

Kita bisa menjalankan test dengan menggunakan Jest. Pertama buka terminal dan jalankan perintah berikut:

yarn test phoneKey.fsm

Jika semua berjalan lancar, seharusnya terminal kamu menampilkan pesan berikut:

 PASS  src/features/phoneKeypad/phoneKey.fsm.spec.ts
  phoneKeypad
    ✓ should be able to type using the keys (1628 ms)
    ✓ pressing different key will added the current key to string (508 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.962 s

Semua fungsionalitas sudah diuji hanya melalui state machine! Sekarang, saatnya mengintegrasikan FSM dengan UI!

Mengintegrasikan FSM ke UI

Saya membuat file bernama PhoneKeypad.tsx yang nantinya akan di-import ke dalam halaman Next.js.

Berikut adalah UI component tanpa integrasi dengan FSM:

"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";

export function PhoneKeypad() {
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            Text will be displayed here...
            {/* TODO: Add current str value */}
            {/* TODO: Add current selected character preview */}
            {/* TODO: Add blinking caret */}
          </p>
        </div>
        {PHONE_KEYS.map((key, index) => (
          <button
            key={index}
            className={[
              "w-[90px] h-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center",
              "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
            ].join(" ")}
            style={{
              userSelect: "none",
            }}
            // TODO: add "KEY.PRESSED" event
            onClick={() => {}}
          >
            <p className="text-2xl">{key[key.length - 1]}</p>
            <div className="gap-1 flex">
              <span>{key}</span>
            </div>
          </button>
        ))}
      </div>
    </div>
  );
}

Potongan kode di atas mencakup placeholder untuk teks yang diinput oleh user dan tombol-tombol yang akan mengirim “KEY.PRESSED” event.

Mengintegrasikan FSM ke React component

Pertama, kita import hooks untuk mengintegrasikan XState ke React component. Di sini saya menggunakan useInterpret dan useSelector. Di XState 4, useInterpret adalah hook yang mengembalikan sebuah “actor” atau “service” berdasarkan state machine yang diberikan. Berbeda dengan interpet yang kita gunakan pada test, “service” yang dikembalikan akan otomatis dimulai dan dijalankan selama masa hidup React component.

useInterpret mengembalikan static reference dari FSM ke React component yang hanya digunakan untuk menginterpretasikan FSM. Berbeda dengan useMachine yang akan mengalirkan seluruh pembaruan ke React component yang mengakibatkan re-render setiap pembaruan, pembaruan pada FSM yang digunakan oleh useInterpret tidak akan mengakibatkan re-render pada React component.

Lalu bagaimana kita bisa mendapatkan state terbaru dari FSM? Kita bisa menggunakan hooks useSelector untuk memilih bagian apa saja dari FSM yang ingin kita perhatikan dan mengakibatkan re-render pada component kita.

Untuk kasus ini, setidaknya ada 4 hal yang ingin kita lacak:

Context currentCharacterGroupIndex dan currentCharacterIndex untuk menampilkan karakter yang sedang dipilih saat ini
Context str untuk menampilkan teks yang sudah dibuat
State isIdle yang digunakan untuk menampilkan “cursor” atau “caret” yang menandakan machine lagi menunggu input dari user.

Berikut adalah cara menggunakan useInterpret dan useSelector :

export function PhoneKeypad() {
  // ...
  const fsm = useInterpret(phoneKeypadMachine);
  const { currentCharacterGroupIndex, currentCharacterIndex, value, isIdle } = useSelector(
    fsm,
    (state) => ({
      currentCharacterGroupIndex: state.context.currentCharacterGroupIndex,
      currentCharacterIndex: state.context.currentCharacterIndex,
      value: state.context.str,
      isIdle: state.matches("Idle"),
    })
  );

  // ...
}

Kemudian, kita bisa menggunakan value untuk menyelesaikan TODO pertama, “Add current str value”

"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";

export function PhoneKeypad() {
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {/* TODO: Add current str value */}
            {value}
            {/* TODO: Add current selected character preview */}
            {/* TODO: Add blinking caret */}
          </p>
        </div>
        {/* ... */}
      </div>
    </div>
  );
}

TODO yang kedua, “Add current selected character preview”, diselesaikan dengan menambahkan preview karakter menggunakan currentCharacterGroupIndex dan currentCharacterIndex

// ...
export function PhoneKeypad() {
  // ...
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {/* TODO: Add current str value */}
            {value}
            {/* TODO: Add current selected character preview */}
            {selectedIndex != undefined &&
              selectedIndexElement != undefined && (
                <span>{PHONE_KEYS[selectedIndex][selectedIndexElement]}</span>
              )}
            {/* TODO: Add blinking caret */}
          </p>
        </div>
        {/* ... */}
      </div>
    </div>
  );
}

Yang terakhir, untuk menandakan kita akan menambahkan teks di akhir teks, kita bisa menambahkan caret atau cursor ketika FSM sedang berada dalam state “Idle”

// ...
import classes from "./phoneKeypad.module.css";

// ...
export function PhoneKeypad() {
  // ...
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {/* TODO: Add current str value */}
            {value}
            {/* TODO: Add current selected character preview */}
            {selectedIndex != undefined &&
              selectedIndexElement != undefined && (
                <span>{PHONE_KEYS[selectedIndex][selectedIndexElement]}</span>
              )}
            {/* TODO: Add blinking caret */}
            <span
              className={[classes.blinkingCaret, isIdle ? "" : "hidden"].join(
                " "
              )}
            >
              |
            </span>
          </p>
        </div>
        {/* ... */}
      </div>
    </div>
  );
}

Saya juga membuat sebuah CSS modules yang akan membuat “caret” berkedip setiap 500ms:

/* phoneKeypad.module.css */
.blinkingCaret {
  animation: blink 500ms infinite;
}

@keyframes blink {
  50% {
    opacity: 0;
  }
}

Yang terakhir, kita mengirim event “KEY.PRESSED” ketika tombol dipencet:

"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";
import { phoneKeypadMachine } from "./phoneKeypad.fsm";
import classes from "./phoneKeypad.module.css";

export function PhoneKeypad() {
  // ...

  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        {/* ... */}
        {PHONE_KEYS.map((key, index) => (
          <button
            key={index}
            className={[
              "w-[90px] h-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center",
              "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
            ].join(" ")}
            style={{
              userSelect: "none",
            }}
            // TODO: add "KEY.PRESSED" event
            onClick={() => fsm.send({ type: "KEY.PRESSED", key: index })}
          >
            <p className="text-2xl">{key[key.length - 1]}</p>
            <div className="gap-1 flex">
              <span>{key}</span>
            </div>
          </button>
        ))}
      </div>
    </div>
  );
}

Berikut adalah potongan kode keseluruhan:

"use client";

import { useInterpret, useSelector } from "@xstate/react";
import { PHONE_KEYS } from "./constant";
import { phoneKeypadMachine } from "./phoneKeypad.fsm";
import classes from "./phoneKeypad.module.css";

export function PhoneKeypad() {
  const fsm = useInterpret(phoneKeypadMachine);
  const { selectedIndex, selectedIndexElement, value, isIdle } = useSelector(
    fsm,
    (state) => ({
      selectedIndex: state.context.currentCharacterGroupIndex,
      selectedIndexElement: state.context.currentCharacterIndex,
      value: state.context.str,
      isIdle: state.matches("Idle"),
    })
  );

  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        <div className="w-full border border-solid col-span-3 h-[50px] max-w-[332px] flex justify-start items-center px-4">
          <p className="max-w-full overflow-x-auto flex-nowrap whitespace-nowrap">
            {value}
            {selectedIndex != undefined &&
              selectedIndexElement != undefined && (
                <span>{PHONE_KEYS[selectedIndex][selectedIndexElement]}</span>
              )}
            <span
              className={[classes.blinkingCaret, isIdle ? "" : "hidden"].join(
                " "
              )}
            >
              |
            </span>
          </p>
        </div>
        {PHONE_KEYS.map((key, index) => (
          <button
            key={index}
            className={[
              "w-[90px] h-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center",
              "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
            ].join(" ")}
            style={{
              userSelect: "none",
            }}
            onClick={() => fsm.send({ type: "KEY.PRESSED", key: index })}
          >
            <p className="text-2xl">{key[key.length - 1]}</p>
            <div className="gap-1 flex">
              <span>{key}</span>
            </div>
          </button>
        ))}
      </div>
    </div>
  );
}

Jika kita menjalankan aplikasi ini, kurang lebih akan seperti ini:

Manfaat dari testing

Misalnya, aplikasi ini sudah di-ship dan kita sudah bisa melanjutkan hidup dengan tenang. Tapi, pada suatu hari, ada permintaan untuk menambah fitur!

User bisa menulis teks tapi tidak bisa menghapusnya!

Kita bisa bilang, ada tambahan fungsionalitas baru, “User bisa menghapus teks”.

Apa yang bisa kita lakukan untuk menyelesaikan fungsionalitas ini?

Menambahkan fungsionalitas hapus ke FSM

Yang pertama tentunya menambahkan fungsi hapus. Di sini, saya menambahkan event baru bernama “DELETE.PRESSED” yang bisa dikirim ketika FSM sedang berada dalam keadaan “Idle”

Event ini akan memicu action bernama “onDeleteLastChar“ yang akan menghapus karakter terakhir yang ada pada str.

Apakah kita langsung menambahkan event ini ke dalam UI? Tentu tidak!

Menambahkan test case baru

Setelah menambahkan fungsionalitas hapus pada FSM, kita perlu menulis test. Berikut test case yang saya tulis untuk menguji fungsionalitas ini:

describe("phoneKeypad", () => {
  // ...
  it("pressing delete will remove the last char", async () => {
    const fsm = interpret(phoneKeypadMachine.withConfig({})).start();

    fsm.send({ type: "KEY.PRESSED", key: 0 });

    fsm.send({ type: "KEY.PRESSED", key: 1 });

    fsm.send({ type: "KEY.PRESSED", key: 2 });

    await waitFor(500);
    expect(fsm.getSnapshot().context.str).toBe("1AD");

    fsm.send({ type: "DELETE.PRESSED" });
    expect(fsm.getSnapshot().context.str).toBe("1A");

    fsm.send({ type: "DELETE.PRESSED" });
    fsm.send({ type: "DELETE.PRESSED" });
    expect(fsm.getSnapshot().context.str).toBe("");
  });
});

Untuk memastikan bahwa test ini berhasil dan test cases sebelumnya juga berhasil, buka terminal dan jalankan kembali perintah berikut:

yarn test phoneKey.fsm

Jika semua berjalan lancar, seharusnya terminal kamu menampilkan pesan berikut:

 PASS  src/features/phoneKeypad/phoneKey.fsm.spec.ts
  phoneKeypad
    ✓ should be able to type using the keys (1626 ms)
    ✓ pressing different key will added the current key to string (507 ms)
    ✓ pressing delete will remove the last char (514 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        4.621 s

Hal yang saya sukai dari adanya test adalah saya bisa memastikan apakah seluruh fungsionalitas yang sudah ada tetap berjalan sesuai dengan test cases yang sudah ditulis. Jika memang ada perubahan terhadap fungsionalitas, tentunya test cases juga harus ikut berubah dan menyesuaikan. Tapi jika tidak, saya tetap bisa menggunakan test cases yang sama!

Menambahkan tombol hapus

Yang terakhir, kita hanya perlu menambahkan tombol untuk mengirim event “DELETE.PRESSED“ dari UI

// ...
export function PhoneKeypad() {
  // ...
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <div className="grid grid-cols-3 gap-4">
        {/* ... */}
        <button
          className={[
            "col-start-3 col-end-3",
            "w-[90px] rounded-lg bg-gray-100 flex flex-col justify-center items-center py-4",
            "hover:bg-gray-200 cursor-pointer active:bg-gray-300",
          ].join(" ")}
          onClick={() => fsm.send({ type: "DELETE.PRESSED" })}
        >
          DEL
        </button>
        {PHONE_KEYS.map((key, index) => (
          // ...
        ))}
      </div>
    </div>
  );
}

Aplikasi kita sekarang terlihat seperti ini:

Penutup

Di tulisan ini, saya sudah bercerita tentang bagaimana saya menguji FSM yang sudah saya buat dengan XState4 secara imperatif menggunakan Jest. Dengan menulis test, kita punya kepercayaan diri bahwa setidaknya FSM yang kita buat sudah berjalan sesuai dengan test cases yang diberikan.

Perlu diingat, XState versi 5 (terbaru) memiliki API yang sedikit berbeda tetapi prinsipnya kurang lebih sama. Selain itu, XState juga menyediakan package untuk melakukan pengujian dengan pendekatan model-based testing. Package tersebut juga bisa membuat test cases secara otomatis berdasarkan definisi state machine yang diberikan!

Terima kasih sudah membaca tulisan saya! Have a nice day!

Create a finite state machine using XState

Ibé Dwi — Sun, 17 Dec 2023 09:00:44 +0000

NOTE: When this article was written, I was still using XState version 4. I might write about changes or differences between XState version 4 and 5. But fundamentally, the concepts used are the same

In this article, I want to share about finite state machines (FSM) and how to create a finite state machine using XState. I also share the final results of the project mentioned in this article at the following link.

Setting Up the Project

I am using Next.js 13 with the app directory and TailwindCSS. A tutorial on creating a Next.js project with an app router can be found at this link.

What is your project named? logs-understanding-fsm-with-xstate
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias (@/*)? Yes
What import alias would you like configured? @/*

Another libraries needed will be introduced in the related subchapter.

What is a Finite State Machine?

What is a finite state machine? The way I understand this term is by trying to dissect and understand each word in the term:

Machine

Here, 'Machine' refers to 'a model of a system.' The model itself can be interpreted as an informative representation of something (basically, a representation of a system).

State

In this context, 'State' refers to information. In particular, the information in question is “the behavior of a system”.

When these two words are combined, 'state machine' can be understood as a representation of a system's behavior. A state machine, of course, consists of a list of its behaviors. A state machine also describes the transition from one state to another. These transitions are triggered by inputs given to the state machine.

The last word, 'finite,' implies that the number of states within the state machine is limited

Modeling a Fan's Finite State Machine

Given that the weather where I live is hot while I am writing this article, we will use a fan as a case study. We will create a model of the fan using an FSM.

Installing XState

Before we start modeling the FSM of the fan, we first need to install some libraries related to finite state machines

yarn add xstate@^4.38.1 @xstate/react@^3.2.2

VSCode Extension

For easier development, I use the Stately extension in VSCode. This extension greatly facilitates FSM modeling because it uses a GUI.

Modeling the FSM of a Fan

To create an FSM with XState, we can use the createMachine function.

import { createMachine } from "xstate";
export const fanMachine = createMachine({
  id: "fan",
});

The id property is used to identify the machine we create.

To model how a fan works, we can start with the question: 'What are the states of a fan?'. Simple, stop andspin. stop means our fan is not spinning, while spin means it is spinning. Essentially, there are states when the fan is on and off. We can write the states of this fan into our machine definition as follows:

import { createMachine } from "xstate";

export const fanMachine = createMachine({
  id: "fan",

  states: {
    stop: {},
    spin: {},
  },

  initial: "off",
});

The states property lists all the states that our machine possesses, and the initial property determines the initial state when the machine is first run.

Now, our machine has states. But, we have not yet determined how our machine can transition from the stop state to spin.

(Tips) TypeScript Support (you can skip this part if you’re not using TypeScript)

If you are also using TypeScript, XState provides a types generator (typegen) for our machine. According to this documentation, VSCode users only need to install an extension.

Then, in our state machine definition, we just need to add the property tsTypes: {}. When we save this file, typings from our state machine will automatically be created.

State Transitions

In XState, the transition from one state to another is triggered by an event. Here, event is equivalent to the 'input' we referred to in the earlier section about the concept of FSM.

For our case, the transitions we need are from the stop state to the spin state and vice versa. These transitions are triggered by the user turning the fan on or off. In XState, we can write these transitions in the on property of a state:

export const fanMachine = createMachine({
  id: "fan",

  states: {
    stop: {
      on: {
        "USER.PRESS.ON": "spin",
      },
    },

    spin: {
      on: {
        "USER.PRESS.OFF": "stop",
      },
    },
  },

  initial: "stop",
});

Essentially, the transition in the stop state can be read as: 'When USER.PRESS.ON, transition to spin.

What’s interesting about XState is that we can use any string value as the name for the event. Here, I use a convention where action names are written in uppercase and each word is separated by a dot instead of a space.

To generate better typings, we can define any event recognized by our machine. For example:

type MachineEvent = { type: "USER.PRESS.ON" } | { type: "USER.PRESS.OFF" };

export const fanMachine = createMachine({
  id: "fan",
  tsTypes: {} as import("./fanMachine.fsm.typegen").Typegen0,
  schema: {
    events: {} as MachineEvent,
  },
  // ...
});

Enriching the State Machine with Additional Information

We have successfully made our fan turn on and off. But, what about the fan's rotation speed? In XState, additional information (or simply, data) known to the machine is stored in the context.

In our case, the additional information needed is the speed of the fan.

We can add speed to the context property:

export const fanMachine = createMachine({
  id: "fan",
  context: {
    fanSpeed: 0,
  },
  // ...
});

We can also create type for the context and add it to the schema:

type MachineContext = {
  fanSpeed: number;
};

// ...

export const fanMachine = createMachine({
  id: "fan",
  schema: {
    events: {} as MachineEvent,
    context: {} as MachineContext,
  },
  // ...
});

Now, our machine has additional information, fanSpeed, stored in the context.

Changing the Context Value with an Action

So far, we have added the fan's speed, fanSpeed, to the machine through the context. But, when the state transitions from stop to spin, our fan's fanSpeed is still 0!

To change the context value, we can utilize one of XState's features, namely “action”.

In XState, an action is a form of side-effect that can be triggered. When is an action triggered? An action can be triggered during state transitions, either on entering or exiting a state, or by an event. An action in XState is a pure function; it is generally synchronous. We can use an action to change the context value.

Adding `action` to an `event`

First, let's update the event we send during the transition from stop to spin and vice versa to trigger an action that will change the value of fanSpeed. Let's name this action changeFanSpeed. This action is added to the actions property within the event.

export const fanMachine = createMachine({
  id: "fan",
  // ...
  states: {
    stop: {
      on: {
        "USER.PRESS.ON": {
          target: "spin",
          // v let's add action here!
          actions: "changeFanSpeed",
        },
      },
    },

    spin: {
      on: {
        "USER.PRESS.OFF": {
          target: "stop",
          // v let's add action here!
          actions: "changeFanSpeed",
        },
      },
    },
  },
  // ...
});

Writing the Implementation of the `changeFanSpeed` action

The next step is to write the implementation of the changeFanSpeed action.

According to its documentation, the createMachine function accepts two arguments, the first being the machine configuration and the second the options. One of the properties of options is actions, where we write the implementation of actions. Almost every property in options — whether guards, actions, or services — that is a function, will receive two arguments in order: the context when the action is triggered and the event that triggers the action. We can write the changeFanSpeed action like this:

export const fanMachine = createMachine(
  {
    // ...
  },
  {
    actions: {
      changeFanSpeed: (_context, event) => {
        /* implementation goes here */
      },
    },
  }
);

However, to change the context, we need a built-in action from XState called the “assign action”. Simply put, the assign action is a function that receives a new value to be applied to the context and sets this value within the context. If the latest context value we want is the result of an action, we simply wrap that action using the assign function.

import { assign } from "xstate";

export const fanMachine = createMachine(
  {
    // ...
  },
  {
    actions: {
      changeFanSpeed: assign((_context, event) => {
        /* implementation goes here */
      }),
    },
  }
);

For example, if the fanSpeed value when the fan is first turned on is 1. We can write the assign action changeFanSpeed like this:

export const fanMachine = createMachine(
  {
    id: "fan",
    // ...
    states: {
      stop: {
        on: {
          "USER.PRESS.ON": {
            target: "spin",
            actions: "changeFanSpeed",
          },
        },
      },

      spin: {
        on: {
          "USER.PRESS.OFF": {
            target: "stop",
            actions: "changeFanSpeed",
          },
        },
      },
    },
    // ...
  },
  {
    actions: {
      changeFanSpeed: assign((_context, event) => {
        if (event.type === "USER.PRESS.ON") {
          return {
            fanSpeed: 1,
          };
        }
        if (event.type === "USER.PRESS.OFF") {
          return {
            fanSpeed: 0,
          };
        }
        return {};
      }),
    },
  }
);

Now, we have our fan FSM!

Next, one of the equally exciting parts: integrating the FSM we have created into the UI!

If you are also using the VSCode extension, our FSM currently looks something like this:

Integrating the State Machine into the UI

Before proceeding, we need to install some libraries first:

yarn add framer-motion@^10.16.12 react-icons@^4.12.0

Integrating the FSM into a React Component

First, let's create a component named Fan.tsx. This component can be considered as the visual representation of the fan.

In XState, the machine we have defined, fanMachine, can be seen as the definition of a process. The process that runs based on our definition is referred to as a “service” or “actor”. Lately, the term “actor” seems to be used more often.

XState provides a hook called useMachine to create an actor (process) from our defined machine. This hook returns a tuple, containing information about the running actor in the form of an object, a function to send events to the actor, and a reference to the created actor. Additionally, this hook also binds the actor to the component's lifecycle. So when the component is unmounted, the actor will stop and will start again (from the initial state) when the component is mounted.

export function Fan() {
  const [fsmState, fsmSendEvent] = useMachine(fanMachine);

  const isOn = fsmState.matches("spin");
  const speed = fsmState.context.fanSpeed;

  return <div>{/* ... */}</div>;
}

isOn stores the result of the matches method. This method is used to ensure whether the current state of the actor matches the given argument. To access the context, we can use the context property from the information obtained from the tuple returned by the useMachine hook, fsmState.

Creating the UI

Here is a simple UI that represents the fan:

// utils to merge an array of `className`s
function cn(...classes: any[]) {
  return classes.filter(Boolean).join(" ");
}

export function Fan() {
  // ...
  return (
    <div className="flex flex-col items-stretch py-3 px-4 bg-gray-200 rounded-lg gap-5">
      <div>
        <FaDotCircle
          className={cn("text-md", isOn ? "text-green-400" : "text-red-400")}
        />
      </div>
      <FaFan className="text-8xl text-gray-500" />
      <div className="flex flex-row item-center justify-between w-full gap-[150px]">
        <button
          className={cn(
            "p-2 rounded-lg",
            !isOn ? "bg-red-300 text-white" : "bg-red-400 text-black"
          )}
        >
          Off
        </button>
        <button
          className={cn(
            "p-2 rounded-lg",
            isOn ? "bg-green-300 text-white" : "bg-green-400 text-black"
          )}
        >
          On
        </button>
      </div>
    </div>
  );
}

Sending `events` to the `actor`

Our UI is now complete, and we want to be able to send events to the actor we have created. We can use fsmSendEvent, which we obtained earlier. (One of the things I like most is the IDE suggestions when writing the event we want to send).

export function Fan() {
  // ...
  return (
    <div className="flex flex-col items-stretch py-3 px-4 bg-gray-200 rounded-lg gap-5">
      {/* ... */}
      <div className="flex flex-row item-center justify-between w-full gap-[150px]">
        <button
          // ...
          onClick={() => fsmSendEvent({ type: "USER.PRESS.OFF" })}
        >
          Off
        </button>
        <button
          // ...
          onClick={() => fsmSendEvent({ type: "USER.PRESS.ON" })}
        >
          On
        </button>
      </div>
    </div>
  );
}

Just by sending events, our fan machine is now integrated with our React component! But there's one more thing missing, which is animation. Don't worry, it won't take long ;)

Adding Fan Rotation Animation

For the animation part, we use framer-motion. We want to rotate the fan blades based on whether it's on or off and at the predetermined speed. Considering this article is not about animation, I won't go into a lengthy explanation of how to use framer-motion in detail.

export function Fan() {
  // animation values
  const calculatedSpeed = isOn ? 1000 - 100 * speed : 0;
  const time = useTime();
  const rotate = useTransform(
    time,
    [0, calculatedSpeed], // For every calculatedSpeed,
    [0, -360], // rotate 360 degrees to the left direction
    {
      clamp: false, // make it rotate forever
    }
  );

  return (
    <div className="flex flex-col items-stretch py-3 px-4 bg-gray-200 rounded-lg gap-5">
      <motion.div
        style={{ rotate }}
        className="flex justify-center items-center"
      >
        <FaFan className="text-8xl text-gray-500" />
      </motion.div>
      {/* ... */}
    </div>
  );
}

In the above lines of code, we use the rotate generated from the useTransform hook of framer motion.

Demo

Summary

In this article, we have learned about the concept of finite state machines and their implementation using XState in Next.js.

I personally believe that XState is a useful library in complex situations.

Thank you for reading!

🇮🇩 Membuat FSM dengan XState

Ibé Dwi — Thu, 07 Dec 2023 06:27:05 +0000

NOTE:
Ketika tulisan ini dibuat, saya masih menggunakan XState versi 4. Saya mungkin akan menuliskan perubahan atau perbedaan antara XState versi 4 dan 5. Tapi pada dasarnya, konsep yang digunakan sama.

Di tulisan ini, saya ingin berbagi tentang finite state machine dan bagaimana membuat FSM dengan XState. Saya juga membagikan hasil akhir dari project yang ada di tulisan ini di link berikut.

Menyiapkan project

Saya menggunakan Next.js 13 dengan app directory dan TailwindCSS. Tutorial membuat project Next.js dengan app router dapat ditemukan di link ini.

What is your project named? logs-understanding-fsm-with-xstate
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias (@/*)? Yes
What import alias would you like configured? @/*

Libraries lain yang dibutuhkan akan saya jelaskan pada subbab terkait.

Apa itu Finite State Machine?

Apa itu finite state machine? Cara saya memahami istilah ini adalah dengan mencoba membedah dan memahami tiap kata yang ada dalam istilah ini:

Machine
Machine di sini merujuk kepada “a model of a system”. Model sendiri bisa diartikan sebagai sebuah representasi yang informatif dari sesuatu (yaa intinya representasi dari sistem).

State
State di sini merujuk kepada informasi. Lebih spesifik lagi, informasi yang dimaksud adalah behavior (perilaku atau tingkah laku) dari sebuah system.

Jika dua kata ini digabungkan, “state machine” dapat dipahami sebagai representasi dari behavior sebuah system. Sebuah state machine, tentunya terdiri dari daftar tingkah lakunya. State machine juga mendeskripsikan transisi dari satu state ke state lain. Transisi ini dipicu oleh input yang diberikan kepada state machine tersebut.

Kata terakhir, “finite”, memiliki makna bahwa state yang ada di dalam state machine jumlahnya terbatas.

Memodelkan finite state machine kipas angin

Berhubung cuaca di tempat saya tinggal saat menulis tulisan ini sedang panas, maka kita akan menggunakan kipas angin sebagai contoh kasus. Kita akan membuat model kipas angin dengan menggunakan FSM.

Memasang XState

Sebelum mulai memodelkan FSM kipas angin, kita harus meng-install beberapa libraries yang berkaitan dengan finite state machine terlebih dahulu:

yarn add xstate@^4.38.1 @xstate/react@^3.2.2

VSCode Extension

Untuk kemudahan development, saya menggunakan extension Stately di VSCode. Extension ini sangat memudahkan dalam memodelkan FSM karena menggunakan GUI.

Pemodelan FSM kipas angin

Untuk membuat sebuah FSM dengan XState, kita bisa menggunakan fungsi createMachine:

import { createMachine } from "xstate";
export const fanMachine = createMachine({
  id: "fan",
});

Property id digunakan untuk mengidentifikasi mesin yang kita buat.

Untuk memodelkan bagaimana sebuah kipas angin bekerja, kita bisa mulai dengan pertanyaan: “apa saja state dari sebuah kipas angin?”. Mudah, stop dan spin. stop artinya kipas angin kita tidak berputar, sedangkan spin artinya berputar. Intinya ada keadaan ketika kipas angin menyala dan mati. Kita bisa menuliskan state dari kipas angin ini ke dalam definisi machine kita sebagai berikut:

import { createMachine } from "xstate";

export const fanMachine = createMachine({
  id: "fan",

  states: {
    stop: {},
    spin: {},
  },

  initial: "off",
});

Property states adalah daftar state apa saja yang dimiliki oleh machine kita dan property initial menentukan state awal saat machine pertama kali dijalankan.

Sekarang, machine kita sudah punya state. Tapi, kita belum menentukan bagaimana machine kita bisa berpindah dari state stop ke spin.

(Tips) Typescript support (you can skip this part if you’re not using TypeScript)

Jika kamu juga menggunakan TypeScript, XState menyediakan types generator (typegen) dari machine kita. Berdasarkan dokumentasi ini, pengguna VSCode hanya perlu meng-install sebuah extension.

Lalu di dalam definisi state machine kita, kita hanya perlu menambahkan property tsTypes: {}. Ketika kita menyimpan file tersebut, typings dari state machine kita akan otomatis terbuat.

Transisi `state`

Dalam XState, transisi dari sebuah state ke state lain dipicu oleh sebuah event. event di sini sepadan dengan “input” yang kita singgung pada bagian pengertian FSM di atas.

Untuk kasus kita, transisi yang kita butuhkan untuk berpindah adalah transisi state stop ke spin dan sebaliknya. Transisi ini dipicu oleh user yang menyalakan atau mematikan kipas angin. Dalam XState, kita bisa menulis transisi ini pada property on dari sebuah state:

export const fanMachine = createMachine({
  id: "fan",

  states: {
    stop: {
      on: {
        "USER.PRESS.ON": "spin",
      },
    },

    spin: {
      on: {
        "USER.PRESS.OFF": "stop",
      },
    },
  },

  initial: "stop",
});

Kurang lebih, transisi pada state stop bisa dibaca: “Ketika USER.PRESS.ON, transisi ke spin”.

Yang menarik dari XState, kita bisa menggunakan nilai string apa saja sebagai nama nilai EVENT. Di sini saya menggunakan convention nama aksi yang ditulis dalam uppercase dan tiap kata dipisahkan oleh titik alih-alih oleh spasi.

Untuk menghasilkan generated typings yang lebih baik, kita bisa menuliskan EVENT apa saja yang dikenali oleh machine kita. Misalnya:

type MachineEvent = { type: "USER.PRESS.ON" } | { type: "USER.PRESS.OFF" };

export const fanMachine = createMachine({
  id: "fan",
  tsTypes: {} as import("./fanMachine.fsm.typegen").Typegen0,
  schema: {
    events: {} as MachineEvent,
  },
  // ...
});

Memperkaya state machine dengan informasi tambahan

Kita sudah berhasil membuat kipas angin kita menyala dan mati. Tapi, bagaimana dengan kecepatan putaran kipas? Di XState, informasi tambahan (atau sederhananya, data) yang diketahui oleh machine disimpan ke dalam context.

Dalam kasus kita, informasi tambahan yang dibutuhkan adalah kecepatan dari kipas.

Kita bisa menambahkan kecepatan ke dalam property context:

export const fanMachine = createMachine({
  id: "fan",
  context: {
    fanSpeed: 0,
  },
  // ...
});

Kita juga bisa membuat type untuk context dan menambahkannya ke dalam schema:

type MachineContext = {
  fanSpeed: number;
};

// ...

export const fanMachine = createMachine({
  id: "fan",
  schema: {
    events: {} as MachineEvent,
    context: {} as MachineContext,
  },
  // ...
});

Sekarang, machine kita memilki informasi tambahan, fanSpeed, yang disimpan di dalam context.

Mengubah nilai dari `context` dengan `action`

Sejauh ini, kita sudah menambahkan kecepatan kipas, fanSpeed , ke dalam machine melalui context. Tapi, ketika state transisi dari stop ke spin, fanSpeed dari kipas angin kita masih 0!

Untuk merubah nilai dari context, kita bisa memanfaatkan salah satu fitur dari XState, yaitu action.

Di XState, action adalah salah satu bentuk side-effect yang bisa di-trigger. Kapan action ke-trigger? action bisa di-trigger ketika perpindahan state, yaitu ketika masuk atau keluar state, atau di-trigger oleh event. action dalam XState adalah pure function; umumnya bersifat synchronous. Kita bisa menggunakan action untuk merubah nilai dari context.

Menambahkan `action` pada `event`

Pertama, mari kita update event yang kita kirim ketika transisi dari stop ke spin dan sebaliknya untuk memicu action yang akan merubah nilai dari fanSpeed. Mari kita beri nama action ini changeFanSpeed. action ini ditambahkan pada property actions yang ada di dalam event.

export const fanMachine = createMachine({
  id: "fan",
  // ...
  states: {
    stop: {
      on: {
        "USER.PRESS.ON": {
          target: "spin",
          // v let's add action here!
          actions: "changeFanSpeed",
        },
      },
    },

    spin: {
      on: {
        "USER.PRESS.OFF": {
          target: "stop",
          // v let's add action here!
          actions: "changeFanSpeed",
        },
      },
    },
  },
  // ...
});

Menulis implementasi dari `action` `changeFanSpeed`

Langkah selanjutnya adalah menuliskan implementasi dari action changeFanSpeed.

Berdasarkan dokumentasinya, fungsi createMachine menerima 2 argumen, yang pertama adalah konfigurasi machine dan yang kedua adalah options. Salah satu property dari options adalah actions, tempat di mana kita menuliskan implementasi dari actions. Hampir setiap property yang ada di options — entah itu guards, actions, atau services — yang berbentuk fungsi, akan menerima 2 argumen secara berurutan yaitu context saat action tersebut di-trigger dan event yang men-trigger action tersebut. Kita dapat menuliskan action changeFanSpeed seperti ini:

export const fanMachine = createMachine(
  {
    // ...
  },
  {
    actions: {
      changeFanSpeed: (_context, event) => {
        /* implementation goes here */
      },
    },
  }
);

Tetapi, untuk merubah context, kita butuh built-in action dari XState yang disebut “assign action”. Sederhananya, assign action ini adalah fungsi yang menerima nilai baru yang akan diterapkan ke context dan akan menetapkan nilai tersebut ke dalam context. Jika nilai dari context terbaru yang kita inginkan adalah hasil dari action , kita cukup membungkus action tersebut ke menggunakan fungsi assign.

import { assign } from "xstate";

export const fanMachine = createMachine(
  {
    // ...
  },
  {
    actions: {
      changeFanSpeed: assign((_context, event) => {
        /* implementation goes here */
      }),
    },
  }
);

Misal, nilai fanSpeed ketika kipas angin pertama kali dinyalakan adalah 1. Kita bisa menuliskan assign action changeFanSpeed seperti ini:

export const fanMachine = createMachine(
  {
    id: "fan",
    // ...
    states: {
      stop: {
        on: {
          "USER.PRESS.ON": {
            target: "spin",
            actions: "changeFanSpeed",
          },
        },
      },

      spin: {
        on: {
          "USER.PRESS.OFF": {
            target: "stop",
            actions: "changeFanSpeed",
          },
        },
      },
    },
    // ...
  },
  {
    actions: {
      changeFanSpeed: assign((_context, event) => {
        if (event.type === "USER.PRESS.ON") {
          return {
            fanSpeed: 1,
          };
        }
        if (event.type === "USER.PRESS.OFF") {
          return {
            fanSpeed: 0,
          };
        }
        return {};
      }),
    },
  }
);

Sekarang, kita sudah memilki FSM kipas angin!

Selanjutnya, salah satu bagian yang tak kalah seru: mengintegrasikan FSM yang sudah kita buat ke UI!

Jika kamu juga menggunakan extension VSCode, FSM kita saat ini kurang lebih terlihat seperti ini:

Mengintegrasikan state machine ke UI

Sebelum melanjutkan, kita perlu meng-install beberapa libraries terlebih dahulu:

yarn add framer-motion@^10.16.12 react-icons@^4.12.0

Mengintegrasikan FSM ke React component

Pertama-tama, mari kita buat sebuah component bernama Fan.tsx. Component ini bisa dianggap sebagai representasi visual dari kipas angin.

Dalam XState, machine yang sudah kita definisikan, fanMachine , bisa dianggap sebagai definisi dari sebuah proses. Sedangkan proses yang berjalan berdasarkan definisi yang sudah kita buat disebut sebagian service atau actor. Beberapa waktu terakhir, saya rasa istilah actor lebih sering digunakan.

XState menyediakan hook bernama useMachine untuk membuat actor (proses) dari machine yang sudah kita definisikan. Hook ini mengembalikan tuple, yang berisi informasi dari actor yang sedang berjalan dalam bentuk object, fungsi untuk mengirim event ke actor, dan referensi ke actor yang sudah dibuat. Selain itu, hook ini juga mengikat actor ke dalam lifecycle dari component. Jadi ketika component di-unmount, actor akan berhenti dan akan mulai dari awal lagi (dari initial state) ketika component di-mount.

export function Fan() {
  const [fsmState, fsmSendEvent] = useMachine(fanMachine);

  const isOn = fsmState.matches("spin");
  const speed = fsmState.context.fanSpeed;

  return <div>{/* ... */}</div>;
}

isOn menyimpan hasil dari method matches. Method ini digunakan untuk memastikan apakahstate dari actor saat ini sesuai dengan argumen yang diberikan. Sedangkan untuk mengakses context, kita bisa menggunakan property context dari informasi yang kita dapatkan dari tuple yang dikembalikan oleh hook useMachine, fsmState.

Membuat UI

Berikut adalah UI sederhana yang menggambarkan kipas angin:

// utils to merge an array of `className`s
function cn(...classes: any[]) {
  return classes.filter(Boolean).join(" ");
}

export function Fan() {
  // ...
  return (
    <div className="flex flex-col items-stretch py-3 px-4 bg-gray-200 rounded-lg gap-5">
      <div>
        <FaDotCircle
          className={cn("text-md", isOn ? "text-green-400" : "text-red-400")}
        />
      </div>
      <FaFan className="text-8xl text-gray-500" />
      <div className="flex flex-row item-center justify-between w-full gap-[150px]">
        <button
          className={cn(
            "p-2 rounded-lg",
            !isOn ? "bg-red-300 text-white" : "bg-red-400 text-black"
          )}
        >
          Off
        </button>
        <button
          className={cn(
            "p-2 rounded-lg",
            isOn ? "bg-green-300 text-white" : "bg-green-400 text-black"
          )}
        >
          On
        </button>
      </div>
    </div>
  );
}

Mengirim `event` ke `actor`

UI kita sudah selesai dan sekarang kita ingin bisa mngirim event ke actor yang sudah kita buat. Kita bisa menggunakan fsmSendEvent yang sudah kita dapatkan sebelumnya. (Salah satu hal yang paling saya sukai adalah suggestions dari IDE ketika menuliskan event yang ingin kita kirim).

export function Fan() {
  // ...
  return (
    <div className="flex flex-col items-stretch py-3 px-4 bg-gray-200 rounded-lg gap-5">
      {/* ... */}
      <div className="flex flex-row item-center justify-between w-full gap-[150px]">
        <button
          // ...
          onClick={() => fsmSendEvent({ type: "USER.PRESS.OFF" })}
        >
          Off
        </button>
        <button
          // ...
          onClick={() => fsmSendEvent({ type: "USER.PRESS.ON" })}
        >
          On
        </button>
      </div>
    </div>
  );
}

Hanya dengan mengirim event, sekarang machine kipas angin sudah terintegrasi dengan React component kita! Tapi masih ada satu hal lagi yang kurang, yaitu animasi. Tenang, ini tidak akan lama ;)

Menambahkan animasi putaran kipas

Pada bagian animasi, kita menggunakan framer-motion. Kita ingin memutar baling-baling kipas berdasarkan kondisi menyala atau mati dengan kecepatan yang sudah ditentukan. Mengingat tulisan ini bukanlah tentang animasi, saya tidak akan memberikan penjelasan panjang lebar tentang bagaimana menggunakan framer-motion secara detail.

export function Fan() {
  // animation values
  const calculatedSpeed = isOn ? 1000 - 100 * speed : 0;
  const time = useTime();
  const rotate = useTransform(
    time,
    [0, calculatedSpeed], // For every calculatedSpeed,
    [0, -360], // rotate 360 degrees to the left direction
    {
      clamp: false, // make it rotate forever
    }
  );

  return (
    <div className="flex flex-col items-stretch py-3 px-4 bg-gray-200 rounded-lg gap-5">
      <motion.div
        style={{ rotate }}
        className="flex justify-center items-center"
      >
        <FaFan className="text-8xl text-gray-500" />
      </motion.div>
      {/* ... */}
    </div>
  );
}

Pada baris kode di atas, kita menggunakan rotate yang dihasilkan dari hook useTransform milik framer motion.

Demo

Loom

Summary

Di tulisan ini, kita sudah belajar tentang konsep finite state machine dan implementasinya menggunakan XState di Next.js.

Saya sendiri yakin bahwa XState adalah salah satu library yang bermanfaat dalam situasi yang kompleks.

Terima kasih sudah membaca!

First post in dev.to

Ibé Dwi — Sat, 07 Nov 2020 16:57:04 +0000

Whoa! I finally made a post in dev.to!
So excited! I promise myself to write more about front-end and software development related.

DEV Community: Ibé Dwi

Testing XState FSM using Jest

Case Study

Preparing the Project

Next.js

xstate & @xstate/react

jest & ts-jest

Folder Structure

Layering the application

Domain Layer

Representation of the keypad

Finite State Machine

Testing the FSM

Writing Test Cases

Integrating FSM into UI

Integrating Machine

Benefits of Testing

Adding Delete Functionality to the FSM

Adding a New Test Case

Adding a Delete Button

Conclusion

🇮🇩 Menguji FSM XState dengan Jest

Studi kasus

Menyiapkan Project

Next.js

xstate & @xstate/react

jest dan ts-jest

Struktur folder

Membuat lapisan aplikasi

Domain Layer - FSM

Representasi keypad (tombol)

Finite State Machine

Menguji FSM

Menulis test cases

Mengintegrasikan FSM ke UI

Mengintegrasikan FSM ke React component

Manfaat dari testing

Menambahkan fungsionalitas hapus ke FSM

Menambahkan test case baru

Menambahkan tombol hapus

Penutup

Create a finite state machine using XState

Setting Up the Project

What is a Finite State Machine?

Machine

State

Modeling a Fan's Finite State Machine

Installing XState

VSCode Extension

Modeling the FSM of a Fan

(Tips) TypeScript Support (you can skip this part if you’re not using TypeScript)

State Transitions

Enriching the State Machine with Additional Information

Changing the Context Value with an Action

Adding action to an event

Writing the Implementation of the changeFanSpeed action

Integrating the State Machine into the UI

Integrating the FSM into a React Component

Creating the UI

Sending events to the actor

Adding Fan Rotation Animation

Demo

Summary

🇮🇩 Membuat FSM dengan XState

Menyiapkan project

Apa itu Finite State Machine?

Memodelkan finite state machine kipas angin

Memasang XState

VSCode Extension

Pemodelan FSM kipas angin

(Tips) Typescript support (you can skip this part if you’re not using TypeScript)

Transisi state

Memperkaya state machine dengan informasi tambahan

Mengubah nilai dari context dengan action

Menambahkan action pada event

Menulis implementasi dari action changeFanSpeed

Mengintegrasikan state machine ke UI

Mengintegrasikan FSM ke React component

Membuat UI

Mengirim event ke actor

`xstate` & `@xstate/react`

`jest` & `ts-jest`

`xstate` & `@xstate/react`

`jest` dan `ts-jest`

Adding `action` to an `event`

Writing the Implementation of the `changeFanSpeed` action

Sending `events` to the `actor`

Transisi `state`

Mengubah nilai dari `context` dengan `action`

Menambahkan `action` pada `event`

Menulis implementasi dari `action` `changeFanSpeed`

Mengirim `event` ke `actor`