What's the point of this library, comparing it to supertest with your own testClient?

[larscyl]

I found this library via some online discussions. Looking through it, the only point of it is that it removes some boilerplates that you would have with e.g. supertest:

import { RequestListener, createServer } from "http";
import { NextApiHandler } from "next";
import { apiResolver } from "next/dist/server/api-utils/node/api-resolver";
import request from "supertest";
import handler from "src/pages/api/hello-world";

const testClient = (handler: NextApiHandler) => {
  const listener: RequestListener = (req, res) => {
    return apiResolver(
      req,
      res,
      undefined,
      handler,
      {
        previewModeEncryptionKey: "",
        previewModeId: "",
        previewModeSigningKey: "",
      },
      false,
    );
  };

  return request(createServer(listener));
};

test("API responds with 'hello-world'", async () => {
  const client = testClient(handler);
  const response = await client.get("/api/hello-world").expect(200);

  expect(response.body.message).toBe("Hello World!");
});

So, what does next-test-api-route-handler do differently or better?

[Xunnamius]

Hey @larscyl! I actually saw your comment on Reddit (or, at least, I think it was you), but for some reason I could not interact with that post.

A few things:

First, note how you're using the old Pages Router API resolver. The new App Router API resolver is much more involved than just calling a function, including, for instance: patching the global fetch function, supporting the magic helper functions via AsyncLocalStorage, and passing around a proper NextRequest object.

Second, the thing about relying on internal APIs like AppRouteRouteModule (app router) or apiResolver (pages router) is that Vercel makes no guarantees about these primitives. If you take a peek at NTARH's source, you'll notice that the location of the apiResolver function changes without warning between major, minor, and even patch versions.

Additionally, note how your use of apiResolver does not read well. I look over the parameters and I have little idea what they mean; for instance, I'd have to reference the function definition to see what is "undefined" and what is "false" and what this random object and its properties mean. On the other hand, NTARH's implementation makes it clear what's going on even when you, or a colleague, come back to the unit tests a year or two later... and even if Vercel adds extra parameters or otherwise changes the interface of this internal function, NTARH can still maintain the same interface and does. NTARH supports the pages router for the last 5 versions of Next.js (since the API feature was first introduced). Your example above, on the other hand, will simply fail unexpectedly and quite randomly after any semver patch or minor bump, and therefore does not translate between Next.js versions without extra work.

In terms of performance, NTARH uses a lightweight node:http server to call Next.js internals. It is "lightning fast" compared to spinning up Next.js to run your tests against, which is what the Vercel/Next team recommends. As for a node:http server versus something like supertest, I'd rather not add even more layers of mocking between Next.js and the API endpoint under test, mostly because I'm not familiar with these libraries' internals or how they function and what complications they will introduce.

[larscyl]

Thanks for the swift reply @Xunnamius!

From what I can read, NTARH removes a lot of overhead, boilerplate and maintenance for testing NextJS API's.

In terms of performance, I can see the advantage of using node:http, but I'm curious if we're not loosing reliability at the cost of performance. Are there no edge cases or other scenarios that a NextJS server handles compared to your custom server environment?

[Xunnamius]

There is plenty of functionality that Next.js handles that NTARH does not. These features are listed here. NTARH also does not provide support for the edge runtime.

If you mean functionality relating specifically to api routes, you can go through the Next.js source (or set a breakpoint in your handler function and move up the stack) to see what makes apiResolver and AppRouteRouteModule good targets for emulating Next.js's API handling. If there is additional functionality missing beyond what is listed in the NTARH documentation, I'm not aware of it.

[larscyl]

Awesome, thanks!