Jest custom matcher for state.matches() (with types 😄 )

[tmikeschu]

On my team we're testing high-level happy/sad paths with React Testing Library, and pushing more of the combinations/edge cases/etc to state machine tests. We'd tried a few different assertion patterns for state values but weren't totally happy with any of them.

expect(.matches()).toBe(true)

Pros

• Type checked (assuming typegen) string values
• Expressive

Cons

• Opaque error message ("expected true, got false", doesn't show the actual state)
• A bit verbose

expect(actor.getSnapshot().matches("mutation.idle")).toBe(true)

expect(.value).toStrictEqual()

Pros

• Expressive error message (diffs actual value with expected)

Cons

• Verbooooose: requires whole state object for parallel states
• Not typed (easy to typo, especially with complex parallel state object)

expect(actor.getSnapshot().value).toStrictEqual({
  input: "idle",
  mutation: "mutating",
  validation: "valid",
})

expect(.value).toEqual(expect.objectContaining())

Pros

• Expressive error message (diffs actual value with expected)

Cons

• Not typed (easy to typo, especially with complex parallel state object)
• Also verbose with expect.objectContaining

expect(actor.getSnapshot().value).toEqual(expect.objectContaining({
  mutation: "mutating",
}))

What if we had expect(actor).toMatchState()?

Let's implement it!

import { State } from 'xstate';

export const toMatchState = <T extends State<any, any, any, any, any>, Actual extends { getSnapshot(): T | undefined }>(
  actual: Actual,
  expected: string | Record<string, any>,
) => {
  const state = actual.getSnapshot();
  if (!state) {
    throw new Error('Actor has no snapshot');
  }

  const pass = state.matches(expected);

  const prettyExpected = JSON.stringify(expected);
  const prettyActual = JSON.stringify(state.toStrings().sort());

  return {
    pass,
    message: pass
      ? () => `${prettyExpected} present in ${prettyActual}`
      : () => `${prettyExpected} not present in ${prettyActual}`,
  };
};

// test/setup.ts
expect.extend({ toMatchState })

// @types/jest.d.ts

import { State, TypegenEnabled } from 'xstate';

type GetStates<T> = NonNullable<ReturnType<T['getSnapshot']>> extends State<
  any,
  any,
  any,
  any,
  infer TResolvedTypesMeta
>
  ? TResolvedTypesMeta extends TypegenEnabled
    ? TResolvedTypesMeta['resolved']['matchesStates']
    : 'not enabled'
  : 'cant infer';

type Actor<T> = {
  getSnapshot(): T | undefined;
};

declare global {
  declare namespace jest {
    interface Matchers<R, T> {
      toMatchState<TSV extends GetStates<T>>(stateValue: TSV): R;
    }
    interface ExpectExtendMap {
      // Here, we're describing the call signature of our
      // matcher for the "expect.extend()" call.
      toMatchState: <Actual extends Actor<State<any, any, any, any, any>>>(
        this: jest.MatcherContext,
        actual: Actual,
        state: GetStates<Actual>,
      ) => jest.CustomMatcherResult;
    }
  }
}

Now we have

expect(actor).toMatcheState("mutation.idle")

It would be awesome to have some kind of @xstate/jest module but this is a nice quick win you can implement manually. Enjoy!