xstate-marionettist v0.9.0

XState Marionettist

Model based testing with XState + Puppeteer made easy

This project contains some code allowing you to define an end-to-end-ish test as a configuration that is transformed into a test using jest, @xstate/test, and puppeteer. It makes it very easy to mock and test all possible network responses your app might encounter. Creating a configuration is also quite painless since it is strictly typed using io-ts' Decoder API.

It abtracts away defining the test machine configuration, writing tests for each state and events

Instructions

Try it out!:

#: npm install
#: npm test

Running npm install will install both the dependencies in the project root as well as the example project in ./examples.

Running npm test will:

• Build the project
• cd into the project folder and
• runnpm run e2e` in the example project which will
• build the project (npm run build)
• Perform the example end-to-end test.

The example test can be found in ./examples/xstate-marionettist-example/src/apps/auth/auth.e2e.ts

Documentation

Configuration

Actions

Actions are instructions for jest and/or puppeteer and can be attached to tests or events. The following actions are currently supported:

! Anything using a selector expects that to be wrapped using the data-testid attribute. waitForSelector and expectProperty wrap names with: [data-testid~="name"] matching any words. We'll make this configurable in the future.

Example

Let's review the example test's configuration availabe in the example project. The project is a ReactJS application created using create-react-app and renders a simple login form. The test is located at ./examples/xstate-marionettist-example/src/apps/auth/auth.e2e.ts.

The configuration models 4 different states:

• noop: State where users can enter their email and password and click login.
• authenticating: State reflecting the UI is blocked and busy
• failure: Failure outcome state
• authenticated: Success outcome state

The configuration for the noop state is as follows:

noop: {
    tests: [["waitForSelector", "frm-login"]],
    on: {
        LOGIN: {
            target: "authenticating",
            actions: [
            ["type", "txt-email", "pianoman@xstatejs.org"],
            ["type", "txt-password", "statechartsareawesome"],
            ["defer", "submitting"],
            ["click", "btn-login"],
            ],
        },
    },
},

This state has 1 test and makes sure the login form is available in the DOM. Under the hood puppeteer's waitForSelector API is used:

page.waitForSelector('[data-testid="frm-login"]');

.on.LOGIN should look familiar to you as it maps directly to a proper state machine configured using XState. The actions defined here however are translated into proper functions passed to the test model built using @xstate/test's createModel API. THE "type" and "click" actions map directly to puppeteer intructions simulating typing and clicking:

    await page.type('[data-testid="txt-email"]', "pianoman@xstatejs.org"),
    await page.type('[data-testid="txt-password"]', "statechartsareawesome"),
    ...
    await page.click('[data-testid="btn-login"]'),

The "defer" action is executed before clicking the button. Under the hood puppteee's API for interepting network requests is used to mock and block API responses. The order of execution here will be:

1. "defer" puts a promise in a buffer
2. Puppteer clicks the button in the UI
3. The UI makes a network request to login
4. Puppteer intercepts the network request, checks the buffer for unresolved promises and blocks if any are in there.
5. The test model moves on to the authenticating state's tests.

The next state that will be tested is the authenticating state:

authenticating: {
    tests: [
        ["expectProperty", "btn-login", "disabled", true],
        ["resolve", "submitting"],
      ],
      on: {
        OK: {
          target: "authenticated",
        },
        BAD: {
          target: "failure",
        },
    },
},

The first test translates to a puppteer intruction for retrieving an element's property and using Jest's expect API to test the value. In this case the button should be disabled while the form is busy submitting.

The next action in the list of tests in not really a test but an instruction to resolve the promise that was put in the buffer using the "defer" action. This will cause the intercepted request to continue on. Our configuration has defined a matching path and for such cases the intercepted request is mocked. Requests that have no matching path are not mocked.

Each event type that transitions the model to a state where a mocked/bloced network request is made should be added to the top-level .outcomes property. This important or otherwise mocked responses are not matched up. I'll write up an explanation of the underlying machinary in a different readme.

In this case we have an OK and a BAD outcome. The API configuration also allows you to define a response status and payload for each outcome. The default response status is 200 and an empty body. You can also define a status and body for all outcome using an asterisk:

  apis: [
    {
      path: "/greet",
      deferrals: ["greet"],
      outcomes: {
        *: {
          status: 200,
          body: "Hello World!"
        },
      },
    },
  ],

From here the test model splits up in to two different outcomes since the authenticating state has two events configured that transition to different states. Let's look at the BAD/failure combination first.

 failure: {
    tests: [
        ["expectProperty", "btn-login", "disabled", true],
        ["resolve", "submitting"],
        ["waitForSelector", "txt-email-helptext-error"],
    ],
    on: {
        NOOP: {
            target: "noop",
        }
    }
},

The tests for this state first determine if the button is disabled since this should be the case while the network request is in progress. Then it resolves the promise that was pushed into the buffer earlier causuing the network request to be unblocked and continue. Since we have defined a custom payload for outcome BAD the response should have status 400 and contain "Invalid token".

Before allowing the model to transition back to noop state we block with a test expecting an error message. The configuration and tests for the authenticated state follow the same pattern.