Add Testing guide to documentation

[balazsorban44]

Feature request

Is your feature request related to a problem? Please describe.

I am a fan of testing, and now that we go with Next.js at my company, I started thinking about how we should test pages. I immediately wanted to go with react-testing-library because of its simplicity, and that it is mainly framework agnostic, although I hit a problem. I am talking about pages implementing one of the GS(S)P methods. In addition, _app, api routes, etc. maybe also should be taken into consideration here. All these makes testing pages a bit trickier than simply using react-testing-library.

Describe the solution you'd like

I would like the Next.js team - if they have an opinion - to consider putting their thoughts around testing of Next.js apps into the docs, so we get a good starting point.

Describe alternatives you've considered

I considered creating nextjs-testing-library (a fork of react-testing-library), that would make writing tests for Next.js pages as easy, as using react-testing-library. But as someone pointed out, it would mean, I should re-implement Next.js in a way, which is not optimal.
https://spectrum.chat/testing-library/help-react/creating-nextjs-testing-library-for-next-js-help-feedback-needed~cd940022-aaa2-46fb-8c37-59af9ea77990

I was suggested:

You're probably better of running next dev and using cypress or puppeteer or any other e2e testing framework of your choice.

by @eps1lon

And if the Next.js team also thinks this is the way to go, or they have a better alternative in mind, a few words around it in the documentation would be great! 🤗

[devdjdjdj]

In addition to testing the react components, a guide for testing the API routes would be helpful too.

[cmbirk]

I would be very interested in a guide to run Cypress tests against PR preview deployments. I'm working on setting that up now

[cmbirk]

If possible I would like to have a github action run Cypress against the vercel preview url, but I don't know how to get that information from the Zeit GH integration

[followbl]

@cmbirk we are currently utilizing github actions + cypress to run what I am now deeming a smoke test against the Vercel build preview...this just makes sure basic functionality is working...here is the github actions yml it's pretty simple to get up and running on each PR...

name: Deploy & Smoke Test
on: [pull_request]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: amondnet/vercel-action@v19.0.1+1
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }} # Required
          github-token: ${{ secrets.GITHUB_TOKEN }} #Optional
          vercel-org-id: ${{ secrets.VERCEL_TEAM_ID }} #Required
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} #Required
          scope: ${{ secrets.VERCEL_SCOPE }}
        id: build_vercel

      - name: Cypress Test
        uses: cypress-io/github-action@v1
        with:
          config: baseUrl=${{ steps.build_vercel.outputs.preview-url }}

Reason I stumbled upon this open issue is what we'd really like to get is a full integration-suite of cypress tests that runs against a test build (production build, with test env vars) of our nextjs application. Getting this to work to my knowledge is not very straight forward considering we leverage Vercel for our deployments with a serverless target...we'd have to run a server target and handle that in order to run the integration tests in a ci environment...which would also mean we're testing a totally different setup that we're deploying to production.

Interested in hearing how anyone else has approached this problem.

[mikealche]

The thing with puppeteer and Next.JS is that it's pretty difficult to tell when the route changes have ended, because the normal "waitForNavigation" method doesn't seem to work well with Next.JS routing

[ballPointPenguin]

I'm shocked that there isn't a word about testing in the Next docs, or on their homepage or anything. This feels like a big oversight.

When I evaluate a framework or library like this I look for the testing documentation and for where testing fits into the story of the library and the values of the maintainers.

See for example:

https://www.gatsbyjs.org/docs/testing/
https://angular.io/guide/testing
https://guides.emberjs.com/release/testing/
https://vue-test-utils.vuejs.org/

A notable exception to good testing docs is Svelte, but at least they offer a scrap of an explanation:
https://svelte.dev/faq#how-do-i-test-svelte-apps

[toomuchdesign]

When I started to use Next I was also concerned about heavily relying on e2e tests to test parts of the application that could be covered with cheaper/quicker DOM nodes tests running in Node.js (like Testing Library).

From my point if view, the main issue about testing Next pages is that the framework provides a lot of glue that you need to somehow replicate in order to not write tests for every single piece of your pages (getServerSideProps, getStaticProps, dynamic API, dynamic routing, etc..)

As a proof of concept I put together this library which tries to fill these gaps and provide a smoother testing experience without spinning up the actual Next server.

The idea consists of providing a Next path (like /post/33) and receiving back a the corresponding page element ready to be rendered with any DOM testing library.

The library is supposed to take care of:

• resolving provided routes into the matching page component
• calling Next.js data fetching methods (getServerSideProps or getStaticProps) if the case
• set up a mocked next/router provider initialized with the expected values (to test useRouter and withRouter)
• instantiating the page component with the expected props

The library is available on NPM as next-page-tester. Any feedback or contribution to validate (or not) this approach is appreciated.

[briangonzalez]

I have been using this (typescript) with some success today. It basically waits for the URL to contain a path and throws an errors if you aren't sent there within an interval.

export const waitForPath = async (
  path: string,
  page: Page,
  timeInMS = 1000
) => {
  const interval = 50
  const iterations = timeInMS / interval

  let foundPath = false
  for (let index = 0; index < iterations; index++) {
    const currentPath = page.url().split(/\.com|\.dev/)[1]

    if (currentPath === path) {
      foundPath = true
      break
    }

    await sleep(interval)
  }

  if (!foundPath)
    throw new Error(`Page did not navigate to ${path} within ${timeInMS}ms`)
}

[Vadorequest]

Maybe this will help a few people, here is an example of E2E testing with Cypress and Next.js.

https://github.com/UnlyEd/next-right-now/tree/v2-mst-aptd-at-lcz-sty/cypress

Tests are run by GitHub Action automatically (CI/CD).
https://github.com/UnlyEd/next-right-now/blob/v2-mst-aptd-at-lcz-sty/.github/workflows/deploy-vercel-staging.yml#L314

The repo also contains other testing examples. (unit/integration) using Jest/Enzyme/etc.

[theoludwig]

There is now a "Testing" documentation : https://nextjs.org/docs/testing
Related PR: #28064
Related discussions: #28173

[leerob]

Thanks for posting @divlo! If you would like to see additions to the documentation, please post back on the Discussion linked above.