Docs: Add App Router Testing Guides and update /examples

[delbaoliveira]

This PR updates the testing guides to use App Router and TypeScript, also updates /examples to show app and pages examples.

Overview

• Create a new "Testing" section that is shared between app and pages.
• Explain the differences between E2E, unit testing, component testing, etc.
  • Recommend E2E for async components as currently none of the tools support it.
• Update setup guides for Cypress, Playwright, and Jest with latest config options, and examples for app and pages.
• Add new guide for Vitest
• Clean up /examples: use TS, show app and pages examples, match docs config

Cypress

• E2E Tests
• Component Testing
  • Client Components
  • Server Components
  • async components

Blockers:

• TS: Option 'bundler' can only be used when 'module' is set to 'es2015' or later. In tsconfig.json compilerOptions, Next.js uses "moduleResolution": "bundler", changing it to "node" fixes the issue but it can have repercussions.
  • Unable to compile TypeScript with "moduleResolution": "bundler" option in v5 cypress-io/cypress#27731
• Version 14 is currently not supported for component testing
  • Add support of Next.JS 14 cypress-io/cypress#28185

Playwright

• E2E Tests

Jest

• Unit Testing
  • Client Components
  • Server Components
  • async components: Support for React Server Components testing-library/react-testing-library#1209
  • 'server-only': fix(next-swc): skips client/server only checks when running with Jest to unblock testing #54891
• Snapshot Testing

Blockers:

• TS: Property 'toBeInTheDocument' does not exist on type 'JestMatchers<HTMLElement>' testing-library/jest-dom#546
  • None of the solutions in the issue work with Next.js v14.0.4 and TS v5

Vitest

• Unit Testing
  • Client Components
  • Server Components
  • async components
  • 'server-only'
• Update vitest example
• Handles CSS, and CSS modules imports
• Handles next/image

Other

• [NEXT-889] Unable to Test Server Components in Next.js 13 App Dir #47448
• [NEXT-863] Unable to test page components using metadata API with Jest #47299

[github-actions]

All broken links are now fixed, thank you!

[philwolstenholme]

This looks really promising :)

The explanation of how to replicate some (?) of what the Next compiler does for Jest is really useful. Would it be possible to add a section for people who want to switch to Vitest but are a bit worried about moving away from next/jest making things 'just work'.

At a guess, I imagine it'd be very similar to the Jest config below, plus the mock files for images, CSS etc, but using the Vitest config keys rather than Jest's?

module.exports = {
  collectCoverage: true,
  // on node 14.x coverage provider v8 offers good speed and more or less good report
  coverageProvider: 'v8',
  collectCoverageFrom: [
    '**/*.{js,jsx,ts,tsx}',
    '!**/*.d.ts',
    '!**/node_modules/**',
    '!<rootDir>/out/**',
    '!<rootDir>/.next/**',
    '!<rootDir>/*.config.js',
    '!<rootDir>/coverage/**',
  ],
  moduleNameMapper: {
    // Handle CSS imports (with CSS modules)
    // https://jestjs.io/docs/webpack#mocking-css-modules
    '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',

    // Handle CSS imports (without CSS modules)
    '^.+\\.(css|sass|scss)$': '<rootDir>/__mocks__/styleMock.js',

    // Handle image imports
    // https://jestjs.io/docs/webpack#handling-static-assets
    '^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i': `<rootDir>/__mocks__/fileMock.js`,

    // Handle module aliases
    '^@/components/(.*)$': '<rootDir>/components/$1',
  },
  // Add more setup options before each test is run
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
  testEnvironment: 'jsdom',
  transform: {
    // Use babel-jest to transpile tests with the next/babel preset
    // https://jestjs.io/docs/configuration#transform-objectstring-pathtotransformer--pathtotransformer-object
    '^.+\\.(js|jsx|ts|tsx)$': ['babel-jest', { presets: ['next/babel'] }],
  },
  transformIgnorePatterns: [
    '/node_modules/',
    '^.+\\.module\\.(css|sass|scss)$',
  ],
}

[delbaoliveira]

@philwolstenholme thank you for the feedback. Good news! While updating the Vitest example, I didn't need to do a lot of configuration as Vitest handles most of it by default. E.g. Handling CSS imports, images, etc.