테스트: Cypress | Next.js

Source URL: https://nextjs.org/docs/app/guides/testing/cypress

Copy page

Next.js에서 Cypress 설정 방법

Last updated February 20, 2026

Cypress는 엔드 투 엔드(E2E) 및 컴포넌트 테스트를 위한 테스트 러너입니다. 이 페이지에서는 Next.js와 함께 Cypress를 설정하고 첫 번째 테스트를 작성하는 방법을 설명합니다.

경고:

Cypress 13.6.3 미만 버전은 moduleResolution:"bundler"가 있는 TypeScript 5를 지원하지 않습니다. 하지만 이 문제는 Cypress 13.6.3 이상 버전에서 해결되었습니다. cypress v13.6.3

빠른 시작

create-next-app과 with-cypress 예제를 사용해 빠르게 시작할 수 있습니다.

pnpmnpmyarnbun

Terminal

    pnpm create next-app --example with-cypress with-cypress-app

수동 설정

Cypress를 수동으로 설정하려면 cypress를 devDependencies로 설치합니다:

pnpmnpmyarnbun

Terminal

    pnpm add -D cypress

package.json의 scripts 필드에 Cypress open 명령을 추가합니다:

package.json

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

처음으로 Cypress를 실행하여 Cypress 테스트 스위트를 엽니다:

pnpmnpmyarnbun

Terminal

    pnpm cypress:open

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

첫 번째 Cypress E2E 테스트 만들기

cypress.config 파일에 다음 구성이 있는지 확인합니다:

cypress.config.ts

JavaScriptTypeScript

    import { defineConfig } from 'cypress'

    export default 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', () => {
        // 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')
      })
    })

E2E 테스트 실행

Cypress는 사용자가 애플리케이션을 탐색하는 동작을 시뮬레이션하므로 Next.js 서버가 실행 중이어야 합니다. 실제 애플리케이션 동작과 최대한 유사하게 만들기 위해 프로덕션 코드에 대해 테스트를 실행하는 것을 권장합니다.

Next.js 애플리케이션을 빌드하려면 npm run build && npm run start를 실행하고, 다른 터미널 창에서 npm run cypress:open을 실행하여 Cypress를 시작하고 E2E 테스트 스위트를 실행합니다.

알아두면 좋아요:

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

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

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

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

Cypress 앱에서 Component Testing을 선택한 후 프런트엔드 프레임워크로 Next.js를 선택합니다. 그러면 프로젝트에 cypress/component 폴더가 생성되고, Component Testing을 활성화하도록 cypress.config.js 파일이 업데이트됩니다.

cypress.config 파일에 다음 구성이 있는지 확인합니다:

cypress.config.ts

JavaScriptTypeScript

    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', () => {
        // 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')
      })
    })

알아두면 좋아요 :

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

컴포넌트 테스트는 Next.js 서버가 필요하지 않으므로 서버 사용을 전제로 하는 <Image />와 같은 기능은 즉시 작동하지 않을 수 있습니다.

컴포넌트 테스트 실행

터미널에서 npm run cypress:open을 실행하여 Cypress를 시작하고 Component Testing 스위트를 실행합니다.

지속적 통합(CI)

대화형 테스트 외에도 CI 환경에 더 적합한 cypress run 명령을 사용하여 헤드리스 모드로 Cypress를 실행할 수 있습니다:

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와 지속적 통합에 대해 더 알아보려면 다음 자료를 참고하세요:

Was this helpful?

supported.

Send