.
This commit is contained in:
Kismet Hasanaj
+319
@@ -0,0 +1,319 @@
|
||||
---
|
||||
title: How to set up Cypress with Next.js
|
||||
nav_title: Cypress
|
||||
description: Learn how to set up Cypress with Next.js for End-to-End (E2E) and Component Testing.
|
||||
---
|
||||
|
||||
[Cypress](https://www.cypress.io/) is a test runner used for **End-to-End (E2E)** and **Component Testing**. This page will show you how to set up Cypress with Next.js and write your first tests.
|
||||
|
||||
> **Warning:**
|
||||
>
|
||||
> - Cypress versions below 13.6.3 do not support [TypeScript version 5](https://github.com/cypress-io/cypress/issues/27731) with `moduleResolution:"bundler"`. However, this issue has been resolved in Cypress version 13.6.3 and later. [cypress v13.6.3](https://docs.cypress.io/guides/references/changelog#13-6-3)
|
||||
|
||||
<AppOnly>
|
||||
|
||||
## Quickstart
|
||||
|
||||
You can use `create-next-app` with the [with-cypress example](https://github.com/vercel/next.js/tree/canary/examples/with-cypress) to quickly get started.
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm create next-app --example with-cypress with-cypress-app
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npx create-next-app@latest --example with-cypress with-cypress-app
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn create next-app --example with-cypress with-cypress-app
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun create next-app --example with-cypress with-cypress-app
|
||||
```
|
||||
|
||||
</AppOnly>
|
||||
|
||||
## Manual setup
|
||||
|
||||
To manually set up Cypress, install `cypress` as a dev dependency:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add -D cypress
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install -D cypress
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add -D cypress
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add -D cypress
|
||||
```
|
||||
|
||||
Add the Cypress `open` command to the `package.json` scripts field:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"lint": "eslint",
|
||||
"cypress:open": "cypress open"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Run Cypress for the first time to open the Cypress testing suite:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm cypress:open
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm run cypress:open
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn cypress:open
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun run cypress:open
|
||||
```
|
||||
|
||||
You can choose to configure **E2E Testing** and/or **Component Testing**. Selecting any of these options will automatically create a `cypress.config.js` file and a `cypress` folder in your project.
|
||||
|
||||
## Creating your first Cypress E2E test
|
||||
|
||||
Ensure your `cypress.config` file has the following configuration:
|
||||
|
||||
```ts filename="cypress.config.ts" switcher
|
||||
import { defineConfig } from 'cypress'
|
||||
|
||||
export default defineConfig({
|
||||
e2e: {
|
||||
setupNodeEvents(on, config) {},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
```js filename="cypress.config.js" switcher
|
||||
const { defineConfig } = require('cypress')
|
||||
|
||||
module.exports = defineConfig({
|
||||
e2e: {
|
||||
setupNodeEvents(on, config) {},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Then, create two new Next.js files:
|
||||
|
||||
<AppOnly>
|
||||
|
||||
```jsx filename="app/page.js"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/about/page.js"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>About</h1>
|
||||
<Link href="/">Home</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
</AppOnly>
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
```jsx filename="pages/index.js"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Home() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/about.js"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function About() {
|
||||
return (
|
||||
<div>
|
||||
<h1>About</h1>
|
||||
<Link href="/">Home</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
Add a test to check your navigation is working correctly:
|
||||
|
||||
```js filename="cypress/e2e/app.cy.js"
|
||||
describe('Navigation', () => {
|
||||
it('should navigate to the about page', () => {
|
||||
// Start from the index page
|
||||
cy.visit('http://localhost:3000/')
|
||||
|
||||
// Find a link with an href attribute containing "about" and click it
|
||||
cy.get('a[href*="about"]').click()
|
||||
|
||||
// The new url should include "/about"
|
||||
cy.url().should('include', '/about')
|
||||
|
||||
// The new page should contain an h1 with "About"
|
||||
cy.get('h1').contains('About')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Running E2E Tests
|
||||
|
||||
Cypress will simulate a user navigating your application, this requires your Next.js server to be running. We recommend running your tests against your production code to more closely resemble how your application will behave.
|
||||
|
||||
Run `npm run build && npm run start` to build your Next.js application, then run `npm run cypress:open` in another terminal window to start Cypress and run your E2E Testing suite.
|
||||
|
||||
> **Good to know:**
|
||||
>
|
||||
> - You can use `cy.visit("/")` instead of `cy.visit("http://localhost:3000/")` by adding `baseUrl: 'http://localhost:3000'` to the `cypress.config.js` configuration file.
|
||||
> - Alternatively, you can install the [`start-server-and-test`](https://www.npmjs.com/package/start-server-and-test) package to run the Next.js production server in conjunction with Cypress. After installation, add `"test": "start-server-and-test start http://localhost:3000 cypress"` to your `package.json` scripts field. Remember to rebuild your application after new changes.
|
||||
|
||||
## Creating your first Cypress component test
|
||||
|
||||
Component tests build and mount a specific component without having to bundle your whole application or start a server.
|
||||
|
||||
Select **Component Testing** in the Cypress app, then select **Next.js** as your front-end framework. A `cypress/component` folder will be created in your project, and a `cypress.config.js` file will be updated to enable Component Testing.
|
||||
|
||||
Ensure your `cypress.config` file has the following configuration:
|
||||
|
||||
```ts filename="cypress.config.ts" switcher
|
||||
import { defineConfig } from 'cypress'
|
||||
|
||||
export default defineConfig({
|
||||
component: {
|
||||
devServer: {
|
||||
framework: 'next',
|
||||
bundler: 'webpack',
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
```js filename="cypress.config.js" switcher
|
||||
const { defineConfig } = require('cypress')
|
||||
|
||||
module.exports = defineConfig({
|
||||
component: {
|
||||
devServer: {
|
||||
framework: 'next',
|
||||
bundler: 'webpack',
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Assuming the same components from the previous section, add a test to validate a component is rendering the expected output:
|
||||
|
||||
<AppOnly>
|
||||
|
||||
```tsx filename="cypress/component/about.cy.tsx"
|
||||
import Page from '../../app/page'
|
||||
|
||||
describe('<Page />', () => {
|
||||
it('should render and display expected content', () => {
|
||||
// Mount the React component for the Home page
|
||||
cy.mount(<Page />)
|
||||
|
||||
// The new page should contain an h1 with "Home"
|
||||
cy.get('h1').contains('Home')
|
||||
|
||||
// Validate that a link with the expected URL is present
|
||||
// Following the link is better suited to an E2E test
|
||||
cy.get('a[href="/about"]').should('be.visible')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
</AppOnly>
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
```jsx filename="cypress/component/about.cy.js"
|
||||
import AboutPage from '../../pages/about'
|
||||
|
||||
describe('<AboutPage />', () => {
|
||||
it('should render and display expected content', () => {
|
||||
// Mount the React component for the About page
|
||||
cy.mount(<AboutPage />)
|
||||
|
||||
// The new page should contain an h1 with "About page"
|
||||
cy.get('h1').contains('About')
|
||||
|
||||
// Validate that a link with the expected URL is present
|
||||
// *Following* the link is better suited to an E2E test
|
||||
cy.get('a[href="/"]').should('be.visible')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Cypress currently doesn't support Component Testing for `async` Server Components. We recommend using E2E testing.
|
||||
> - Since component tests do not require a Next.js server, features like `<Image />` that rely on a server being available may not function out-of-the-box.
|
||||
|
||||
### Running Component Tests
|
||||
|
||||
Run `npm run cypress:open` in your terminal to start Cypress and run your Component Testing suite.
|
||||
|
||||
## Continuous Integration (CI)
|
||||
|
||||
In addition to interactive testing, you can also run Cypress headlessly using the `cypress run` command, which is better suited for CI environments:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
//...
|
||||
"e2e": "start-server-and-test dev http://localhost:3000 \"cypress open --e2e\"",
|
||||
"e2e:headless": "start-server-and-test dev http://localhost:3000 \"cypress run --e2e\"",
|
||||
"component": "cypress open --component",
|
||||
"component:headless": "cypress run --component"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can learn more about Cypress and Continuous Integration from these resources:
|
||||
|
||||
- [Next.js with Cypress example](https://github.com/vercel/next.js/tree/canary/examples/with-cypress)
|
||||
- [Cypress Continuous Integration Docs](https://docs.cypress.io/guides/continuous-integration/introduction)
|
||||
- [Cypress GitHub Actions Guide](https://on.cypress.io/github-actions)
|
||||
- [Official Cypress GitHub Action](https://github.com/cypress-io/github-action)
|
||||
- [Cypress Discord](https://discord.com/invite/cypress)
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Testing
|
||||
description: Learn how to set up Next.js with four commonly used testing tools — Cypress, Playwright, Vitest, and Jest.
|
||||
---
|
||||
|
||||
In React and Next.js, there are a few different types of tests you can write, each with its own purpose and use cases. This page provides an overview of types and commonly used tools you can use to test your application.
|
||||
|
||||
## Types of tests
|
||||
|
||||
- **Unit Testing** involves testing individual units (or blocks of code) in isolation. In React, a unit can be a single function, hook, or component.
|
||||
- **Component Testing** is a more focused version of unit testing where the primary subject of the tests is React components. This may involve testing how components are rendered, their interaction with props, and their behavior in response to user events.
|
||||
- **Integration Testing** involves testing how multiple units work together. This can be a combination of components, hooks, and functions.
|
||||
- **End-to-End (E2E) Testing** involves testing user flows in an environment that simulates real user scenarios, like the browser. This means testing specific tasks (e.g. signup flow) in a production-like environment.
|
||||
- **Snapshot Testing** involves capturing the rendered output of a component and saving it to a snapshot file. When tests run, the current rendered output of the component is compared against the saved snapshot. Changes in the snapshot are used to indicate unexpected changes in behavior.
|
||||
|
||||
<AppOnly>
|
||||
|
||||
## Async Server Components
|
||||
|
||||
Since `async` Server Components are new to the React ecosystem, some tools do not fully support them. In the meantime, we recommend using **End-to-End Testing** over **Unit Testing** for `async` components.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
## Guides
|
||||
|
||||
See the guides below to learn how to set up Next.js with these commonly used testing tools:
|
||||
+423
@@ -0,0 +1,423 @@
|
||||
---
|
||||
title: How to set up Jest with Next.js
|
||||
nav_title: Jest
|
||||
description: Learn how to set up Jest with Next.js for Unit Testing and Snapshot Testing.
|
||||
---
|
||||
|
||||
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
|
||||
Jest and React Testing Library are frequently used together for **Unit Testing** and **Snapshot Testing**. This guide will show you how to set up Jest with Next.js and write your first tests.
|
||||
|
||||
> **Good to know:** Since `async` Server Components are new to the React ecosystem, Jest currently does not support them. While you can still run **unit tests** for synchronous Server and Client Components, we recommend using an **E2E tests** for `async` components.
|
||||
|
||||
## Quickstart
|
||||
|
||||
You can use `create-next-app` with the Next.js [with-jest](https://github.com/vercel/next.js/tree/canary/examples/with-jest) example to quickly get started:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm create next-app --example with-jest with-jest-app
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npx create-next-app@latest --example with-jest with-jest-app
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn create next-app --example with-jest with-jest-app
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun create next-app --example with-jest with-jest-app
|
||||
```
|
||||
|
||||
## Manual setup
|
||||
|
||||
Since the release of [Next.js 12](https://nextjs.org/blog/next-12), Next.js now has built-in configuration for Jest.
|
||||
|
||||
To set up Jest, install `jest` and the following packages as dev dependencies:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
|
||||
```
|
||||
|
||||
Generate a basic Jest configuration file by running the following command:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm create jest@latest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm init jest@latest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn create jest@latest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun create jest@latest
|
||||
```
|
||||
|
||||
This will take you through a series of prompts to setup Jest for your project, including automatically creating a `jest.config.ts|js` file.
|
||||
|
||||
Update your config file to use `next/jest`. This transformer has all the necessary configuration options for Jest to work with Next.js:
|
||||
|
||||
```ts filename="jest.config.ts" switcher
|
||||
import type { Config } from 'jest'
|
||||
import nextJest from 'next/jest.js'
|
||||
|
||||
const createJestConfig = nextJest({
|
||||
// Provide the path to your Next.js app to load next.config.js and .env files in your test environment
|
||||
dir: './',
|
||||
})
|
||||
|
||||
// Add any custom config to be passed to Jest
|
||||
const config: Config = {
|
||||
coverageProvider: 'v8',
|
||||
testEnvironment: 'jsdom',
|
||||
// Add more setup options before each test is run
|
||||
// setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
|
||||
}
|
||||
|
||||
// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
|
||||
export default createJestConfig(config)
|
||||
```
|
||||
|
||||
```js filename="jest.config.js" switcher
|
||||
const nextJest = require('next/jest')
|
||||
|
||||
/** @type {import('jest').Config} */
|
||||
const createJestConfig = nextJest({
|
||||
// Provide the path to your Next.js app to load next.config.js and .env files in your test environment
|
||||
dir: './',
|
||||
})
|
||||
|
||||
// Add any custom config to be passed to Jest
|
||||
const config = {
|
||||
coverageProvider: 'v8',
|
||||
testEnvironment: 'jsdom',
|
||||
// Add more setup options before each test is run
|
||||
// setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
|
||||
}
|
||||
|
||||
// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
|
||||
module.exports = createJestConfig(config)
|
||||
```
|
||||
|
||||
Under the hood, `next/jest` is automatically configuring Jest for you, including:
|
||||
|
||||
- Setting up `transform` using the [Next.js Compiler](/docs/architecture/nextjs-compiler).
|
||||
- Auto mocking stylesheets (`.css`, `.module.css`, and their scss variants), image imports and [`next/font`](/docs/app/api-reference/components/font).
|
||||
- Loading `.env` (and all variants) into `process.env`.
|
||||
- Ignoring `node_modules` from test resolving and transforms.
|
||||
- Ignoring `.next` from test resolving.
|
||||
- Loading `next.config.js` for flags that enable SWC transforms.
|
||||
|
||||
> **Good to know**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.ts` file. For more information, please see [Test Environment Variables](/docs/app/guides/environment-variables#test-environment-variables).
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
## Setting up Jest (with Babel)
|
||||
|
||||
If you opt out of the [Next.js Compiler](/docs/architecture/nextjs-compiler) and use Babel instead, you will need to manually configure Jest and install `babel-jest` and `identity-obj-proxy` in addition to the packages above.
|
||||
|
||||
Here are the recommended options to configure Jest for Next.js:
|
||||
|
||||
```js filename="jest.config.js"
|
||||
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)$': `<rootDir>/__mocks__/fileMock.js`,
|
||||
|
||||
// Handle module aliases
|
||||
'^@/components/(.*)$': '<rootDir>/components/$1',
|
||||
|
||||
// Handle @next/font
|
||||
'@next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
|
||||
// Handle next/font
|
||||
'next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
|
||||
// Disable server-only
|
||||
'server-only': `<rootDir>/__mocks__/empty.js`,
|
||||
},
|
||||
// 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)$',
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
You can learn more about each configuration option in the [Jest docs](https://jestjs.io/docs/configuration). We also recommend reviewing [`next/jest` configuration](https://github.com/vercel/next.js/blob/e02fe314dcd0ae614c65b505c6daafbdeebb920e/packages/next/src/build/jest/jest.ts) to see how Next.js configures Jest.
|
||||
|
||||
### Handling stylesheets and image imports
|
||||
|
||||
Stylesheets and images aren't used in the tests but importing them may cause errors, so they will need to be mocked.
|
||||
|
||||
Create the mock files referenced in the configuration above - `fileMock.js` and `styleMock.js` - inside a `__mocks__` directory:
|
||||
|
||||
```js filename="__mocks__/fileMock.js"
|
||||
module.exports = 'test-file-stub'
|
||||
```
|
||||
|
||||
```js filename="__mocks__/styleMock.js"
|
||||
module.exports = {}
|
||||
```
|
||||
|
||||
For more information on handling static assets, please refer to the [Jest Docs](https://jestjs.io/docs/webpack#handling-static-assets).
|
||||
|
||||
## Handling Fonts
|
||||
|
||||
To handle fonts, create the `nextFontMock.js` file inside the `__mocks__` directory, and add the following configuration:
|
||||
|
||||
```js filename="__mocks__/nextFontMock.js"
|
||||
module.exports = new Proxy(
|
||||
{},
|
||||
{
|
||||
get: function getter() {
|
||||
return () => ({
|
||||
className: 'className',
|
||||
variable: 'variable',
|
||||
style: { fontFamily: 'fontFamily' },
|
||||
})
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
## Optional: Handling Absolute Imports and Module Path Aliases
|
||||
|
||||
If your project is using [Module Path Aliases](/docs/app/getting-started/installation#set-up-absolute-imports-and-module-path-aliases), you will need to configure Jest to resolve the imports by matching the paths option in the `jsconfig.json` file with the `moduleNameMapper` option in the `jest.config.js` file. For example:
|
||||
|
||||
```json filename="tsconfig.json or jsconfig.json"
|
||||
{
|
||||
"compilerOptions": {
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"baseUrl": "./",
|
||||
"paths": {
|
||||
"@/components/*": ["components/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```js filename="jest.config.js"
|
||||
moduleNameMapper: {
|
||||
// ...
|
||||
'^@/components/(.*)$': '<rootDir>/components/$1',
|
||||
}
|
||||
```
|
||||
|
||||
## Optional: Extend Jest with custom matchers
|
||||
|
||||
`@testing-library/jest-dom` includes a set of convenient [custom matchers](https://github.com/testing-library/jest-dom#custom-matchers) such as `.toBeInTheDocument()` making it easier to write tests. You can import the custom matchers for every test by adding the following option to the Jest configuration file:
|
||||
|
||||
```ts filename="jest.config.ts" switcher
|
||||
setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']
|
||||
```
|
||||
|
||||
```js filename="jest.config.js" switcher
|
||||
setupFilesAfterEnv: ['<rootDir>/jest.setup.js']
|
||||
```
|
||||
|
||||
Then, inside `jest.setup`, add the following import:
|
||||
|
||||
```ts filename="jest.setup.ts" switcher
|
||||
import '@testing-library/jest-dom'
|
||||
```
|
||||
|
||||
```js filename="jest.setup.js" switcher
|
||||
import '@testing-library/jest-dom'
|
||||
```
|
||||
|
||||
> **Good to know:** [`extend-expect` was removed in `v6.0`](https://github.com/testing-library/jest-dom/releases/tag/v6.0.0), so if you are using `@testing-library/jest-dom` before version 6, you will need to import `@testing-library/jest-dom/extend-expect` instead.
|
||||
|
||||
If you need to add more setup options before each test, you can add them to the `jest.setup` file above.
|
||||
|
||||
## Add a test script to `package.json`
|
||||
|
||||
Finally, add a Jest `test` script to your `package.json` file:
|
||||
|
||||
```json filename="package.json" highlight={6-7}
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"test": "jest",
|
||||
"test:watch": "jest --watch"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`jest --watch` will re-run tests when a file is changed. For more Jest CLI options, please refer to the [Jest Docs](https://jestjs.io/docs/cli#reference).
|
||||
|
||||
### Creating your first test
|
||||
|
||||
Your project is now ready to run tests. Create a folder called `__tests__` in your project's root directory.
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
For example, we can add a test to check if the `<Home />` component successfully renders a heading:
|
||||
|
||||
```jsx filename="pages/index.js
|
||||
export default function Home() {
|
||||
return <h1>Home</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="__tests__/index.test.js"
|
||||
import '@testing-library/jest-dom'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Home from '../pages/index'
|
||||
|
||||
describe('Home', () => {
|
||||
it('renders a heading', () => {
|
||||
render(<Home />)
|
||||
|
||||
const heading = screen.getByRole('heading', { level: 1 })
|
||||
|
||||
expect(heading).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
<AppOnly>
|
||||
|
||||
For example, we can add a test to check if the `<Page />` component successfully renders a heading:
|
||||
|
||||
```jsx filename="app/page.js"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="__tests__/page.test.jsx"
|
||||
import '@testing-library/jest-dom'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Page from '../app/page'
|
||||
|
||||
describe('Page', () => {
|
||||
it('renders a heading', () => {
|
||||
render(<Page />)
|
||||
|
||||
const heading = screen.getByRole('heading', { level: 1 })
|
||||
|
||||
expect(heading).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
</AppOnly>
|
||||
|
||||
Optionally, add a [snapshot test](https://jestjs.io/docs/snapshot-testing) to keep track of any unexpected changes in your component:
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
```jsx filename="__tests__/snapshot.js"
|
||||
import { render } from '@testing-library/react'
|
||||
import Home from '../pages/index'
|
||||
|
||||
it('renders homepage unchanged', () => {
|
||||
const { container } = render(<Home />)
|
||||
expect(container).toMatchSnapshot()
|
||||
})
|
||||
```
|
||||
|
||||
> **Good to know**: Test files should not be included inside the Pages Router because any files inside the Pages Router are considered routes.
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
<AppOnly>
|
||||
|
||||
```jsx filename="__tests__/snapshot.js"
|
||||
import { render } from '@testing-library/react'
|
||||
import Page from '../app/page'
|
||||
|
||||
it('renders homepage unchanged', () => {
|
||||
const { container } = render(<Page />)
|
||||
expect(container).toMatchSnapshot()
|
||||
})
|
||||
```
|
||||
|
||||
</AppOnly>
|
||||
|
||||
## Running your tests
|
||||
|
||||
Then, run the following command to run your tests:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm test
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm run test
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn test
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun run test
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
For further reading, you may find these resources helpful:
|
||||
|
||||
- [Next.js with Jest example](https://github.com/vercel/next.js/tree/canary/examples/with-jest)
|
||||
- [Jest Docs](https://jestjs.io/docs/getting-started)
|
||||
- [React Testing Library Docs](https://testing-library.com/docs/react-testing-library/intro/)
|
||||
- [Testing Playground](https://testing-playground.com/) - use good testing practices to match elements.
|
||||
+150
@@ -0,0 +1,150 @@
|
||||
---
|
||||
title: How to set up Playwright with Next.js
|
||||
nav_title: Playwright
|
||||
description: Learn how to set up Playwright with Next.js for End-to-End (E2E) Testing.
|
||||
---
|
||||
|
||||
Playwright is a testing framework that lets you automate Chromium, Firefox, and WebKit with a single API. You can use it to write **End-to-End (E2E)** testing. This guide will show you how to set up Playwright with Next.js and write your first tests.
|
||||
|
||||
## Quickstart
|
||||
|
||||
The fastest way to get started is to use `create-next-app` with the [with-playwright example](https://github.com/vercel/next.js/tree/canary/examples/with-playwright). This will create a Next.js project complete with Playwright configured.
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm create next-app --example with-playwright with-playwright-app
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npx create-next-app@latest --example with-playwright with-playwright-app
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn create next-app --example with-playwright with-playwright-app
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun create next-app --example with-playwright with-playwright-app
|
||||
```
|
||||
|
||||
## Manual setup
|
||||
|
||||
To install Playwright, run the following command:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm create playwright
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm init playwright
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn create playwright
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun create playwright
|
||||
```
|
||||
|
||||
This will take you through a series of prompts to setup and configure Playwright for your project, including adding a `playwright.config.ts` file. Please refer to the [Playwright installation guide](https://playwright.dev/docs/intro#installation) for the step-by-step guide.
|
||||
|
||||
## Creating your first Playwright E2E test
|
||||
|
||||
Create two new Next.js pages:
|
||||
|
||||
<AppOnly>
|
||||
|
||||
```tsx filename="app/page.tsx"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```tsx filename="app/about/page.tsx"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>About</h1>
|
||||
<Link href="/">Home</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
</AppOnly>
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
```tsx filename="pages/index.ts"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Home() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```tsx filename="pages/about.ts"
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function About() {
|
||||
return (
|
||||
<div>
|
||||
<h1>About</h1>
|
||||
<Link href="/">Home</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
Then, add a test to verify that your navigation is working correctly:
|
||||
|
||||
```ts filename="tests/example.spec.ts"
|
||||
import { test, expect } from '@playwright/test'
|
||||
|
||||
test('should navigate to the about page', async ({ page }) => {
|
||||
// Start from the index page (the baseURL is set via the webServer in the playwright.config.ts)
|
||||
await page.goto('http://localhost:3000/')
|
||||
// Find an element with the text 'About' and click on it
|
||||
await page.click('text=About')
|
||||
// The new URL should be "/about" (baseURL is used there)
|
||||
await expect(page).toHaveURL('http://localhost:3000/about')
|
||||
// The new page should contain an h1 with "About"
|
||||
await expect(page.locator('h1')).toContainText('About')
|
||||
})
|
||||
```
|
||||
|
||||
> **Good to know**: You can use `page.goto("/")` instead of `page.goto("http://localhost:3000/")`, if you add [`"baseURL": "http://localhost:3000"`](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) to the `playwright.config.ts` [configuration file](https://playwright.dev/docs/test-configuration).
|
||||
|
||||
### Running your Playwright tests
|
||||
|
||||
Playwright will simulate a user navigating your application using three browsers: Chromium, Firefox and Webkit, this requires your Next.js server to be running. We recommend running your tests against your production code to more closely resemble how your application will behave.
|
||||
|
||||
Run `npm run build` and `npm run start`, then run `npx playwright test` in another terminal window to run the Playwright tests.
|
||||
|
||||
> **Good to know**: Alternatively, you can use the [`webServer`](https://playwright.dev/docs/test-webserver/) feature to let Playwright start the development server and wait until it's fully available.
|
||||
|
||||
### Running Playwright on Continuous Integration (CI)
|
||||
|
||||
Playwright will by default run your tests in the [headless mode](https://playwright.dev/docs/ci#running-headed). To install all the Playwright dependencies, run `npx playwright install-deps`.
|
||||
|
||||
You can learn more about Playwright and Continuous Integration from these resources:
|
||||
|
||||
- [Next.js with Playwright example](https://github.com/vercel/next.js/tree/canary/examples/with-playwright)
|
||||
- [Playwright on your CI provider](https://playwright.dev/docs/ci)
|
||||
- [Playwright Discord](https://discord.com/invite/playwright-807756831384403968)
|
||||
+243
@@ -0,0 +1,243 @@
|
||||
---
|
||||
title: How to set up Vitest with Next.js
|
||||
nav_title: Vitest
|
||||
description: Learn how to set up Vitest with Next.js for Unit Testing.
|
||||
---
|
||||
|
||||
Vitest and React Testing Library are frequently used together for **Unit Testing**. This guide will show you how to setup Vitest with Next.js and write your first tests.
|
||||
|
||||
> **Good to know:** Since `async` Server Components are new to the React ecosystem, Vitest currently does not support them. While you can still run **unit tests** for synchronous Server and Client Components, we recommend using **E2E tests** for `async` components.
|
||||
|
||||
## Quickstart
|
||||
|
||||
You can use `create-next-app` with the Next.js [with-vitest](https://github.com/vercel/next.js/tree/canary/examples/with-vitest) example to quickly get started:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm create next-app --example with-vitest with-vitest-app
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npx create-next-app@latest --example with-vitest with-vitest-app
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn create next-app --example with-vitest with-vitest-app
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun create next-app --example with-vitest with-vitest-app
|
||||
```
|
||||
|
||||
## Manual Setup
|
||||
|
||||
To manually set up Vitest, install `vitest` and the following packages as dev dependencies:
|
||||
|
||||
```bash package="pnpm"
|
||||
# Using TypeScript
|
||||
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
|
||||
# Using JavaScript
|
||||
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
# Using TypeScript
|
||||
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
|
||||
# Using JavaScript
|
||||
npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
# Using TypeScript
|
||||
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
|
||||
# Using JavaScript
|
||||
yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
# Using TypeScript
|
||||
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom vite-tsconfig-paths
|
||||
# Using JavaScript
|
||||
bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom
|
||||
```
|
||||
|
||||
Create a `vitest.config.mts|js` file in the root of your project, and add the following options:
|
||||
|
||||
```ts filename="vitest.config.mts" switcher
|
||||
import { defineConfig } from 'vitest/config'
|
||||
import react from '@vitejs/plugin-react'
|
||||
import tsconfigPaths from 'vite-tsconfig-paths'
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [tsconfigPaths(), react()],
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
```js filename="vitest.config.js" switcher
|
||||
import { defineConfig } from 'vitest/config'
|
||||
import react from '@vitejs/plugin-react'
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
For more information on configuring Vitest, please refer to the [Vitest Configuration](https://vitest.dev/config/#configuration) docs.
|
||||
|
||||
Then, add a `test` script to your `package.json`:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"test": "vitest"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When you run `npm run test`, Vitest will **watch** for changes in your project by default.
|
||||
|
||||
## Creating your first Vitest Unit Test
|
||||
|
||||
Check that everything is working by creating a test to check if the `<Page />` component successfully renders a heading:
|
||||
|
||||
<AppOnly>
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.jsx" switcher
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```tsx filename="__tests__/page.test.tsx" switcher
|
||||
import { expect, test } from 'vitest'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Page from '../app/page'
|
||||
|
||||
test('Page', () => {
|
||||
render(<Page />)
|
||||
expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
|
||||
})
|
||||
```
|
||||
|
||||
```jsx filename="__tests__/page.test.jsx" switcher
|
||||
import { expect, test } from 'vitest'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Page from '../app/page'
|
||||
|
||||
test('Page', () => {
|
||||
render(<Page />)
|
||||
expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
|
||||
})
|
||||
```
|
||||
|
||||
> **Good to know**: The example above uses the common `__tests__` convention, but test files can also be colocated inside the `app` router.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
<PagesOnly>
|
||||
|
||||
```tsx filename="pages/index.tsx" switcher
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/index.jsx" switcher
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Home</h1>
|
||||
<Link href="/about">About</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```tsx filename="__tests__/index.test.tsx" switcher
|
||||
import { expect, test } from 'vitest'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Page from '../pages/index'
|
||||
|
||||
test('Page', () => {
|
||||
render(<Page />)
|
||||
expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
|
||||
})
|
||||
```
|
||||
|
||||
```jsx filename="__tests__/index.test.jsx" switcher
|
||||
import { expect, test } from 'vitest'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import Page from '../pages/index'
|
||||
|
||||
test('Page', () => {
|
||||
render(<Page />)
|
||||
expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined()
|
||||
})
|
||||
```
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
## Running your tests
|
||||
|
||||
Then, run the following command to run your tests:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm test
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm run test
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn test
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun run test
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
You may find these resources helpful:
|
||||
|
||||
- [Next.js with Vitest example](https://github.com/vercel/next.js/tree/canary/examples/with-vitest)
|
||||
- [Vitest Docs](https://vitest.dev/guide/)
|
||||
- [React Testing Library Docs](https://testing-library.com/docs/react-testing-library/intro/)
|
||||
Reference in New Issue
Block a user