DEV Community: John

Supervising XState Machines with Redux

John — Wed, 10 Nov 2021 15:32:39 +0000

Redux introduced me to the concept of a single state store for managing a front-end application's state. It was a fantastic library to help maintain large and complex state in an app built with ReactJS. Combined with redux-saga for managing network requests and other side-effects it made a pretty powerful tool. However as soon I saw XState in action I dropped all my "religious" convictions about a single state store and was sold on the idea of statecharts.

In this post we are going to have our cake and eat it and use both Redux and XState. State machines lend themselves well for implementing the actor model and I thought Redux would be a good candidate to supervise messaging between running machines and rehydrating their state.

This article is a rewrite of a previous post that I wrote on the same topic.

The Store

Our Redux store state is an object where each key is a unique machine identifier and maps to a service. (In XState services are interpreted state machine configurations that handle incoming events and state transitions)

import * as X from "xstate";

type AnyService = X.Interpreter<any, any, any>;
type AnyMachine = X.StateMachine<any, any, any>;

/**
 * A machine is a machine attached to the event bus.
 */
type StoredMachine = {
  /** Unique identifier of the machine. Must be unique for the whole app. */
  id: string;
  /** A state machine. */
  machine: AnyMachine;
  /** A running service that has interpreted a state machine configuration.
   * Only available if the component needing it is live / renderered.
   * */
  service?: AnyService;
  /**
   * If a machine is not live but components are sending events to it
   * they will be parked here.
   **/
  eventQueue: AnyDispatchedEvent[];
  /** The most recent state of a machine live or not. */
  state: X.State<any, any, any, any>;
};

/**
 * Map of machine id's to [[StoredMachine]]. This is the Redux store state object
 */
type StoreState = Record<string, StoredMachine>;

The eventQueue is a nice feature we are including that will allow us to discard services when components unmount while still being able to send events to the machine. The events are queued up and sent to the machine once it comes back online.

Reducing machines and events

We'll need a reducer for StoredMachine that:

Can take an event
Send it to the related service if its running
and return the state of the machine

As mentioned, our Redux store will have the same reducer for each state entry since all our state entries are of the same type:

type AnyDispatchedEvent = Exclude<X.AnyEventObject, string> & { to: string | string[] }

/**
 * The only type of reducer you'll see here.
 * 
 * @param state A machine
 * @param event An event targetting this machine.
 */
const machineReducer = (state: Station, event: AnyDispatchedEvent): StoredMachine => {
  if (state.service) {
    // If the machine's service is live, fire away and compute it's next state.
    const next = state.service.send(event);

    // Only change the store if changes have occurred.
    if (next.changed) {
      return {
        ...state,
        state: next
      };
    }

    return state;
  } 

  // Queue the event. Event will be dispatched as soon as the machine is live.
  return {
    ...state,
    eventQueue: [...state.eventQueue, event]
  };
};

The only thing this reducer does is dispatch events to an interpreted machine's service or queue the events up if the service is offline (because no components are using the many anymore).

One reducer to rule them all.

The reducer we created is for each individual machine in the store. Redux needs a final single reducer. This reducer's state will be the map of machine id's and stored machines and process events and send them to the correct machine in the store.

2 other features I would like us to include:

A batched events feature. Being able to dispatch an array of events.
Target multiple machines (reducers) with one event.

Redux does not support dispatching an array of events so we'll create a special event typed "BATCHED" of which the payload is an array of events. Unlike regular Redux reducers our events are not sent to every reducer available to the store but specifically target individual reducers:

/**
 * Special events are:
 * 
 * `.type: "BATCHED"` - Handles batched event just like service.send;
 * `.type: "REGISTER_MACHINE" - Introduces a new machine to the bus;
 * 
 * For all other events, if a `.to` property is present targeting a specific
 * machine then the event is only sent to that machine.
 * 
 * ToDo: Could be an array of machine id's or an asterisk to target all.
 * 
 * The Redux store reducer.
 * @param state A map of machines
 * @param event Any event.
 */
const machinesReducer = (
  state: Stations = {},
  event: DispatchedSupervisedEvent
): Stations => {
  if (isBatchedEvent(event)) {
    return event.events.reduce((acc, next) => {
      return stationsReducer(acc, next);
    }, state);
  } else if (isRegisterEvent(event)) {
    return {
      ...state,
      [event.payload.id]: event.payload
    };
  } else if (Array.isArray(event.to)) {
    const events = event.to.map(id => {
      return {
        ...event,
        to: id,
      }
    })

    return machinesReducer(state, { type: "BATCHED", events })
  }

  const machine = state[event.to];

  if (machine) {
    return {
      ...state,
      [event.to]: machineReducer(state[event.to], event)
    };
  }

  return state;
};

Let's review each branch of the if statement here.

if (isBatchedEvent(event))

If the dispatched event's type property equals "BATCHED" then event.events will be an array of events to be sent to the machines. We just call machinesRedcuer recursively for each event and build up the next state using Array.reduce

if (isRegisterEvent(event))

This is the special event for registering new machines with the store. event.payload should be of type StoredMachine

if (Array.isArray(event.to))

This handles the case where a single event is sent to multiple machines. It transforms the single event into a list of batched event and calls machinesReducer with the special "BATCHED" event.

else

We check if there is a machine given event.to and if so send the event to that machine or return state as is if we can't find a machine the event is targeting.

Connecting with ReactJS

Now that we have the Redux part down we can move onto ReactJS. Our wrapper around XState's useMachine does a whole lot of extra. I'm going to post the entire function before analyzing it in parts.

