refactor: land Clerk example and other small refactorings

Author: Xunnamius

.github/workflows/run-apollo-app-example.yml

@@ -57,5 +57,5 @@ jobs:
           echo 'module.exports={"presets":["next/babel"]};' > babel.config.js
           mkdir -p app/api/graphql
           curl -o app/api/graphql/route.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_route
-          curl -o test/my.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_test
+          curl -o test/integration.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_test
           npx jest

.github/workflows/run-apollo-pages-example.yml

@@ -61,5 +61,5 @@ jobs:
           # npm install --force [email protected] next-server
           echo 'module.exports={"presets":["next/babel"]};' > babel.config.js
           mkdir test
-          curl -o test/my.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw
+          curl -o test/integration.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw
           npx jest

README.md

@@ -647,8 +647,8 @@ These examples use Next.js's [App Router][51] API.
 #### Testing Apollo's Official Next.js Integration @ `app/api/graphql`
 
 This example is based on [the official Apollo Next.js App Router
-integration][52]. You can easily run it yourself by copying and pasting the
-following commands into your terminal.
+integration][52]. You can run it yourself by copying and pasting the following
+commands into your terminal.
 
 > The following should be run in a nix-like environment. On Windows, that's
 > [WSL][53]. Requires `curl`, `node`, and `git`.
@@ -660,13 +660,15 @@ npm install --force next @apollo/server @as-integrations/next graphql-tag next-t
 echo 'module.exports={"presets":["next/babel"]};' > babel.config.js
 mkdir -p app/api/graphql
 curl -o app/api/graphql/route.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_route
-curl -o test/my.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_test
+curl -o test/integration.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw_app_test
 npx jest
 ```
 
-The above script creates a new temporary directory, installs NTARH and
-configures dependencies, downloads the [app route][54] and [jest test][55] files
-shown below, and runs the test using [jest][56].
+This script creates a new temporary directory, installs NTARH and configures
+dependencies, downloads the [app route][54] and [jest test][55] files shown
+below, and runs the test using [jest][56].
+
+The following is our new app route:
 
 ```typescript
 /* File: app/api/graphql/route.js */
@@ -697,8 +699,11 @@ const handler = startServerAndCreateNextHandler(server);
 export { handler as GET, handler as POST };
 ```
 
+And with the following jest test, we ensure our route integrates with Apollo
+correctly:
+
 ```typescript
-/* File: tests/my.test.js */
+/* File: tests/integration.test.js */
 
 import { testApiHandler } from 'next-test-api-route-handler';
 // Import the handler under test from the app/api directory
