feat: Add testing utility for mocking the randomness API

Author: delucis

docs/documentation/testing.md

@@ -67,7 +67,7 @@ it('should declare player 1 as the winner', () => {
   client.moves.clickCell(5);
 
   // get the latest game state
-  const { G, ctx } = client.store.getState();
+  const { G, ctx } = client.getState();
 
   // the board should look like this now
   expect(G.cells).toEqual(['0', '0', null, '1', '1', '1', null, null, '0']);
@@ -76,9 +76,72 @@ it('should declare player 1 as the winner', () => {
 });
 ```
 
-!> Note that we imported the vanilla JavaScript client, not the
+?> Note that we imported the vanilla JavaScript client, not the
 one from `boardgame.io/react`.
 
+### Testing Randomness
+
+If you are testing a move that uses the [Random API](/random), by definition
+you can’t always expect the same result, making it harder to test. In this
+case, you can use one of the following strategies.
+
+#### Fixed PRNG seed
+
+You can set `seed` in your game object. This will be used to initialise the
+Random API’s internal state and you’ll see a predictable sequence of results
+from calls to random API methods:
+
+```js
+import { Client } from 'boardgame.io/client';
+
+const Game = {
+  moves: {
+    rollDice: (G, ctx) => {
+      G.roll = ctx.random.D6();
+    },
+  },
+};
+
+it('updates G.roll with a random number', () => {
+  const client = Client({
+      // Set seed so PRNG always starts in same state
+    game: { ...Game, seed: 'fixed-seed' },
+  });
+  client.moves.rollDice();
+  const { G } = client.getState();
+  expect(G.roll).toMatchInlineSnapshot(`4`);
+});
+```
+
+#### Override Random API <small>`since v0.49.9`</small>
+
+If you need to test specific random outcomes, you can override the Random
+API entirely to allow complete control of the results of API methods.
+
+```js
+import { Client } from 'boardgame.io/client';
+import { MockRandom } from 'boardgame.io/testing';
+
+// Create a mock of the random plugin, where the D6 method always returns 6.
+// Any methods you don’t provide an implementation for will behave as usual.
+const randomPlugin = MockRandom({
+  D6: () => 6,
+});
+
+it ('rolls a six', () => {
+  const client = Client({
+    game: {
+      ...Game,
+      // Add the random plugin mock to the game’s plugins.
+      plugins: [...(Game.plugins || []), randomPlugin]
+    },
+  });
+  client.moves.rollDice();
+  const { G } = client.getState();
+  expect(G.roll).toMatchInlineSnapshot(`6`);
+});
+```
+
 ### Multiplayer Tests
 
 Use the local multiplayer mode to simulate multiplayer interactions

packages/testing.ts

@@ -0,0 +1 @@
+export { MockRandom } from '../src/testing/mock-random';

src/testing/mock-random.test.ts

@@ -0,0 +1,45 @@
+import { Client } from '../client/client';
+import type { Game } from '../types';
+import { MockRandom } from './mock-random';
+
+test('it creates a plugin object', () => {
+  const plugin = MockRandom();
+  expect(plugin).toEqual({
+    name: 'random',
+    noClient: expect.any(Function),
+    api: expect.any(Function),
+    setup: expect.any(Function),
+    playerView: expect.any(Function),
+  });
+});
+
+test('it can override random API methods', () => {
+  const game: Game<{ roll: number }> = {
+    moves: {
+      roll: (G, ctx) => {
+        G.roll = ctx.random.D6();
+      },
+    },
+    plugins: [MockRandom({ D6: () => 1 })],
+  };
+
+  const client = Client({ game });
+  client.moves.roll();
+  expect(client.getState().G.roll).toBe(1);
+});
+
+test('it can use non-overridden API methods', () => {
+  const game: Game<{ roll: number }> = {
+    moves: {
+      roll: (G, ctx) => {
+        G.roll = ctx.random.D6();
+      },
+    },
+    plugins: [MockRandom({ D10: () => 1 })],
+    seed: 0,
+  };
+
+  const client = Client({ game });
+  client.moves.roll();
+  expect(client.getState().G.roll).toMatchInlineSnapshot(`4`);
+});

src/testing/mock-random.ts

@@ -0,0 +1,27 @@
+import type { RandomAPI } from '../plugins/random/random';
+import RandomPlugin from '../plugins/plugin-random';
+
+/**
+ * Test helper that creates a plugin to override the built-in random API.
+ *
+ * @param overrides - A map of method names to mock functions.
+ *
+ * @example
+ * const game = {
+ *   plugins: [
+ *     MockRandom({ D6: () => 1 }),
+ *   ],
+ * };
+ */
+export const MockRandom = (
+  overrides: Partial<Record<keyof RandomAPI, (...args: any[]) => any>> = {}
+): Omit<typeof RandomPlugin, 'flush'> => {
+  // Don’t include the original flush method, otherwise when the
+  // built-in random plugin flushes, it won’t have access to the
+  // state it needs.
+  const { flush, ...rest } = RandomPlugin;
+  return {
+    ...rest,
+    api: (context) => ({ ...RandomPlugin.api(context), ...overrides }),
+  };
+};

subpackages.js

@@ -17,4 +17,5 @@ module.exports = [
   'master',
   'multiplayer',
   'internal',
+  'testing',
 ];