Next.js와 Cypress 설정하기

Cypress는 End-to-End (E2E) 및 컴포넌트 테스팅에 사용되는 테스트 러너입니다. 이 페이지에서는 Next.js와 Cypress를 설정하고 첫 번째 테스트를 작성하는 방법을 보여드리겠습니다.

경고:

컴포넌트 테스팅의 경우, Cypress는 현재 Next.js 버전 14와 async 서버 컴포넌트를 지원하지 않습니다. 이 문제들은 추적 중입니다. 현재로서는 컴포넌트 테스팅은 Next.js 버전 13에서 작동하며, async 서버 컴포넌트에 대해서는 E2E 테스팅을 권장합니다.

Cypress 13.6.3 이전 버전은 moduleResolution:"bundler"와 함께 TypeScript 버전 5를 지원하지 않습니다. 그러나 이 문제는 Cypress 버전 13.6.3 이상에서 해결되었습니다. cypress v13.6.3

빠른 시작

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

Terminal

npx create-next-app@latest --example with-cypress with-cypress-app

수동 설정

Cypress를 수동으로 설정하려면 cypress를 개발 의존성으로 설치하세요:

Terminal

npm install -D cypress
# 또는
yarn add -D cypress
# 또는
pnpm install -D cypress

Cypress open 명령을 package.json 스크립트 필드에 추가하세요:

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "cypress:open": "cypress open"
  }
}

Cypress 테스팅 스위트를 열기 위해 처음으로 Cypress를 실행하세요:

Terminal

npm run cypress:open

E2E 테스팅 및/또는 컴포넌트 테스팅을 구성할 수 있습니다. 이 옵션들 중 하나를 선택하면 자동으로 cypress.config.js 파일과 cypress 폴더가 프로젝트에 생성됩니다.

첫 번째 Cypress E2E 테스트 만들기

cypress.config.js 파일에 다음 구성이 있는지 확인하세요:

cypress.config.ts

import { defineConfig } from "cypress";
 
export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
});

cypress.config.js

const { defineConfig } = require("cypress");
 
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {},
  },
});

그런 다음, 두 개의 새로운 Next.js 파일을 만드세요:

app/page.js

import Link from "next/link";
 
export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  );
}

app/about/page.js

import Link from "next/link";
 
export default function Page() {
  return (
    <div>
      <h1>About</h1>
      <Link href="/">Home</Link>
    </div>
  );
}

네비게이션이 올바르게 작동하는지 확인하는 테스트를 추가하세요:

cypress/e2e/app.cy.js

describe("Navigation", () => {
  it("should navigate to the about page", () => {
    // 인덱스 페이지에서 시작
    cy.visit("http://localhost:3000/");
 
    // "about"을 포함하는 href 속성이 있는 링크를 찾아 클릭
    cy.get('a[href*="about"]').click();
 
    // 새 url에 "/about"이 포함되어야 함
    cy.url().should("include", "/about");
 
    // 새 페이지에는 "About"이라는 텍스트가 있는 h1이 포함되어야 함
    cy.get("h1").contains("About");
  });
});

E2E 테스트 실행하기

Cypress는 사용자가 애플리케이션을 탐색하는 것을 시뮬레이션합니다. 이를 위해서는 Next.js 서버가 실행 중이어야 합니다. 애플리케이션의 동작을 더 정확히 반영하기 위해 프로덕션 코드에 대해 테스트를 실행하는 것을 권장합니다.

npm run build && npm run start를 실행하여 Next.js 애플리케이션을 빌드한 다음, 다른 터미널 창에서 npm run cypress:open을 실행하여 Cypress를 시작하고 E2E 테스팅 스위트(Testing Suite)를 실행하세요.

알아두면 좋은 점:

cypress.config.js 구성 파일에 baseUrl: 'http://localhost:3000'을 추가하면 cy.visit("http://localhost:3000/") 대신 cy.visit("/")를 사용할 수 있습니다.

또는 start-server-and-test 패키지를 설치하여 Cypress와 함께 Next.js 프로덕션 서버를 실행할 수 있습니다. 설치 후, package.json 스크립트 필드에 "test": "start-server-and-test start http://localhost:3000 cypress"를 추가하세요. 새로운 변경 사항 후에는 애플리케이션을 다시 빌드해야 함을 잊지 마세요.

첫 번째 Cypress 컴포넌트 테스트 만들기

컴포넌트 테스트는 전체 애플리케이션을 번들링하거나 서버를 시작하지 않고도 특정 컴포넌트를 빌드하고 마운트합니다.

Cypress 앱에서 컴포넌트 테스팅을 선택한 다음, 프론트엔드 프레임워크로 Next.js를 선택하세요. 프로젝트에 cypress/component 폴더가 생성되고, 컴포넌트 테스팅을 활성화하기 위해 cypress.config.js 파일이 업데이트됩니다.

cypress.config.js 파일에 다음 구성이 있는지 확인하세요:

cypress.config.ts

import { defineConfig } from "cypress";
 
export default defineConfig({
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});

cypress.config.js

const { defineConfig } = require("cypress");
 
module.exports = defineConfig({
  component: {
    devServer: {
      framework: "next",
      bundler: "webpack",
    },
  },
});

이전 섹션의 같은 컴포넌트를 가정하고, 컴포넌트가 예상된 출력을 렌더링하는지 확인하는 테스트를 추가하세요:

cypress/component/about.cy.tsx

import Page from "../../app/page";
 
describe("<Page />", () => {
  it("should render and display expected content", () => {
    // Home 페이지에 대한 React 컴포넌트를 마운트
    cy.mount(<Page />);
 
    // 새 페이지에는 "Home"이라는 텍스트가 있는 h1이 포함되어야 함
    cy.get("h1").contains("Home");
 
    // 예상된 URL을 가진 링크가 존재하는지 확인
    // 링크를 따라가는 것은 E2E 테스트에 더 적합함
    cy.get('a[href="/about"]').should("be.visible");
  });
});

알아두면 좋은 점:

Cypress는 현재 async 서버 컴포넌트에 대한 컴포넌트 테스팅을 지원하지 않습니다. E2E 테스팅을 사용하는 것을 권장합니다.

컴포넌트 테스트는 Next.js 서버를 필요로 하지 않기 때문에, 서버가 사용 가능해야 하는 <Image /> 같은 기능은 바로 작동하지 않을 수 있습니다.

컴포넌트 테스트 실행하기

터미널에서 npm run cypress:open을 실행하여 Cypress를 시작하고 컴포넌트 테스팅 스위트를 실행하세요.

지속적 통합 (CI)

대화형 테스팅 외에도 cypress run 명령을 사용하여 Cypress를 헤드리스(화면 없이)로 실행할 수 있습니다. 이는 CI 환경에 더 적합합니다:

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"
  }
}

다음 리소스에서 Cypress와 지속적 통합에 대해 더 자세히 알아볼 수 있습니다:

Playwright 인증