How to test Next.js app router

Searching for a good solution to test a Next.js app router is something that I've been struggling with for a while. I recently stumbled upon a tidbit hidden in the Next.js docs for Vitest that suggests the answer. Next.js currently has no solution for testing app router, so they recommend using end-to-end testing.

Rather than waiting around for a proper testing solution, I decided to follow the end-to-end testing path. One thing that makes this extremely powerful is being about to use Vercel for deployments. Also hidden in the Vercel docs is a section about running end-to-end tests on Vercel Preview Deployments. This is great because preview deployments are (mostly) the same as production deployments, making it a great way to test your application before deploying it to production, or before merging a PR.

By skipping straight to the end-to-end testing path, you gain the advantage of being able to test the actual application, rather than just a static snapshot of the application using something like React Testing Library. But the disadvantage is that the tests are slower and more expensive to run. So you need to think more critically about what you're testing.

I had previously used Vitest (Jest would also work similarly) for testing my Next.js app router using the following:

describe(Page.name, () => {
  it('should throw not found error for invalid page type', async () => {
    await expect(() =>
      Page({
        params: {
            parent: 'not-a-valid-parent',
        },
      }),
    ).rejects.toEqual(new Error('NEXT_NOT_FOUND'));
  });

  it('should redirect if page not found', async () => {
    await expect(() =>
      Page({
        params: {
          parent: 'parent',
          id: 'does-not-exist',
        },
      }),
    ).rejects.toEqual(new Error('NEXT_REDIRECT')); // TODO: Where?
  });
});

Unfortunately due to the way that Next.js throws the errors that's as far as I could get. There's no way that I could see to even test where the redirect is going to. Because it's not officially supported, it has also been prone to break across versions.

For now, I definitely recommend skipping straight to end-to-end testing with either Cypress or Playwright. By plumbing these into your CI pipeline triggered by your Vercel preview deployments, you can test your application in the most realistic way. Hopefully Next.js will have better first class support for testing in the future.