Intergration with MSW

[SPAHI4]

I think it's a good idea to use counterfact in integration tests.
So, it could integrate into the MSW server and provide the ability to override a request for a specific test case with type safety.

[SPAHI4]

How it could look like in node environment, inspired by https://github.com/apollographql/graphql-testing-library

import { createMswHandler } from "counterpart";
import counterpartConfig from "../counterpartConfig.json";

const { handler, replaceHandlers } = createMswHandler(counterpartConfig, {
  // msw config
  delay: number | "infinite" | "real",
});

// setup
import { setupServer } from 'msw/node';

import { handler } from './counterpartHandler';

export const server = setupServer(handler);

// usage

describe('MyComponent', () => {
  it('should make API request', () => {
    using _disposed = replaceHandlers({
      'user/{userId}': ($) => $.response[200].random(),
    });
    render(<MyComponent />);
  });
});

[dethell]

I have a basic setup working (without very much hacking on the Counterfact imports). Now that we've proven we can use Counterfact to provide the handlers for MSW I'm going to work at distilling this down to something easily consumable. As of this writing it requires using custom commands if you're using MSW in browser mode (worker instead of server) so that the browser can communicate with the node process to call Counterfact. In server mode this shouldn't be required. I'll try to get good examples of each once this is all written up.

No exact ETA, just working on it as I'm able. Hoping for fully shippable in June 2025.

[pmcelhaney]

Thanks for the suggestion! I think what you're suggesting is very similar to #730

I think it's a low hanging fruit. I've just been waiting for someone to come along and say "I would use this". :)

[dethell]

@SPAHI4 I'm curious about your use case. Are you using MSW in the browser or server mode? I'm starting to pull together the code and documentation for using Counterfact with MSW in browser mode and not really working on how it will work in Node (Node should be simpler). I don't want to leave the Node world out but this first pass basically satisfies the Vitest Browser + MSW combination.

[dethell]

Version 1.4.0 supports MSW, but I didn't really write up how it works at present. Here's a quick rundown:

There are two new functions exported by Counterfact:

• createMswHandlers: This is called by the consuming application have Counterfact load all the routes and create MSW-compatible handlers in a local array. A minimal Counterfact config is needed for this call to tell it where to find your API cache and spec. These handlers will work with the Counterfact Dispatcher to correctly handle incoming requests. These handlers can't be passed directly back to MSW because they exist in Node and MSW exists in the browser. The bridge between browser and Node will attempt to serialize the handlers and they won't work, obviously. So CF creates a local map of handlers and then passes back to the consumer a list of all the routes that it created. It is then up to the consumer to loop through that array and create MSW-compatible handlers using the http method from MSW and in those handlers call the other new exported function:
• handleMswRequest: This is an exported function that will take an incoming request, find the appropriate handler in the local handler map, handle the request and pass back the results.

Here's a sample code site for Vitest Browser mode:

import { createMswHandlers, handleMswRequest } from 'counterfact';
import nodePath from 'node:path';
import type { BrowserCommand, BrowserCommandContext } from 'vitest/node';

export type MockRequest = {
    path: string;
    rawPath: string;
    method: string;
    body: unknown;
    headers: Record<string, string>;
    query: Record<string, string>;
};

export const mockServerMswHandlers: BrowserCommand<[]> = async () => {
    const destinationPath = nodePath
        .join(process.cwd(), './path/to/counterfact/api')
        .replaceAll('\\', '/');

    const basePath = nodePath.resolve(destinationPath).replaceAll('\\', '/');
    const config = {
        basePath,
        openApiPath: './path/to/api/openapi-spec.yml',
    };
    const handlers = await createMswHandlers(config);
    return handlers;
};

export const handleMockRequest: BrowserCommand<[request: MockRequest]> = async (
    _: BrowserCommandContext,
    request: MockRequest
) => {
    const response = await handleMswRequest(request);
    return response;
};

Now I can use these to create my handlers for MSW:

const counterfactHandlers = await commands.mockServerMswHandlers();
const mockHandlers: RequestHandler[] = counterfactHandlers
    .filter(handler => http[handler.method.toLowerCase()])
    .map(handler => {
        const { method, path } = handler;
        const lowerMethod = method.toLowerCase();
        return http[lowerMethod](path, async ({ request }) => {
            const { body, headers } = request;
            const url = new URL(request.url);
            // Convert search params to an object with string keys and values
            const query: Record<string, string> = {};
            url.searchParams.forEach((value, key) => {
                query[key] = value;
            });
            const req: MockRequest = {
                path: url.pathname,
                rawPath: path,
                method: method.toUpperCase(),
                body,
                headers,
                query,
            };
            const result = await commands.handleMockRequest(req);
            return HttpResponse.json(result.body);
        });
    });

const worker = setupWorker(...mockHandlers);

For now that rawPath is required by Counterfact to find the mapping. The raw path is the API call path that includes any path parameters such as /api/getMyPet/:id where the path is the actual app call like /api/getMyPet/123.

Hope that helps us get everyone going while we keep improving the DX.