/**
 * Wrapper around _useMachine_
 * 
 * Machines are registered with the [[store]]. Events
 * are sent to the store rather than the _send_ function
 * returned by _useMachine_.
 * 
 * @param machine
 */
const useSupervisedMachine = <
  TContext,
  TEvent extends X.EventObject = X.AnyEventObject,
  TTypestate extends X.Typestate<TContext> = any
>(
  machine: X.StateMachine<TContext, any, TEvent, TTypestate>
) => {
  // Unique identifier
  const id = machine.id;

  let isNew = false;
  let maybeStoredMachine = store.getState()[id];

  // 1.
  if (!maybeStation) {
    isNew = true;

    maybeStation = {
      id: id,
      machine,
      eventQueue: [],
      state: machine.initialState
    };
  }

  // 2.
  // Effect with no dependencies. Actual effect is only
  // run once and registers the machine with the store.
  React.useEffect(() => {
    if (isNew) {
      dispatch({
        type: "REGISTER_MACHINE",
        // @ts-ignore
        payload: maybeStation
      });
    }
  });

  // 3.
  const [   state, , service] = useMachine(machine, { state: maybeStation.state} );

  // 4.
  // Mutate the service property on the machine's related [[StoredMachine]]
  React.useEffect(() => {
    store.getState()[id].service = service;

    return () => {
      store.getState()[id].service = undefined;
    };
  }, [service, id]);

  // 5.
  // Our verison of service.send
  const sendWrapper = React.useMemo(() => {
    const sendToStore = (
      event: SupervisedEvent<TEvent>,
      payload?: X.EventData | undefined
    ): void => {
      // `.to` is added too all events and populated
      // with the machine's id if not present.
      if (Array.isArray(event)) {
        // Redux doesn't like array's of events so this will do:

        const events: AnyDispatchedEvent[] = event.map(batchedEvent => {
          const dispatchableEvent: AnyDispatchedEvent = typeof batchedEvent === 'string' ? {
            type: batchedEvent,
            to: id
          } : {
            ...batchedEvent,
            type: batchedEvent.type,
            to: batchedEvent.to || id
          }

          return dispatchableEvent
        })

        const batchedEvent = {
          type: "BATCHED" as const,
          events,
        }

        dispatch(batchedEvent as any);

        return;
      }

      // If not batched than just a single plain event.
      const dispatchableEvent: AnyDispatchedEvent = typeof event === 'string' ? {
        type: event,
        to: id
      } : {
        ...event,
        type: event.type,
        to: event.to || id
      }

      dispatch(dispatchableEvent);
    };

    return sendToStore;
  }, [id]);

  // 6.
  React.useEffect(
    () => {
      if (maybeStation.eventQueue.length > 0) {
        const queue = maybeStation.eventQueue.splice(0, maybeStation.eventQueue.length)
        dispatch({ type: 'BATCHED', events: queue})
      }
    }
  )

  // 7., voila:
  return [state, sendWrapper, service] as const;
};

1.

Create a station object for a machine + id if it doesn't exist yet in the store.

2.

Use useEffect to dispatch the special registration event if the station is new.

3.

Call XState's version of useMachine to providing us with the machine's state, dispatcher, and service.

4.

Use useEffect to mutate the store's state with the machine's now available service. The effect removes the service when the component unmounts.

5.

Create a version of send that the store can handle.

6.

Dispatch queued events, if any, to the machine's service

7.

Return the next state, our version of the dispatcher, and the service just like useMachine would.

sendWrapper looks like a lot of code but all it does is:

Add .to to an event object using the machine's id if it wasn't set so that the reducer targets the right machine.
Change string events into event objects with a type property. send("TOGGLE") becomes send({type: "TOGGLE"}).
Convert lists of batched events into a single special "BATCHED" event the store can consume.

And that's it! We now have an architecture in place for sharing state between machines in different ReactJS components as well as being able to dispatch events to any machine using eitherstore.dispatch or the send function returned to us by our version of useMachine

codesandbox

In the above sandbox it demonstrates that when a user changes the country it clears the city input by dispatching 2 events.

I'm also using the useSelector hook provided by react-redux to read state and give me the value of the Country input. That's right! You can keep using all your favourite Redux tools.

I hope you feel inspired. I'm really excited to see where XState is going and what patterns and strategies we'll all come up with. There are flaws in this setup but it was fun to experiment.

About Jobber

At Jobber I am exploring XState to help us manage front-end state in our apps. We are hiring for remote positions across Canada at all software engineering levels!

Our awesome Jobber technology teams span across Payments, Infrastructure, AI/ML, Business Workflows & Communications. We work on cutting edge & modern tech stacks using React, React Native, Ruby on Rails, & GraphQL.

If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!

Working with non-user asynchronous events in model based tests with XState

John — Wed, 18 Mar 2020 17:45:57 +0000

I recently blogged about my about experience in developing model based tests using state machines with the help of XState and it's companion library @xstate/test. I the article I talk about intercepting network requests and how I made it work. I want to focus in a little on that in this post.

If you are unfamiliar with XState I highly recommend checking it out. It has helped me develop better interfaces, components and part where it generates hundreds of tests for you given a few lines of code is just the icing on the cake.

The problem

When defining the configuration of a state machine that models the user's interaction with your application you also instruct your test model (created using xstate/test) what action to perform that simulates the event. Here's an example of test modeled for a form with a single text input and a button:

Application code:

<div>
  <div id="message">Guess the right value?!</div>
  <input type="text" value="" id="txtInput" />
  <button>Try!</button>
</div>
<script>
  document.querySelector('button').addEventListener('click', () => {
    const guessedRight = document.getElementById('txtInput').value === "777"
    document.getElementById('message').innerHTML = guessedRight
      ? "You guessed right!"
      : "Nope! Try again!"    
  })
