🗺️ Testing Helpers

[mcansh]

Note
This RFC is currently just for unit testing with vitest/jest, but the helper would be used in a Storybook set up as well, but I haven't played a ton with what that could look like yet.

Prior Art:

• 🗺️ Storybook + Testing Helper #2481

Summary

This is a proposal for some new helpers for remix so that you can unit test a Remix Route without needing to manually mock everything under the sun. Note these helpers wouldn't be for testing a entire route module (importing your actual loader/action) as you would more than likely be hitting an actual database in that case and would be better off using a full integration test.

Note
These helpers will utilize [email protected] so that will need to be required in order to use them.

Background

It's currently next to impossible to test a Remix app without either manually mocking everything or extracting pieces out of components that don't use Remix hooks and pass everything in as props due to the hooks needing to read the manifest.

Proposal

Create a createRemixStub function which usage would look like:

function LikeButton({ liked, label, action }) {
  let fetcher = useFetcher();
  let isLiked = fetcher.formData?.get("liked") ?? liked;
  return (
    <fetcher.Form method="post" action={action}>
      <button
        aria-label={label}
        name="liked"
        value={String(!isLiked)}
        type="submit"
      >
        {isLiked ? "♥" : "♡"}
      </button>
    </fetcher.Form>
  );
}

function TestPost() {
  let post = useLoaderData();
    return (
      <LikeButton
        liked={post.liked}
        label={post.liked ? `Unlike ${post.title}` : `Like ${post.title}`}
        href={`/post/${post.id}`}
      />
    );
  }

let fakePost = { title: "Fake Post", liked: false, id: 1 };

let RemixStub = createRemixStub({
  routes: [
    {
      path: "post/:postId",
      loader() {
        return json(fakePost);
      },
      async action({ request }) {
        let formData = await request.formData();
        fakePost.liked = formData.get("liked") === "true";
        return json(fakePost);
      },
      element: <TestPost />,
    },
  ],
});

test("renders an empty heart initially", () => {
  render(<RemixStub initialEntries={['post/1]} />);
  // assertions
  expect(screen.getByRole("button").innerHTML).toMatch("♥");
});

Implementation

The implementation for the above example would look like the following

import * as React from "react";
import type { RouteObject } from "react-router-dom";
import { createMemoryRouter, RouterProvider } from "react-router-dom";

type RouterOptions = Parameters<typeof createMemoryRouter>[1];

export function createReactRouterStub(args: { routes: Array<RouteObject> }) {
  let RouterStub = (options?: RouterOptions) => {
    // TODO: create remix manifest from routes so we can use `useLoaderData`, `useFetcher`, etc.
    let router = createMemoryRouter(args.routes, options);
    return <RouterProvider router={router} />;
  };

  return RouterStub;
}

A non tested, but theoretical "duck punch" of fetch could look like:

function setupMockFetch(router: ReturnType<typeof createMemoryRouter>) {
  let originalFetch: typeof fetch;
  if (typeof beforeAll === "function") {
    beforeAll(() => {
      globalThis.fetch = fakeFetch;
    });
  }

  if (typeof afterAll === "function") {
    afterAll(() => {
      globalThis.fetch = originalFetch;
    });
  }

  function fakeFetch(
    input: RequestInfo | URL,
    init: RequestInit = {}
  ): Promise<Response> {
    let url: URL =
      typeof input === "string"
        ? new URL(input)
        : input instanceof Request
        ? new URL(input.url)
        : input;

    let method: RequestInit["method"] = init.method
      ? init.method
      : input instanceof Request
      ? input.method
      : "GET";

    let request =
      input instanceof Request
        ? input
        : new Request(input, { ...init, method });

    if (url.searchParams.has("_data")) {
      let matches = matchRoutes(router.routes, url);
      console.log(matches);
      if (!matches) {
        throw new Error(`Couldn't find matches for ${url.toString()}`);
      }

      let routeMatch = matches[matches.length - 1];
      let params = routeMatch ? routeMatch.params : {};
      if (
        typeof routeMatch.route.loader === "function" &&
        ["get", "head"].includes(method.toLowerCase())
      ) {
        return routeMatch.route.loader({ params, request });
      } else if (typeof routeMatch.route.action === "function") {
        return routeMatch.route.action({ params, request });
      }
    }

    return originalFetch(input, init);
  }
}

Open Questions

The big one is "how do we generate a Remix manifest and context from a RR route config?"

[chaance]

This looks great to me! Just to clarify, this is intended for unit/integration tests for components that call Remix hooks/components, yeah? I assume you wouldn't use this to test your actual route components.

[brophdawg11]

Thats my understanding - you'd be testing deeper components of your own that use Remix hooks that require Remix contexts.

Once we get Remix on 6.4, the only things that Remix will provide via a Remix-specific context are routeModules and manifest, both of which aren't used in most of the cases that folks would be testing.

However, Remix will in some cases be wrapping/re-exporting some aspects from 6.4, at least initially. For example, RR doesn't have <Link prefetch> and the prefetching implementation will rely on the manifest which won't be available via RouterProvider. So we'd need our stub to potentially stub a RemixContext with a manifest as well for folks to be able to use <Link prefetch> in their unit tests. Hopefully we can auto-generate some form of stub manifest, potentially from the incoming routes...

[ryanflorence]

Right, this is specifically for not caring about your app routes but testing components that use Remix APIs.

Simply put: unit testing reusable components designed for use inside of Remix.

[sergiodxa]

Why limit it to only reusable components to use inside a Remix app? From what I saw I could import the component of a route and test it with different loader data and actions.

And because createRemixStub expects an array of routes I could even add multiple routes and even test that after a Form submit or a Link click I go to a different route.

[ryanflorence]

Instead of duck punching fetch maybe we could pass in an internal load implementation on context that defaults to the modules in remix.

So inside of Remix components, instead of calling functions like loadData from remix-react/data.ts, it calls context.loadData. That context defaults to the data.ts file but the stubs pass in something else that calls the loaders in the test.

[brophdawg11]

I think I'm confused about the need to still duck punch fetch in a 6.4 world where we are using createMemoryRouter - can you elaborate on the use-case?

As an example of how I was envisioning it, when you call fetcher.load() in remix it goes:

transitionManager.send 
 -> (client)  match.route.loader (returned from createLoader)
 -> (client)  fetch
 -> (server) handleDataRequest
 -> (server) callRouteLoader
 -> (server) user-provided loader implementation

And we're talking about stubbing at the fetch level right before going over the wire.

When you introduce createMemoryRouter, the user-provided route.loader is the first thing that gets called so I was sort of envisioning we just use that as the stub and it would never make it to the fetch call since they'd just return some data directly from the client-side loader?

There is remix-specific logic in createLoader but I wasn't thinking it was relevant to unit tests. Looking closer the main things it does are:

• loadRouteModuleWithBlockingLinks - don't think we care about this in a unit test/storybook case?
• throwing Errors/returning Redirects - should be handled by the remix router
• isCatchResponse - this is likely different since the router doesn't know about catch versus error, but - if we threw up to the catch boundary the component being rendered in the view would be unmounted anyway so is there a use-case where this is relevant?
• extractData - should be handled by remix router