@@ -740,27 +745,84 @@ describe('my-test (app router)', () => {
 
 #### Testing Clerk's Official Next.js Integration @ `app/api/authed`
 
-Suppose we have an _authenticated_ API endpoint built using [Clerk's quick-start
-guide for Next.js][57], or perhaps [from their official demo repo][58].
+Suppose we created a new _authenticated_ API endpoint at `app/api/authed` using
+[Clerk's quick-start guide for Next.js][57]:
+
+```typescript
+/* File: app/api/authed/route.ts */
+
+import { auth } from '@clerk/nextjs';
+
+export async function GET() {
+  const { userId } = auth();
+  return Response.json({ isAuthed: !!userId, userId });
+}
+```
 
-How might we test that this endpoint behaves as we expect?
+How might we test that this endpoint functions as we expect?
 
 ```typescript
 /* File: test/unit.test.ts */
 
+import * as Clerk from '@clerk/nextjs';
 import { testApiHandler } from 'next-test-api-route-handler';
-import * as appHandler from '../app/api/authed/route';
 
-it('', async () => {
+import * as appHandler from './app/api/authed/route';
+
+let mockedClerkAuthReturnValue:
+  | Partial<ReturnType<(typeof Clerk)['auth']>>
+  | undefined = undefined;
+
+jest.mock('@clerk/nextjs', () => {
+  return {
+    auth() {
+      return mockedClerkAuthReturnValue;
+    }
+  };
+});
+
+afterEach(() => {
+  mockedClerkAuthReturnValue = undefined;
+});
+
+it('returns isAuthed: true and a userId when authenticated', async () => {
   expect.hasAssertions();
 
+  mockedClerkAuthReturnValue = { userId: 'winning' };
+
   await testApiHandler({
     appHandler,
-    test: async ({ fetch }) => // TODO
+    test: async ({ fetch }) => {
+      await expect((await fetch()).json()).resolves.toStrictEqual({
+        isAuthed: true,
+        userId: 'winning'
+      });
+    }
+  });
+});
+
+it('returns isAuthed: false and nothing else when unauthenticated', async () => {
+  expect.hasAssertions();
+
+  mockedClerkAuthReturnValue = { userId: null };
+
+  await testApiHandler({
+    appHandler,
+    test: async ({ fetch }) => {
+      await expect((await fetch()).json()).resolves.toStrictEqual({
+        isAuthed: false,
+        userId: null
+      });
+    }
   });
 });
 ```
 
+If you're feeling more adventurous, you can turn this unit test into an
+_integration_ test by calling [`authMiddleware`][58] in `requestPatcher` instead
+of mocking `@clerk/nextjs`. For insight into what you'd need to mock to make
+this work, check out [Clerk's own tests][59].
+
 #### Testing an Unreliable Handler on the Edge @ `app/api/unreliable`
 
 Suppose we have an API endpoint we use to test our application's error handling.
@@ -846,11 +908,11 @@ it('injects contrived errors at the required rate', async () => {
 
 ### Using the Pages Router
 
-These examples use Next.js's [Pages Router][59] API.
+These examples use Next.js's [Pages Router][60] API.
 
 #### Testing Next.js's Official Apollo Example @ `pages/api/graphql`
 
-This example uses the [official Next.js Apollo demo][60]. You can easily run it
+This example uses the [official Next.js Apollo demo][61]. You can easily run it
 yourself by copying and pasting the following commands into your terminal.
 
 > The following should be run in a nix-like environment. On Windows, that's
@@ -867,21 +929,21 @@ npm install --force next-test-api-route-handler jest babel-jest @babel/core @bab
 # npm install --force [email protected] next-server
 echo 'module.exports={"presets":["next/babel"]};' > babel.config.js
 mkdir test
-curl -o test/my.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw
+curl -o test/integration.test.js https://raw.githubusercontent.com/Xunnamius/next-test-api-route-handler/main/apollo_test_raw
 npx jest
 ```
 
-The above script clones [the Next.js repository][61], installs NTARH and
-configures dependencies, downloads the [jest test][62] file shown below, and
-runs it using [jest][56].
+This script clones [the Next.js repository][62], installs NTARH and configures
+dependencies, downloads the [jest test][63] file shown below, and runs it using
+[jest][56] to ensure our route integrates with Apollo correctly.
 
 > \[!IMPORTANT]\
-> Note that passing the [route configuration object][63] (imported below as `config`)
-> through to NTARH and setting `request.url` to the proper value is **[crucial][64]**
-> when testing Apollo endpoints using the Pages Router!
+> Note that passing the [route configuration object][64] (imported below as `config`)
+> through to NTARH and setting `request.url` to the proper value [may be necessary][65]
+> when testing Apollo endpoints using the Pages Router.
 
 ```typescript
-/* File: examples/api-routes-apollo-server-and-client/tests/my.test.js */
+/* File: examples/api-routes-apollo-server-and-client/tests/integration.test.js */
 
 import { testApiHandler } from 'next-test-api-route-handler';
 // Import the handler under test from the pages/api directory
@@ -1128,52 +1190,60 @@ Further documentation can be found under [`docs/`][x-repo-docs].
 Since NTARH is meant for unit testing API routes rather than faithfully
 recreating Next.js functionality, NTARH's feature set comes with some caveats.
 Namely: no Next.js features will be available that are external to processing
-API routes and executing their handlers. This includes [middleware][65] (see
-[`requestPatcher`][66] if you need to mutate the `Request` before it gets to the
-handler under test), [metadata][67], [static assets][68], [OpenTelemetry][69]
-and [instrumentation][70], [caching][71], [styling][72], [server actions and
-mutations][73], [helper functions][5] (except: `cookies`, `fetch` (global),
+API routes and executing their handlers. This includes [middleware][66] (see
+[`requestPatcher`][67] if you need to mutate the `Request` before it gets to the
+handler under test), [metadata][68], [static assets][69], [OpenTelemetry][70]
+and [instrumentation][71], [caching][72], [styling][73], [server actions and
+mutations][74], [helper functions][5] (except: `cookies`, `fetch` (global),
 `headers`, `NextRequest`/`NextResponse`, `notFound`, `permanentRedirect`,
-`redirect`, and `userAgent`), and anything related to React or [components][74].
+`redirect`, and `userAgent`), and anything related to React or [components][75].
 
 NTARH is for testing your API route handlers only.
 
-Further, any support NTARH appears to have for any "[edge runtime][75]" (or any
-other runtime) beyond what is provided by [`AppRouteRouteModule`][76] is merely
+Further, any support NTARH appears to have for any "[edge runtime][76]" (or any
+other runtime) beyond what is provided by [`AppRouteRouteModule`][77] is merely
 cosmetic. **Your tests will always run in Node.js** (or your runner of choice)
 and never in a different runtime, realm, or VM. This means unit testing like
 with NTARH must be done in addition to, and not in lieu of, more holistic
-testing practices (e.g. [end-to-end][77]).
+testing practices (e.g. [end-to-end][78]).
 
 If you're having trouble with your App Router and/or Edge Runtime routes,
 consider [opening a new issue][x-repo-choose-new-issue]!
 
+> Also note that Next.js's middleware **only supports the Edge runtime**, even
+> if the Next.js application is being run entirely by Node.js. This is an
+> artificial constraint imposed by Next.js; when running the middleware locally
+> (via `npm run dev` or something similar), the middleware will still run on
+> Node.js.
+>
+> Next.js's middleware limitation is discussed at length [here][79].
+
 ### Legacy Runtime Support
 
 As of version `4.0.0`, NTARH supports both the App Router (for `next@>=14.0.4`)
 and the "legacy" Pages Router Next.js APIs.
 
 Additionally, as of version `2.1.0`, NTARH is fully backwards compatible with
 Next.js going _allll_ the way back to `[email protected]` [when API routes were first
-introduced][78]!
+introduced][80]!
 
 If you're working with `next@<9.0.6` (so: [before `next-server` was merged into
-`next`][79]), you might need to install `next-server` manually:
+`next`][81]), you might need to install `next-server` manually:
 
 ```shell
 npm install --save-dev next-server
 ```
 
 Similarly, if you are using `npm@<7` or `node@<15`, you must install Next.js
 _and its peer dependencies_ manually. This is because [`npm@<7` does not install
-peer dependencies by default][80].
+peer dependencies by default][82].
 
 ```shell
 npm install --save-dev next@latest react
 ```
 
 > If you're also using an older version of Next.js, ensure you install the [peer