</script>

State machine that models the test:

import { createMachine } from 'xstate'

const testMachine = createMachine({
  initial: 'fillOutForm'
  states: {
    fillOutForm: {
      on: { CLICK_BUTTON: 'guessed' },
      meta: {
        test: () => expect(document.getElementById('message').innerHTML)
                      .toBe("Guess the right value?!")
      }
    },
    guessed: {
      meta: {
        test: (_, e) => {
          const guessedRight = e.value === "777"
          expect(document.getElementById('message').innerHTML)
            .toBe(guessedRight ? "You guessed right!" : "Nope! Try again!")
      }
    }
  }
});

Test model:

import { createModel } from '@xstate/test'

const testModel = createModel(testMachine).withEvents({
  CLICK_BUTTON: {
    cases: ["000", "777"],
    exec: (_, event) => {
      document.getElementById('txtInput').value === event.value
      document.querySelector('button').click()
    } 
})

As you can see, the map of events given to the model reflects 2 user interactions. One for entering a value and one for clicking the button. This is likely the most common use case and also recommended for complete end-to-end tests where nothing is mocked, intercepted, or substituted.

However we often want to test end-to-somewhere-in-the-middle. Is that just called an integration test? The most common example of this is intercepting and mocking network requests. And even for complete end-to-end tests you will find yourself in situations where you need control over the order-of-execution. And that can be difficult to wrap your mind around.

A good example of this is the usage of setTimeout. If you are using setTimeout in your application then at some point an event will occur that is not triggered by the user. Other examples of this are promises that resolve, setInterval, registered callbacks for events such as the window resizing, etc. Those events can not be simulated in your models event map as intuitively as user events.

Aside: This is where I see newcomers to XState go off the deep-end. They create a state machine in their application that handles some kind of asynchronous behaviour using an invoked service that takes their machine say from idle to loading and a final state of failure or success. All excited they start digging into model-based testing and use the same machine or a very similar one in their test. The first mistake made, (I did), is keeping the invoked service on the test machine.

However, the machine used in your application is not the the machine used in your test. The machine used in your application is interpreted (service) and transitions from state to state responding to user- or internal machine events. The test machine is never interpreted but analyzed and "converted" to a set (plan) of of possible transitions (paths).

Now that we know that non-user events can be a problem, lets put this problem in our example:

Application code:

<div>
  <div id="message">Guess the right value?!</div>
  <input type="text" value="" id="txtInput" />
  <button>Try!</buttton>
</div>
<script>
  document.querySelector('button').addEventListener('click', () => {
    const guessedRight = document.getElementById('txtInput').value === "777"

    document.getElementById('message').innerHTML = guessedRight
      ? "You guessed right!"
      : "Nope! Try again!"    

    setTimeout(() => {
      document.getElementById('message').innerHTML = "Guess again?!"
    }, 3000)
  })
</script>

State machine that models the test:

import { createMachine } from 'xstate'

const testMachine = createMachine({
  initial: 'fillOutForm'
  states: {
    fillOutForm: {
      ...
    },
    guessed: {
      on: { SET_TIMEOUT_DONE: 'guessAgain' },
      meta: {
        ...
      }
    },
    guessAgain: {
      meta: {
        test: () => waitFor(() =>
          expect(document.getElementById('message')
           .innerHTML
          ).toBe("Guess again?!")
      }
    },
  }
});

Test model:

import { createModel } from '@xstate/test'

const testModel = createModel(testMachine).withEvents({
  SET_TIMEOUT_DONE: ?????
  CLICK_BUTTON: {
    ...
})

And there we have it. Our test model's event map has an event for which we don't know how to write a simulation. Continuing off the deep-end described in the aside above: This is where developers will:

Return a rejected or resolved promise
Call setTimeout

And then look sad as their tests fail and they can't figure out why because intuitively this is how you would expect to take care of the event. For now you can just assign a void function to that event.

const testModel = createModel(testMachine).withEvents({
  SET_TIMEOUT_DONE: () => {}
  ...

Regardless, your test will fail at this point because the test model, after executing the test for the "guessed" state will execute the void handler for the "SET_TIMEOUT_DONE" event and continue with the test for the "guessAgain" state before the setTimeout in our code resolves.

This is where utility functions provided by most testing libraries such as Puppeteer, Cypress.io, and @testing-library come in. They will block an asynchronous test and retry an assertion or expectation until it succeeds or times out:

import { waitFor } from '@testing-libary/dom'
    guessAgain: {
      meta: {
        test: async () => waitFor (
          () => expect(
            document.getElementById('message').innerHTML
            ).toBe("Guess again?!")
        )
      }
    },

This probably covers 90% or more of all cases. Problem solved. This post isn't necessary.

It becomes a problem when the test for the state that dispatches the non-user event has additional blocking statements and your application moves on to it's "success" or "failure" state while your test is still busy checking for the "loading" state. When intercepting requests and immediately resolving them with a mock this issue also pops up. It's race issue. The order of execution could be:

Test model executes function defined for "SUBMIT" event.
Application code calls onClick handler.
onClick handler calls fetch or setTimeout.
Test model executes function defined for submitting.meta.test.

Case 1: The test is blocked asserting something other than being in submitting state:

Test for submitting.meta.test is blocking
The callback provided for the fetch promise or setTimeout in the application code resolves and the appliction's UI updates reflecting a successful or failed outcome.
Test for submitting.meta.test continues and asserts if the application's UI reflects a "loading" state.
Test fails.

Case 2: fetch or setTimeout are mocked and resolve immediately:

The callback provided for the fetch promise or setTimeout in the application code resolves and the application's UI updates reflecting a successful or failed outcome. 2.. Test for submitting.meta.test continues and asserts if the application's UI reflects a a "loading" state.
Test fails.

The solution

What if we could:

Intercept where the application calls fetch or setTimeout.
Block execution of the application code.
Let the test do what it needs to.
Let the test unblock the application code whenever it wants.

We can! Whether you are using Puppeteer, Cypress.io, @testing-library or any other library for testing. As long as you have access to the environment the application is running in from your test.

As I type this I'm not 100% sure how you would intercept calls to setTimeout with Puppeteer but I'm pretty sure it would be possible.

We're going to continue with our simpler set-up that we started out with. To block setTimeout from resolving we are going to work with an array buffer of promises that allows.

const getFancyPromise = () => {
  let resolvePromise = () => throw "Unresolved promise"

  const promise = new Promise(resolve) => {
    resolvePromise = resolve
  }

  return Object.assign(promise, { resolvePromise })
}

I'll admit this is hacky but it allows me to resolve the promise outside of it's context:

const promise = getFancyPromise();
..
// much later
promise.resolvePromise();

Let's write our version of setTimeout

const makeSetTimeout = (buffer: Promise[]) => {
  const __setTimeout = window.setTimeout

  window.setTimeout = (cb: () => void, ms: number) => __setTimeout(async => {
    while (buffer.length > 0) {
      const promise = buffer[0]

      if (promise ) {
        await promise
        buffer.shift()
      }
    }

    __setTimeout(cb, ms)
  }, 0)
}

Given an array buffer we assign to window.setTimeout a version of it that delays the execution of the callback function until all promises in the buffer are resolved. Once a promise resolves it is removed from the buffer (mutative!!). Arrays in JavaScript are reference types. Anything pushing to the buffer is mutating the same array in memory as our function shifting from it.

We can now change our event mapping to push to this buffer before the button click simulation:

Test model:

import { createModel } from '@xstate/test'

const testModel = createModel(testMachine).withEvents({
  SET_TIMEOUT_DONE: () => {},
  CLICK_BUTTON: {
    cases: ["000", "777"],
    exec: (_, event) => {
      buffer.push(getFancyPromise())

      document.getElementById('txtInput').value === event.value
      document.querySelector('button').click()
    } 
})

And in the test for the "guessAgain" state we can resolve the promise in the buffer:

import { waitFor } from '@testing-libary/dom'

...
    guessed: {
      meta: {
        test: (_, e) => {
          const guessedRight = e.value === "777"
          expect(document.getElementById('message').innerHTML)
            .toBe(guessedRight ? "You guessed right!" : "Nope! Try again!")

          buffer.forEach(promise => promise.resolve())
      }
    }

So now the order of execution is:

Model simulates button click
Application code updates UI with message with "You guessed right!" or "Nope! Try again!"
Application code calls setTimeout which blocks at promise.
Model executes guessed.meta.test.
Test resolves promise in buffer.
Intercepted setTimeout continues as is.
Model executes guessAgain.meta.test and is blocked using waitFor.
setTimeout resolves.
Test passes.

This is a simple strategy that can be applied if you are running in edge cases when dealing with non-user events modeled in your test machine. I've been using it primarily to gain control on when network requests should be allowed to continue whether they are mocked or not.

Feel free to ask any questions or join me on https://spectrum.chat/statecharts and stop touching your face!

Chautelly.

Model based UI tests with XState, Cypress, Puppeteer & more

John — Thu, 12 Mar 2020 13:31:10 +0000

You may have seen XState appear on your feed lately as an up-and-coming javascript library promoting the usage of state machines for UI development and testing. A presentation (by David Khourshid at the 2020 React Rally conference) on using state machines to auto-generate model based tests is what got me hooked on XState.

In this post I will explain how I:

Used XState to define a state machine that reflects the users interaction with a UI.
Used XState's @xstate/test library to auto generate testable pathways given the state machine.
Tested each state using puppeteer or Cypress.io
Mocked all possible API responses, both good and bad, and included testable states for those in my machine.

I'll try to address an audience that is completely new to XState as well as guide those that are somewhat familiar already. If you are new to XState: To get an idea of what we are talking about here I highly recommend watching David's presentation at a ReactConf AU titled "Model-based testing in React"

Code examples

For the impatient, code examples are available here:

An explanation of how I maintained control on the order of execution between tested states, machine events, and the intercepted requests can be found here

What we're building

I forked David's repository where he built a simple feedback app with auto-generated tests. I added some asynchronous behaviour to it as well as a success and failure state. We're building on top of what he had in place. I'll formalize in a a set of requirements:

Story

As visitor of the site wanting to give feedback I should be able to rate my experience as Good or Bad and provide additional feedback if I choose Bad.

Requirements

Users can exit at any time by pressing the Escape key on the keyboard.
Users can choose between a Good or Bad experience.
A thank you message is displayed when they give a Good rating.
Users can provide additional feedback using a text input when they give a Bad rating.
The UI should indicate the request is being processed while their additional feedback is being submitted.
Once submitted, a thank you message or if the submission failed a message indicating that should be displayed.

Steps we'll take

First we have to come up with a state machine that reflects the users interaction with our application and create a test model.
Then we have to define what should happen for each event the machine handles.
Next we should write a test for each state the machine can be in.
Followed by iterating each pathway and testing it.
We'll continue with looking at how both Puppeteer and Cypress.io allow you to intercept and stub network requests.
Talk about order of execution between your tested states, the events and the intercepted network requests and how to control the order of execution using a buffer of promises.
How I intercepted and blocked network requests in Cypress.io

1. The State Machine

You'll want to put yourself a user's shoes when coming up with a state machine specifically targeting tests. Think about the things a user can do (events) and the things they can see (states).

In our case the first screen needs an option to rate the user experience as Good or Bad. And so the first state could be labelled "question" while the possible events are RATE_GOOD, "RATE_BAD, or PRESS_ESC.

To create a state machine import createMachine from xstate:

import { createMachine } from "xstate";

const feedbackMachine = createMachine({
  id: "feedback",
  initial: "question",
  on: {
    ESC: ???
  },
  states: {
    question: {
      on: {
        CLICK_BAD: ???
        CLICK_GOOD; ???,
      }
    }
  }
});

In the above code example we gave the machine an initial state and a possible "question" state. The .on map of events indicate the events that can occur at the state they are part of. As you can tell the ESC event is defined at a top level since that event can occur any time while the click events are only defined for the "question" state.

There are quite a few options when it comes to defining what should happen within the state machine when responding to events. For this example we are going to only show the option where you define what state the machine should transition to:

...
  states: {
    question: {
      on: {
        CLICK_BAD: "form",
        CLICK_GOOD: "thanks"
      }
    },
    form: {},
    thanks: {},
    closed: {}
  }
});

This configuration instructs the state machine to transition to the states assigned to the events. Since the user can give additional feedback when they give a Bad rating and that submitting that is an asynchronous process our state machine configuration needs a few more events and states:

const feedbackMachine = createMachine({
  id: "feedback",
  initial: "question",
  on: {
    ESC: "closed",
  },
  states: {
    question: {
      on: {
        CLICK_BAD: "form",
        CLICK_GOOD: "thanks"
      }
    },
    form: {
      on: {
        SUBMIT: 'submitting',
        CLOSE: 'closed',
      }
    },
    submitting: {
      on: {
        FAILURE: 'failure',
        SUCCESS: 'thanks',
        CLOSE: 'closed',
      }
    },
    failure: {
      on: {
        CLOSE: 'closed',
      }
    },
    thanks: {
      on: {
        CLOSE: 'closed',
      }
    },
    closed: {}
  }
});

The "CLOSE" event reflects the interaction the user can have with a "close" button that is available at every step after the user has selected a rating. Submitting the form takes the user to the submitting state and from there the request can succeed and transition to thanks or to failure.

The last piece of the configuration puzzle is adding a condition to the transition the machine makes when the form is submitted. We want the machine to transition to a "thanks" state if the user leaves the input for additional feedback empty and essentially ignore the additional feedback.

    form: {
      on: {
        SUBMIT: {
          target: "submitting",
            // Only transition to submitting if the user has entered a value.
            cond: (ctx, evt) => evt.value.trim().length > 0
          },
          { target: "closed" }
        ...
      }
    },

That's it. That's our state machine. You can view it in XState's vizualiser here.

With our machine in hand we can create model using @xstate/test's createModel function:

const testModel = createModel(feedbackMachine)

2. Given, when ...

Our list of possible events are:

CLICK_GOOD
CLICK_BAD
CLOSE
ESC
SUCCESS
FAILURE
SUBMIT

For each event that reflects a user interaction we have to instruct our test model what simulation action to take. In our case the FAILURE and SUCCESS events are not user driven events but API driven events. For those we don't have to define any actions.

Using a test model's .withEvents API we can instruct XState what code to execute per event. This is different for Cypress then for Puppeteer:

Puppeteer:

const testModel = createModel(feedbackMachine).withEvents({
  CLICK_GOOD: page => page.click('[data-testid="good-button"]'),
})

Cypress:

const testModel = createModel(feedbackMachine).withEvents({
  CLICK_GOOD: () => new Cypress.Promise(resolve => {
    cy.get('[data-testid="good-button"]')
      .click()
      .then(resolve);
  }),
});

The function provided for an event can return a promise. This allows you to block the transition of the machine and subsequently the execution of the next test.

In the case of Cypress we are forced to use Cypress.Promise since cypress tests internally work quite different. I have a faint idea of what is going on in the background but if you know of a good explanation to link to I would love to add that to this post.

You can check out the full configuration of events in the linked repositories. I will discuss the configuration of the SUBMIT later.

3. Given, when, then

To define a test for each state that the model has access too you define a function named test on each state configuration's .meta property:

Puppeteer:

states: {
  question: {
    on: {
      CLICK_GOOD: "thanks",
      CLICK_BAD: "form",
      CLOSE: "closed"
    },
    meta: {
      test: async (page: Page) => {
        await page.waitFor('[data-testid="question-screen"]');
        await page.waitFor('[data-testid="bad-button"]');
        await page.waitFor('[data-testid="good-button"]');
      }
    }
  },

Cypress:

states: {
  question: {
    on: {
      CLICK_GOOD: "thanks",
      CLICK_BAD: "form",
      CLOSE: "closed"
    },
    meta: {
      test: () =>
        new Cypress.Promise(resolve => {
          cy.get('[data-testid="question-screen"]');
          cy.get('[data-testid="question-screen"]');
          cy.get('[data-testid="good-button"]').then(() => {
            resolve();
          });
        })
    }
  },

Again, to block the state machine from transitioning we return a promise and in the case of Cypress we resolve that promise in the last line of the test. From what I understand the calls to cy are automatically chained and so resolve should only be called when all three tests are done.

We continue this pattern of checking the DOM for each state node. When in state A, I expect the DOM to look like .., etc. Similar to the SUBMIT event, the submitting state has a slightly different test that we will talk about as well. This is what is so cool about XState. It's fairly trivial to think of the states your application can be in and write tests for those. Transitioning between them is what XState is good at!

4. XState, do the work!

With a state machine configured, events mapped out and tests written for each state we are ready to do the actual testing:

Puppeteer:

// Create the test plans
const testPlans = testModel.getSimplePathPlans();

// Iterate the plans and paths and test each:
testPlans.forEach((plan, planIndex) => {
  describe(`${planIndex}: ${plan.description}`, () => {
    plan.paths.forEach((path, pathIndex) => {
      it(`${pathIndex}: ${path.description}`, async () => {
        await page.goto(`http://localhost:7777`);
        await path.test(page);
      },
      10000);
    });
  });
});

Cypress:

// Iterate the plans and paths and test each:
testPlans.forEach((plan, planIndex) => {
  describe(`Plan ${planIndex}: ${plan.description}`, () => {
    // Start with an empty list for the failur patterns for this plan.
    plan.paths.forEach((path, pathIndex) => {
      it(`Path ${pathIndex}: ${path.description}`, () => {
        cy.visit(`http://localhost:7777`);

        return new Cypress.Promise(async resolve => {
          await path.test();
          resolve();
        });
      });
    });
  });
});

The test model provides an API for us to generate plans and paths. Each path represents a set of transitions a machine can go through. And since our machine is based on the user's interaction each path represents a possible outcome the user can encounter.

Check out @xtate/test's documentation on .getSimplePathPlans vs .getShortestPathPlans

The rest of this post has very little to do with XState and is mostly on making generated tests using XState work with Puppeteer and Cypress and being able to intercept network requests and stub their responses.

We will come back to XState in a bit and talk about the SUBMIT event and the submitted and failed states.

5. Stubbing network requests

Puppeteer provides a way to intercept network requests out-of-the-box and you can also choose to let the request continue or respond with a custom response. Cypress has limited support for this. At the time of writing this post they do not support intercepting promise based requests using fetch. They do have support for stubbing responses for requests made using XMLHttpRequest but I was unable to figure out how to block a request, do some work and let it continue with a stubbed response.

5.1 Stubbing network requests with Puppeteer

With puppeteer you have to explicitly indicate you want to intercept requests and register a callback function that will handle requests. You can do this in your test's beforeAll and afterAll hooks:

describe("feedback app", () => {
  const onRequest = request => { request.continue() }

  beforeAll(async () => {
    await page.setRequestInterception(true);
    page.on("request", onRequest);
  });

  afterAll(async () => {
    page.off("request", onRequest);
    await page.setRequestInterception(false);
  });

The issues I have encountered were related to security and mostly affected running the tests in headless mode. Adding the appropriate headers resolved this for me:

async (interceptedRequest: Request): Promise<void> => {
  const url = interceptedRequest.url();

  // If the url matches an API our app would use
  if (/foobar/.test(url)) {
    if (interceptedRequest.method() === "OPTIONS") {
      return interceptedRequest.respond({
        status: 200,
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Headers": "*"
        }
      });
    }

    return interceptedRequest.respond({
      status: 200,
      contentType: "application/json",
      headers: {
        "Access-Control-Allow-Origin": "*"
      },
      body: JSON.stringify({
      ...

For all requests that you aren't stubbing you use request.continue(). I also used request.abort() if the requested url matched assets such as fonts or images that weren't important to the test. This can help speed up the test.

5.2 Stubbing network requests with Cypress

Stubbing network requests with Cypress was a different story. I first looked at the cypress-unfetch plugin but I couldn't get it to work with just that. However, after having a look at the plugin's source code I made it work by:

Installing cypress-unfetch
Importing import "@rckeller/cypress-unfetch/await"; at the top of my file as per the README.
Creating my own wrapper around unfetch:

// unfetch-wrapper.ts
import unfetch from 'unfetch'
import { Deferred } from '../src/delay';

export default (buffer: Deferred[]) => async (url: RequestInfo, options: RequestInit) => {
  while (buffer.length > 0) {
    const deferred = buffer[0];

    if (deferred) {
      await deferred;
      // Pop it once it's resolved. Don't pop it before that otherwise
      // the test won't have access to it to resolve it.
      buffer.shift();
    }
  }

  if (/FAILURE/.test(url as string)) {
    throw Error("500")
  }

  return unfetch(url, options)
}

Importing my version of unfetch and executing the same code as in @rckeller/cypress-unfetch/index but slightly adjusted:

before(() => {
    cy.log("Cypress-Unfetch: Polyfill Fetch >>> XHR Fallback");
    // Load the standalone polyfill w/ a closure, prevents race
    Cypress.on("window:before:load", win => {
      Object.assign(win, { fetch: unfetch(buffer) });
    });
  });

Essentially what is happening here is: unfetch gives us a promise based wrapper around XMLHttpRequest and since Cypress supports that API we should be able to intercept requests. Before the test runs we use a hook provided by Cypress giving us access to the window object. We import our wrapper around unfetch, call it and give a bit more information and assign that to window.fetch

6. Race to the finish line

Ok, we're ready to talk about tying it all together. First we need to address the issue of the order of execution. The problem is as follows:

When the model executes the SUBMIT event we might test if the button is available using cy.get or page.waitFor. We then simulate the user clicking the button by calling cy.get(..).click() or page.click(..). After this the state machine should transition to submitting and the network requests should be intercepted and stubbed.

However we need a solution so that we can make sure that the tests written for the submitting state are executed before the network promise resolves. You could do this with a delay inside the intercepted request but that doesn't give you guarantees. To guarantee the order of execution I am using a buffer of promises. The order is as follows:

Model executes callback for SUBMIT event.
A promise is pushed to an array buffer.
The click is simulated
The UI responds to the click and makes a network call.
The request is intercepted.
The "interceptor" checks if there is a promise in the array buffer and blocks the execution (async/await).
The state machine runs the "submitting" state's test
The test resolves the promise that is in the buffer after it's test has run.
The interceptor continues now that the promise is resolved and stubs the response.
The UI updates according to the stubbed response.
The model executes the events that are defined for the "submitting" state.
Tests for each state transitioned to after "submitting" are run.

I should also add that I'm using a hack to resolve a promise outside of it's callback function:

export type Deferred<T = any> = Promise<T> & {
  id: string;
  resolve: () => void;
}

export const defer = <T = any>(value: T, id: string): Deferred<T> => {
  let resolve: () => void = () => {
    throw Error("Unexpected deferral")
  }

  const promise = new Promise<T>(r => {
    resolve = () => r(value)
  })

  return Object.assign(promise, { resolve, id }) 
}

If you know of a better solution for this let me know. Right now it does the job :).

Here's what our SUBMIT event mapping and submitting test look like for both Puppeteer and Cypress:

Puppeteer:

...
submitting: {
  on: {
    SUCCESS: 'thanks',
    FAILURE: 'failure'
  },
  meta: {
    test: async (page: Page) => {
      // Wait for the loading message
      await page.waitFor('[data-testid="submitting"]');

      // And resolve the promise in the buffer so that the
      // request interceptor can continue 
      buffer.forEach(deferred => {
        deferred.resolve()
      })
    }
  }
},
...
SUBMIT: {
  exec: async (page, event: any) => {
    await page.type('[data-testid="response-input"]', event.value);

    if (event.value.length > 0) {
      // Put a promise in the buffer to be resolved
      // in the "submitting" state's test.
      buffer.push(defer('Submitting' ,'Submitting'))
    }

    await page.click('[data-testid="submit-button"]');
  },
  cases: [{ value: "something" }, { value: "" }]
}

Cypress:

submitting: {
  on: {
    SUCCESS: "thanks",
    FAILURE: "failure"
  },
  meta: {
    test: () => {
      return new Cypress.Promise(resolve => {
        cy.get('[data-testid="submitting"]').then(() => {
          // And resolve the promise in the buffer so that the
          // request interceptor can continue
          buffer.forEach(deferred => {
            deferred.resolve();
          });

          resolve();
        });
      });
    }
  }
},
...
SUBMIT: {
  exec: (_, event: any) =>
    new Cypress.Promise(async resolve => {
      const handle = cy.get('[data-testid="response-input"]');
      const nextHandle = event.value ? handle.type(event.value) : handle;

      nextHandle.then(() => {
        if (event.value.length > 0) {
          // Put a promise in the buffer to be resolved
          // in the "submitting" state's test.
          cy.log(`Buffer Submitting`);
          buffer.push(defer("Submitting", "Submitting"));
        }

        cy.get('[data-testid="submit-button"]')
          .click()
          .then(resolve);
      });
    }),
  cases: [{ value: "something" }, { value: "" }]
}

7. Just give me a reason

As a last step we have to create the link between a path that wants to test a certain API outcome and the request interception itself. The best way I've found to to do this is via query parameters added to the url visited by both Cypress and Puppeteer.

A path' description might look like:

Path 3: via CLICK_BAD → SUBMIT ({"value":"something"}) → SUCCESS → CLOSE

I use regular expressions to parse that into: [SUCCESS] and include that information in the page visit's url:

// Puppeteer
await page.goto(
  `http://localhost:7777?pathIndex=${pathIndex}&planIndex=${planIndex}&outcomes=${outcomes.join(
    ","
  )}`
);

// Cypress
cy.visit(
  `http://localhost:7777?pathIndex=${pathIndex}&planIndex=${planIndex}&outcomes=${outcomes.join(
    ","
  )}`
);

This is probably sufficient for most cases but it could be that you are making multiple API calls. For example, if we allowed the user to retry a failed network call our test path description might look like:

Path 3: via CLICK_BAD → SUBMIT ({"value":"something"}) → FAILURE → RETRY → SUBMIT → SUCCESS → CLOSE

Indicating that the set of events and transitions includes a first try that failed and a second one that succeeded.

For this case just using query parameters is not sufficient and you will need an additional mapping of plan and path index to a list of instructions on how the API should resolve.

This is what that looks like:

const failurePattern: string[][][] = []
...
// Iterate the plans and paths and test each:
testPlans.forEach((plan, planIndex) => {
  describe(`${planIndex}: ${plan.description}`, () => {
    // Start with an empty list for the failur patterns for this plan.
    failurePattern[planIndex] = [];

    plan.paths.forEach((path, pathIndex) => {
      it(
        `${pathIndex}: ${path.description}`,
        async () => {
          // Populate this path's failure pattern 
          failurePattern[planIndex][pathIndex] =
            path.description.match(
              /SUCCESS|FAILURE/g
            ) || [];

          const outcomes = failurePattern[planIndex][pathIndex];

          // Outcomes is added to the frame url for info but pathIndex and planIndex are important
          // as they are read in the request interceptor
          await page.goto(
            `http://localhost:7777?pathIndex=${pathIndex}&planIndex=${planIndex}&outcomes=${outcomes.join(
              ","
            )}`
          );

          await path.test(page);
        },
        10000
      );
    });
  });
});

While the test model's plans and paths are iterated, failurePattern is built up with information for each plan and path index on how the API should respond given the order of SUCCESS and FAILURE events in the path's description.

The plan and path index are added as query parameters and the request interceptor should have access to the failurePattern data set similarly as to the buffer of promises. When a request is made it checks the query parameters and pops from failurePattern[planIndex][pathIndex] the next "how it should respond" code.

Puppeteer

const makeRequest = (failurePattern: string[][][], buffer: Deferred[])
  (request: Request) => {
    const frameUrl = interceptedRequest.frame()?.url()
    const [, pathIndex, planIndex] = (frameUrl.match(/\d+/g) || []).map(Number);
    const outcome = failurePattern[planIndex][pathIndex].shift();

Cypress

// unfetch.ts
export default (failurePattern: string[][][], buffer: Deferred[])
  => async (url: RequestInfo, options: RequestInit) => {
    const frameUrl = window.location.href
    const [, pathIndex, planIndex] = (frameUrl.match(/\d+/g) || []).map(Number);
    const outcome = failurePattern[planIndex][pathIndex].shift();

// e2e.spec.ts
Cypress.on("window:before:load", win => {
  Object.assign(win, { fetch: unfetch(failurePattern, buffer) });
});

Both failurePattern and buffer are passed by reference and mutated.

When path.test(..) is executed the state machine will transition from state to state given the set of events that the path describes. The first time the SUBMIT event occurs and is simulated; Once the request is intercepted the interceptor pops the first "how to respond" from the failurePattern array for the given plan and path index that were derived from the frame url or window location. The second time SUBMIT is dispatched in the test, the next "how to respond" is popped from the stack.

Summary

This may have been a lot to take in. One the main reasons for me to write this was to have some document out in the open recording the process. I went trough a lot of trial and error to figure this out and I am very much open to other, maybe less hacky, solutions. Feel free to DM me if you have any questions or need a bit help with this!

@chautelly

Thoughts on state management with XState and ReactJS

John — Sun, 08 Mar 2020 19:30:18 +0000

This is not a step-by-step guide or article on how you should but rather a how you could manage and share state when developing applications and components. I should also state, (see what I did there), that I am heavily influenced by Redux and less familiar with other state management libraries.

The short

Lift the machine just like you lift state.
Import an interpreted machine and use useService
Make a memoized version of useMachine
Create a supervisor using Redux
Use observable streams to share state

The medium

Problems

Current: You have component + machine that fetches and renders a list of todos.

Requirement: You need to display a count of completed todos in a sibling component.

Current: A component/machine combo in the top bar of your app fetches and displays the name of the authenticated user.

Requirement: Display the username in the footer as well.

Solution

Lift the machine interpreted using the useMachine hook up to a (grand)parent component if you find yourself needing to share it's state with a siblings. Use props or ReactJS' Context API to pass machine information (state) and callbacks (send) to (grand)child components.

Spawning actors

Problem: Your "list of repositories" machine depends on a "selected user" machine higher up.

Requirement: When the selected user changes, the list of repositories should be reset and fetched again.

Solution

If your component + machine depends on a machine running higher up in the component hierarchy, (e.g. your machine could be a spawned actor). Don't use the useMachine hook in the child component but let the parent spawn it and pass data and callbacks down via props or use ReactJS' Context API.

The line of communcation here is: spawnedMachine-> parentMachine -> ParentComponent -> ChildComponent -> ChildComponent. And back of course.

If you do not want your spawned repositories machine to make a network request when selected user changes because the component rendering the list of repositories is not routed to. Then model your machines in such a way allowing you to send messages up the chain using ReactJS' useEffect hook (or componentDidMount when using classes). The message event can trigger a state transition to start fetching or refreshing the list of repositories when the component is mounted. The machine controlling the selected user can still empty the list of repositories when it's selection changes.

Also an option

If the machine should run for (most of) the life-time of the application, interpret the machine and export the service it creates. Components in need of the machine's state can import the service and use the useService hook.

Memoization

A state machine's state can be persisted. See the documentation. With this knowledge you can write a version of useMachine that combined with ReactJS' useEffect hook memoizes the interpreted machine's state and re-hydrates.

You can find an example written in Codesandbox here.

Memoize all the machines!

The state of a state machine is just, well state. I like to think of state machines being similar to reducers in Redux. Redux could be used If you wanted to memoize and share the state of many machines in your application. When a component renders and interprets a machine it would dispatch an action with the machine's id and initial state. It could keep doing this on each transition or choose to only report back to Redux when the component unmounts. Computing or deriving data from a machine's context in other components would look exactly the same as you would currently do using selectors. Redux effectively becomes a sort of supervisor.

Observe and behold

By far, my favourite solution so far has been combining XState with observables (RxJS). With a few years of Redux under my belt I'm the developer that will tell you: "You might not need local state" and "There's no need to put form state in local state." Switching to XState really put me through a few weeks of rethinking how to manage state in large (monolithic) web applications.

You can think of observable streams as a mini Redux store. Maybe they stream a single string, maybe a complete object with lot's of data. With RxJS you can create a stream called a BehaviourSubject that is an observable with an initial state. From there it becomes fairly trivial using combinators and operators to combine multiple streams into a single state stream. And voila, you have a single-ish state solution again.

And to take it back to XState and to state machines: Machines that produce a value, e.g. an authenticated user, a list of todos, etc, can dispatch that data to their respective observable streams. Now you have state machines controlling the logical state of your components while still being able to share data between applications and modules!

If you'd like to see it in action, I've been working on a sample repository here: https://github.com/rjdestigter/xstate-sample-kit

Thank you for perusing my thoughts! Feel free to leave a comment or add your ideas. Be kind to one another!

@chautelly