Docs: Next-Js API Route Unit Testing

[robreinhard]

What is the improvement or update you wish to see?

I would like to write more in-depth documentation for creating next.js api route unit tests. I'm willing to do the work, and provide examples. I just want to make sure that work will be approved.

Is there any context that might help us understand?

There is no clear documentation for creating next-js api route unit tests. Existing documentation and tutorials on third party sites requires installing of third party npm packages. I want to create official documentation that does not require that.

Current unit testing documentation focuses more on front-end testing.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/testing#jest-and-react-testing-library

[balazsorban44]

Hi, I think the preferred way of testing API routes would be to spin up a Next.js server and use something like Playwright to cover a real production scenario. (We are using the same to test API routes in the Next.js repo as well.)

If you want to write unit tests, you'll need to mock/stub NextApiRequest and NextApiResponse which in the long term would be more cumbersome and extra maintenance work, especially with the introduction of Edge API routes.

See this similar package next-page-tester/next-page-tester#303 with a similar goal that has been deprecated because of the above-mentioned reason.

[robreinhard]

@balazsorban44 as someone who still thinks there are cases where Playwright for our API controllers is not sufficient, can we discuss this further?

Yes, you have to stub the request and response bodies, but that's the same for any unit test. And in browser testing does not work for all scenarios. Having this available would allow you to test for things in the controller or other backend layers specifically, such as appropriate error handling.

And maybe I'm wrong, but is that linked package for testing next.js api routes specifically? It looks to be more for client-side handling.

I think there is obvious need for this because so many third party and discussions are trying to solve this in fairly convoluted ways. Plus it's not that difficult, outside of set-up.

[robreinhard]

To expand upon this, the documentation also not make it clear that api routes should be tested with node as opposed to jest-environment-jsdom

People who are attempting to use next-auth have run into issues because of this.

It also doesn't help that jest.config.js does not seem to handle projects correctly, it has to be done in package.json for some reason.

[github-actions]

This closed issue has been automatically locked because it had no new activity for a month. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.