-> dependencies (like `react`) that your specific Next.js version requires][81]!
+> dependencies (like `react`) that your specific Next.js version requires][83]!
 
 ### Inspiration
 
@@ -1193,8 +1263,8 @@ ballooning the execution time of the tests. That is: no spinning up the entire
 Next.js runtime just to run a single test in isolation.
 
 It doesn't seem like it'd be such a lift to surface a wrapped version of the
-Pages Router's [`apiResolver`][82] function and a pared-down subclass of the App
-Router's [`AppRouteRouteModule`][76], both accessible with something like
+Pages Router's [`apiResolver`][84] function and a pared-down subclass of the App
+Router's [`AppRouteRouteModule`][77], both accessible with something like
 `import { ... } from 'next/test'`. This is essentially what NTARH does.
 
 ### Published Package Details
@@ -1458,39 +1528,42 @@ specification. Contributions of any kind welcome!
 [55]: ./apollo_test_raw_app_test
 [56]: https://www.npmjs.com/package/jest
 [57]: https://clerk.com/docs/quickstarts/nextjs
-[58]: https://github.com/clerk/clerk-nextjs-demo-app-router
-[59]: https://nextjs.org/docs/pages
-[60]:
+[58]: https://clerk.com/docs/references/nextjs/auth-middleware
+[59]:
+  https://github.com/clerk/javascript/blob/434a96ebefc550b726b417788b7bae9e41791408/packages/nextjs/src/server/authMiddleware.test.ts#L4
+[60]: https://nextjs.org/docs/pages
+[61]:
   https://github.com/vercel/next.js/tree/deprecated-main/examples/api-routes-apollo-server-and-client
