Cypress는 End-to-End (E2E) 및 컴포넌트 테스팅에 사용되는 테스트 러너입니다.

NOTE. Cypress 사용 시 주의할 점
Cypress 13.6.3 미만의 버전에서는 TypeScript 버전5와 moduleResolution:"bundler"를 지원하지 않습니다. 해당 설정을 사용하려면 Cypress 13.6.3 이상의 버전을 사용하는 것이 좋습니다.

14.5.1 Cypress 설치하기

빠르게 시작하기

아래 명령어와 같이 create-next-app을 with-cypress 예제와 함께 실행하여 Cypress가 설치된 형태의 Next.js 애플리케이션을 곧바로 생성할 수 있습니다.

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

수동 설치

수동으로 Cypress를 설치하려면 아래와 같이 cypress 패키지를 개발 종속성(devDependencies)으로 설치하면 됩니다.

npm install -D cypress
# or
yarn add -D cypress
# or
pnpm install -D cypress

패키지 설치 이후 package.json 파일의 scripts에 아래와 같이 cypress:open 스크립트를 추가합니다.

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

그런 다음 해당 스크립트를 실행하여 Cypress 테스트 도구 모음을 엽니다.

npm run cypress:open

그러면 E2E Testing과 Component Testing을 설정하도록 선택할 수 있습니다. 이러한 옵션 중 하나를 선택하면 프로젝트에 cypress.config.js 파일과 cypress 폴더가 자동으로 생성됩니다.

14.5.2 Cypress E2E 테스트

먼저 cypress.config.js 파일이 아래와 같이 설정되어 있는지 확인합니다.

// cypress.config.ts

import { defineConfig } from 'cypress';

export default defineConfig({
    e2e: {
        setupNodeEvents(on, config) {},
    },
});

그런 다음 아래와 같이 두 개의 페이지 컴포넌트를 코드를 작성합니다.

// 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>
    );
}

이후 각 페이지 간에 경로 이동이 제대로 작동하는지 확인하기 위한 테스트 코드를 아래와 같이 작성하면 됩니다.

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');
    });
});

Cypress는 사용자가 애플리케이션을 탐색하는 것을 시뮬레이션하며, 이를 위해 Next.js 서버가 실행 중이어야 합니다. 개발모드에서도 시뮬레이션은 가능하지만 애플리케이션이 실제로 동작하는 방식을 더 정확하게 테스트하기 위해서는 Production 코드에 대해 테스트하는 것이 좋습니다.

Production 코드에 대해 테스트 하기 위해서는 npm run build와 npm run start를 실행하여 Next.js 애플리케이션을 빌드하고 시작합니다. 그런 다음 다른 터미널 창에서 npm run cypress:open를 실행하여 Cypress를 시작하고 E2E 테스트를 실행하면 됩니다.

NOTE. 알아두면 좋은 점
cypress.config.js 설정 파일에 baseUrl: 'http://localhost:3000'을 추가함으로써 cy.visit("http://localhost:3000/")대신 cy.visit("/")를 사용할 수 있습니다.

14.5.3 Cypress Component 테스트

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

컴포넌트 테스트를 하기 위해서는 Cypress 앱에서 Component Testing을 선택한 다음, 프론트엔드 프레임워크로 Next.js를 선택하면 됩니다. 그러면 프로젝트 폴더에 cypress/component 폴더가 생성되고, cypress.config.js 파일에 컴포넌트 테스팅 관련 설정이 추가됩니다.

// cypress.config.ts

import { defineConfig } from 'cypress';

export default 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', () => {
        // Page 컴포넌트 마운트
        cy.mount(<Page />);
        // 새로운 페이지가 'Home'이라는 텍스트를 가진 h1 태그를 포함하는지 확인
        cy.get('h1').contains('Home');
        // '/about'이라는 href 속성을 가진 링크가 화면에 존재하는지 확인
        cy.get('a[href="/about"]').should('be.visible');
    });
});

이후 터미널에서 npm run cypress:open 명령을 실행하여 Cypress를 시작하고 컴포넌트 테스트를 실행하면 됩니다.

NOTE. 알아두면 좋은 점

• Cypress는 현재 async Server Components에 대한 컴포넌트 테스트를 지원하지 않습니다. 해당 컴포넌트를 테스트 하고 싶을 경우 E2E 테스트를 사용하는 것을 권장합니다.
• 컴포넌트 테스트는 Next.js 서버가 필요하지 않기 때문에 <Image />와 같이 서버에 의존하는 기능들이 기본적으로 작동하지 않을 수 있습니다.