문서
App Router 사용하기
애플리케이션 구축하기
테스트
Jest

Next.js와 Jest 설정하기

Jest와 React Testing Library는 단위 테스트와 스냅샷 테스트를 위해 자주 함께 사용됩니다. 이 가이드에서는 Next.js와 Jest를 설정하고 첫 번째 테스트를 작성하는 방법을 보여드리겠습니다.

알아두면 좋은 점: async 서버 컴포넌트는 React 생태계에 새로 도입되었기 때문에 Jest는 현재 이를 지원하지 않습니다. 동기식 서버 및 클라이언트 컴포넌트에 대한 단위 테스트는 여전히 실행할 수 있지만, async 컴포넌트에 대해서는 E2E 테스트를 사용하는 것을 권장합니다.

빠른 시작

Next.js with-jest 예제와 함께 create-next-app을 사용하여 빠르게 시작할 수 있습니다:

Terminal
npx create-next-app@latest --example with-jest with-jest-app

수동 설정

Next.js 12 릴리스 이후, Next.js에는 이제 Jest를 위한 내장 구성이 있습니다.

Jest를 설정하려면 jest와 다음 패키지들을 개발 의존성으로 설치하세요:

Terminal
npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom
# 또는
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom
# 또는
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom

다음 명령을 실행하여 기본 Jest 구성 파일을 생성하세요:

Terminal
npm init jest@latest
# 또는
yarn create jest@latest
# 또는
pnpm create jest@latest

이 과정에서 프로젝트에 Jest를 설정하기 위한 일련의 프롬프트가 표시되며, 자동으로 jest.config.ts|js 파일이 생성됩니다.

next/jest를 사용하도록 구성 파일을 업데이트하세요. 이 트랜스포머에는 Jest가 Next.js와 작동하는 데 필요한 모든 구성 옵션이 포함되어 있습니다:

jest.config.ts
import type { Config } from "jest";
import nextJest from "next/jest.js";
 
const createJestConfig = nextJest({
  // 테스트 환경에서 next.config.js와 .env 파일을 로드하기 위해 Next.js 앱의 경로를 제공하세요
  dir: "./",
});
 
// Jest에 전달할 사용자 정의 구성을 추가하세요
const config: Config = {
  coverageProvider: "v8",
  testEnvironment: "jsdom",
  // 각 테스트 실행 전에 더 많은 설정 옵션을 추가하세요
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
};
 
// next/jest가 비동기인 Next.js 구성을 로드할 수 있도록 createJestConfig를 이렇게 내보냅니다
export default createJestConfig(config);
jest.config.js
const nextJest = require("next/jest");
 
/** @type {import('jest').Config} */
const createJestConfig = nextJest({
  // 테스트 환경에서 next.config.js와 .env 파일을 로드하기 위해 Next.js 앱의 경로를 제공하세요
  dir: "./",
});
 
// Jest에 전달할 사용자 정의 구성을 추가하세요
const config = {
  coverageProvider: "v8",
  testEnvironment: "jsdom",
  // 각 테스트 실행 전에 더 많은 설정 옵션을 추가하세요
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
};
 
// next/jest가 비동기인 Next.js 구성을 로드할 수 있도록 createJestConfig를 이렇게 내보냅니다
module.exports = createJestConfig(config);

내부적으로 next/jest는 다음을 포함하여 자동으로 Jest를 구성합니다:

  • Next.js 컴파일러를 사용하여 transform 설정
  • 스타일시트(.css, .module.css, 및 해당 scss 변형), 이미지 가져오기 및 next/font의 자동 모킹
  • .env(및 모든 변형)를 process.env로 로드
  • 테스트 해결 및 변환에서 node_modules 무시
  • 테스트 해결에서 .next 무시
  • SWC 변환을 활성화하는 플래그에 대한 next.config.js 로드

알아두면 좋은 점: 환경 변수를 직접 테스트하려면 별도의 설정 스크립트나 jest.config.ts 파일에서 수동으로 로드하세요. 자세한 내용은 테스트 환경 변수를 참조하세요.

선택 사항: 절대 가져오기 및 모듈 경로 별칭 처리하기

프로젝트에서 모듈 경로 별칭을 사용하는 경우, jsconfig.json 파일의 paths 옵션과 jest.config.js 파일의 moduleNameMapper 옵션을 일치시켜 Jest가 가져오기를 해결하도록 구성해야 합니다. 예를 들어:

tsconfig.json or jsconfig.json
{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "baseUrl": "./",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}
jest.config.js
moduleNameMapper: {
  // ...
  '^@/components/(.*)$': '<rootDir>/components/$1',
}

선택 사항: Jest를 사용자 정의 매처로 확장하기

@testing-library/jest-dom은 .toBeInTheDocument()와 같은 편리한 사용자 정의 매처 세트를 포함하여 테스트 작성을 더 쉽게 만듭니다. Jest 구성 파일에 다음 옵션을 추가하여 모든 테스트에 대해 사용자 정의 매처를 가져올 수 있습니다:

jest.config.ts
setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"];
jest.config.js
setupFilesAfterEnv: ["<rootDir>/jest.setup.js"];

그런 다음 jest.setup.ts 안에 다음 가져오기를 추가하세요:

jest.setup.ts
import "@testing-library/jest-dom";
jest.setup.js
import "@testing-library/jest-dom";

알아두면 좋은 점: extend-expect는 v6.0에서 제거되었습니다, 따라서 버전 6 이전의 @testing-library/jest-dom을 사용하고 있다면 대신 @testing-library/jest-dom/extend-expect를 가져와야 합니다.

각 테스트 전에 더 많은 설정 옵션을 추가해야 하는 경우 위의 jest.setup.js 파일에 추가할 수 있습니다.

package.json에 테스트 스크립트 추가하기:

마지막으로, package.json 파일에 Jest test 스크립트를 추가하세요:

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "test:watch": "jest --watch"
  }
}

jest --watch는 파일이 변경될 때 테스트를 다시 실행합니다. 더 많은 Jest CLI 옵션에 대해서는 Jest 문서를 참조하세요.

첫 번째 테스트 만들기:

이제 프로젝트에서 테스트를 실행할 준비가 되었습니다. 프로젝트의 루트 디렉토리에 __tests__라는 폴더를 만드세요.

예를 들어, <Page /> 컴포넌트가 제목을 성공적으로 렌더링하는지 확인하는 테스트를 추가할 수 있습니다:

import Link from "next/link";
 
export default function Home() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  );
}
__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();
  });
});

선택적으로, 스냅샷 테스트를 추가하여 컴포넌트의 예기치 않은 변경 사항을 추적할 수 있습니다:

__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();
});

테스트 실행하기

그런 다음, 다음 명령을 실행하여 테스트를 실행하세요:

Terminal
npm run test
# 또는
yarn test
# 또는
pnpm test

추가 자료

추가 읽기 자료로 다음 리소스가 도움이 될 수 있습니다:

VitestPlaywright