-[61]: https://github.com/vercel/next.js
-[62]: ./apollo_test_raw
-[63]: https://nextjs.org/docs/api-routes/api-middlewares#custom-config
-[64]: https://github.com/Xunnamius/next-test-api-route-handler/issues/56
-[65]: https://nextjs.org/docs/app/building-your-application/routing/middleware
-[66]: #requestpatcher-url
-[67]: https://nextjs.org/docs/app/building-your-application/optimizing#metadata
-[68]:
-  https://nextjs.org/docs/app/building-your-application/optimizing#static-assets
+[62]: https://github.com/vercel/next.js
+[63]: ./apollo_test_raw
+[64]: https://nextjs.org/docs/api-routes/api-middlewares#custom-config
+[65]: https://github.com/Xunnamius/next-test-api-route-handler/issues/56
+[66]: https://nextjs.org/docs/app/building-your-application/routing/middleware
+[67]: #requestpatcher-url
+[68]: https://nextjs.org/docs/app/building-your-application/optimizing#metadata
 [69]:
-  https://nextjs.org/docs/pages/building-your-application/optimizing/open-telemetry
+  https://nextjs.org/docs/app/building-your-application/optimizing#static-assets
 [70]:
+  https://nextjs.org/docs/pages/building-your-application/optimizing/open-telemetry
+[71]:
   https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
-[71]: https://nextjs.org/docs/app/building-your-application/caching
-[72]: https://nextjs.org/docs/app/building-your-application/styling
-[73]:
+[72]: https://nextjs.org/docs/app/building-your-application/caching
+[73]: https://nextjs.org/docs/app/building-your-application/styling
+[74]:
   https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
-[74]: https://nextjs.org/docs/app/api-reference/components
-[75]:
-  https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#runtime
+[75]: https://nextjs.org/docs/app/api-reference/components
 [76]:
-  https://github.com/vercel/next.js/blob/0aa0179246d4e59f74cd1d62e3beb8e9b670fc4e/packages/next/src/server/future/route-modules/app-route/module.ts#L118C24-L118C24
+  https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#runtime
 [77]:
+  https://github.com/vercel/next.js/blob/0aa0179246d4e59f74cd1d62e3beb8e9b670fc4e/packages/next/src/server/future/route-modules/app-route/module.ts#L118C24-L118C24
+[78]:
   https://nextjs.org/docs/app/building-your-application/testing#types-of-tests
-[78]: https://nextjs.org/blog/next-9
-[79]: https://github.com/vercel/next.js/pull/8613
-[80]:
+[79]: https://github.com/vercel/next.js/discussions/46722
+[80]: https://nextjs.org/blog/next-9
+[81]: https://github.com/vercel/next.js/pull/8613
+[82]:
   https://github.blog/2021-02-02-npm-7-is-now-generally-available#peer-dependencies
-[81]:
+[83]:
   https://github.com/vercel/next.js/blob/v9.0.0/packages/next/package.json#L106-L109
-[82]:
+[84]:
   https://github.com/vercel/next.js/blob/90f95399ddfd036624c69b09910f40fa36c00ac2/packages/next/src/server/api-utils/node/api-resolver.ts#L321

apollo_test_raw

@@ -1,4 +1,4 @@
-/* File: examples/api-routes-apollo-server-and-client/tests/my.test.js */
+/* File: examples/api-routes-apollo-server-and-client/tests/integration.test.js */
 
 import { testApiHandler } from 'next-test-api-route-handler';
 // Import the handler under test from the pages/api directory

apollo_test_raw_app_test

@@ -1,4 +1,4 @@
-/* File: tests/my.test.js */
+/* File: tests/integration.test.js */
 
 import { testApiHandler } from 'next-test-api-route-handler';
 // Import the handler under test from the app/api directory