@codesandbox/pitcher-client

pitcher-client

How it works

pitcher-client is exposed as a class PitcherClient which is responsible for keeping a connection to a single VM, exposing an imperative API to send requests, listen to notifications etc. and also holds internal state for simpler consumption.

There are really three levels to PitcherClient. The main class is instantiated in a CONNECTED state and will only move between CONNECTING, DISCONNECTED and CONNECTED based on the state of its passed connection. The Connection class holds connection states for the initial VM request and the websocket connection, while the WebsocketClient holds connection states for the websocket connection.

All messages are managed by the PitcherClientMessageHandler and PitcherMssageHandler (Should probably be a single class), where serialisation, deserialisation, queuing and matching of messages are handled.

How to write tests

All tests in pitcher-client can be written as full integration tests, where the only mocking is responses from Pitcher.

describe("Something", () => {
  test("should do something", async () => {
    const { client, pitcher, dispose } = await initPitcherClientMock({
      // This object represents all the responses you want Pitcher to give,
      // typed and ready to roll
      "file/open": ({ params: { id } }) => ({
        method: "file/open",
        status: PitcherResponseStatus.RESOLVED,
        result: {
          clients: {},
          content: "",
          document: { clients: {}, revision: 0 },
          id,
          isBinary: false,
          savedHash: "cc",
        },
      }),
    });

    // Use pitcher client as normal
    client.fs.getFile("someId");

    // Send a notification form Pitcher to the client
    await pitcher.sendNotification({
      method: "file/documentOperation",
      params: {
        id: file.id,
        revision: 1,
        operation: incoming.toJSON(),
        reason: ot.OperationReason.USER,
      },
    });

    // Not strictly required, but nice to clean up tests
    dispose();
  });
});

NOTE! If pitcher-client sends a request you do not have a handler for, it will throw an error and tell you which handler is missing.

How does it work?

• The initPitcherClientMock returns initPitcherClient by giving it a mocked request for an instance
• The jest-websocket-mock library is used to set up a new mocked WebSocket server for each use of initPitcherClientMock