RFC 001: Endpoint Level Testing #

Summary #

Endpoints will be tested via undici's MockAgent, rather than using an ordered set of request/response pairs like matrix-js-sdk.

Problem #

_{With the matrix-js-sdk approach}

Besides being tedious and ugly, this approach is brittle as any change would easily break tests if anything route-related changed, despite no behaviour actually being involved.

Furthermore, as per Postman API testing, matrix-js-sdk tests are even more brittle as they rely on order rather than the APIs actual contract.

Proposal #

Taking inspiration from discord.js/rest, we will use undici's MockAgent, which will intercept the requests at the network-layer. We will also create a small hook named TBD that'll provide the MockAgent and disables network access for ease of testing.

An example could look like this:

// https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3accountwhoami
import { useHomeserver, expect } from '@matrix-nebu/test';

const origin = "https://homeserver.test";
const homeserver = useHomeserver(origin);
const client = new Client({ baseUrl: origin, ... });


homeserver
  .intercept({
    path: "/_matrix/client/v3/account/whoami",
    method: "GET",
    headers: { authorization: "Bearer syt_drainpixie_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  })
  .reply(200, { user_id: "@drainpixie:homeserver.test", device_id: "test" });
  
await expect(client.whoami()).resolves.toEqual({
  user_id: "@drainpixie:homeserver.test",
  device_id: "test",
});

Future #

• Automated CI checks against the Matrix OpenAPI Spec
• E2E against real homeservers