How to set up Playwright with Next.js

Playwright는 단일 API로 Chromium(크롬 기반), Firefox, 그리고 WebKit(사파리 기반) 브라우저를 모두 자동화할 수 있게 해주는 아주 강력한 테스팅 프레임워크랍니다. 여러분은 이걸 사용해서 End-to-End (E2E) 테스트를 작성할 수 있어요. 이 가이드에서는 Next.js 프로젝트에 Playwright를 어떻게 설정하고, 대망의 첫 번째 테스트 코드를 어떻게 작성하는지 보여드릴게요.

👨‍🏫 강사의 보충 설명 & 꿀팁:
"End-to-End (E2E) 테스트"가 처음이신 분들도 계실 텐데요! E2E 테스트는 쉽게 말해서 '실제 사용자가 우리 웹사이트에 들어와서 버튼을 누르고 페이지를 이동하는 과정을 로봇(코드)이 대신 똑같이 해보면서 버그가 없는지 확인하는 것'이라고 생각하시면 됩니다. Playwright는 현재 E2E 테스팅 시장에서 Cypress와 함께 가장 핫한 도구 중 하나예요. 속도도 정말 빠르고 여러 브라우저를 동시에 테스트할 수 있어서 현업에서 아주 많이 쓰인답니다!

🚀 빠른 시작 (Quickstart)

가장 빠르게 시작하는 방법은 create-next-app을 사용할 때 with-playwright 예제(example)를 함께 사용하는 거예요. 이렇게 하면 Playwright 설정이 모두 완료된 Next.js 프로젝트가 짠! 하고 만들어집니다.

pnpm create next-app --example with-playwright with-playwright-app

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

yarn create next-app --example with-playwright with-playwright-app

bun create next-app --example with-playwright with-playwright-app

👨‍🏫 강사의 꿀팁:
새로운 프로젝트를 시작할 때는 이 방법이 최고예요. Vercel 팀이 설정해둔 모범 사례(Best Practice)가 그대로 녹아있거든요. 하지만 현업에서는 이미 만들어진 기존 프로젝트에 Playwright를 붙여야 하는 경우가 훨씬 많겠죠? 그래서 바로 다음에 나오는 '수동 설정(Manual setup)' 방법을 잘 알아두셔야 합니다!

🛠 수동 설정 (Manual setup)

기존 프로젝트에 Playwright를 설치하려면 터미널에서 다음 명령어를 실행해 주세요.

pnpm create playwright

npm init playwright

yarn create playwright

bun create playwright

이 명령어를 치면 터미널에서 여러분의 프로젝트에 Playwright를 설정하고 구성하기 위한 몇 가지 질문(prompt)들이 연달아 나올 거예요. 이 과정을 거치면 프로젝트 폴더에 playwright.config.ts 파일이 추가된답니다. 단계별로 더 자세한 가이드가 필요하다면 Playwright 설치 가이드를 참고해 주세요.

👨‍🏫 강사의 보충 설명:
터미널에서 물어보는 질문들은 보통 이런 것들이에요.
1. 테스트 코드를 TypeScript로 쓸 건지 JavaScript로 쓸 건지 (우리는 당연히 TS!)
2. 테스트 파일들을 모아둘 폴더 이름은 뭘로 할 건지 (보통 tests나 e2e로 많이 합니다)
3. GitHub Actions 워크플로우를 추가할 건지 (CI/CD 파이프라인 구축할 때 아주 유용해요)
여기서 생성되는 playwright.config.ts 파일이 Playwright의 심장 같은 곳입니다. 브라우저 설정, 타임아웃, 테스트 병렬 실행 여부 등을 여기서 모두 관리하게 돼요.

✍️ 첫 번째 Playwright E2E 테스트 만들기

테스트를 해보려면 먼저 테스트할 화면이 있어야겠죠? Next.js 페이지 두 개를 새로 만들어 볼게요.

//filename="app/page.tsx"
import Link from 'next/link'

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

//filename="app/about/page.tsx"
import Link from 'next/link'

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

페이지를 만들었다면, 이제 네비게이션(페이지 이동)이 제대로 작동하는지 검증하기 위한 테스트 코드를 추가해 봅시다.

//filename="tests/example.spec.ts"
import { test, expect } from '@playwright/test'

test('should navigate to the about page', async ({ page }) => {
  // 인덱스(메인) 페이지에서 시작합니다 (baseURL은 playwright.config.ts의 webServer를 통해 설정되어 있습니다)
  await page.goto('http://localhost:3000/')
  // 'About'이라는 텍스트를 가진 요소를 찾아서 클릭합니다
  await page.click('text=About')
  // 새로운 URL은 "/about"이어야 합니다 (여기서 baseURL이 사용됩니다)
  await expect(page).toHaveURL('http://localhost:3000/about')
  // 새로운 페이지에는 "About"이라는 텍스트가 포함된 h1 태그가 있어야 합니다
  await expect(page.locator('h1')).toContainText('About')
})

알아두면 좋은 점 (Good to know): playwright.config.ts 설정 파일에 "baseURL": "http://localhost:3000"을 추가해 두면, page.goto("http://localhost:3000/") 처럼 긴 주소를 다 쓸 필요 없이 간단하게 page.goto("/") 라고만 써도 된답니다!

👨‍🏫 강사의 꿀팁:
여러분, 이 baseURL 설정은 선택이 아니라 필수라고 생각하세요! 나중에 로컬에서 테스트하다가 개발/운영 서버로 테스트 환경을 바꿀 때, 코드 안의 http://localhost:3000을 일일이 찾아 바꾸는 건 끔찍한 일이거든요. 환경 변수를 통해 baseURL만 갈아끼울 수 있게 세팅하는 것이 실무의 기본입니다.
그리고 위 코드에서 page.click('text=About') 처럼 텍스트로 요소를 찾는 방식도 좋지만, 텍스트가 다국어 처리되어 바뀌거나 디자인이 변경될 때 테스트가 깨질 수 있어요. 그래서 실무에서는 data-testid="about-link" 같은 테스트 전용 속성을 부여해서 page.getByTestId('about-link')로 찾는 방식을 더 권장합니다!

🏃‍♂️ Playwright 테스트 실행하기

Playwright는 Chromium, Firefox, Webkit 이렇게 세 가지 브라우저를 사용해서 사용자가 애플리케이션을 탐색하는 과정을 시뮬레이션(모의)합니다. 그러려면 당연히 여러분의 Next.js 서버가 켜져 있어야겠죠? 여기서 저희는 실제 애플리케이션이 어떻게 동작할지 가장 유사한 환경을 만들기 위해, 개발 모드가 아닌 프로덕션(배포용) 코드로 테스트를 실행하는 것을 권장합니다.

터미널에서 npm run build를 실행해서 빌드한 다음 npm run start로 서버를 켜주세요. 그리고 다른 터미널 창을 하나 더 열어서 npx playwright test를 입력하면 Playwright 테스트가 쫙 실행될 겁니다!

알아두면 좋은 점 (Good to know): 창을 두 개 띄우는 게 귀찮으신가요? 그렇다면 webServer 기능을 사용해 보세요! Playwright가 알아서 개발 서버를 시작해주고 서버가 완전히 준비될 때까지 기다렸다가 테스트를 시작하게 만들 수 있답니다.

👨‍🏫 강사의 보충 설명:
"왜 굳이 빌드해서 테스트해야 하죠? 그냥 npm run dev 켜놓고 하면 안 되나요?" 라고 물어보시는 분들이 꼭 계십니다. 아주 좋은 질문이에요!
개발 환경(dev)과 실제 배포 환경(build & start)은 번들링 과정이나 최적화 측면에서 차이가 있어요. CSS나 자바스크립트가 압축(Minify)되면서 생기는 예상치 못한 에러, 서버 사이드 렌더링(SSR)과 클라이언트 하이드레이션(Hydration) 타이밍 문제 등은 프로덕션 빌드에서만 발견되는 경우가 종종 있거든요. 그래서 E2E 테스트는 최대한 '실제 운영 환경'과 똑같이 맞추고 돌려보는 게 가장 안전합니다.

🤖 지속적 통합(Continuous Integration, CI) 환경에서 Playwright 실행하기

Playwright는 기본적으로 헤드리스 모드(headless mode)로 테스트를 실행합니다. 모든 Playwright 의존성 패키지들을 설치하려면 npx playwright install-deps 명령어를 실행해 주세요.

👨‍🏫 강사의 보충 설명:
'헤드리스 모드'라는 말이 좀 무섭게 들리죠? 😅 이건 브라우저의 '머리(화면, GUI)'가 없다는 뜻이에요. 우리가 평소에 쓰는 것처럼 브라우저 창이 눈에 보이게 뜨는 게 아니라, 컴퓨터 메모리 상에서 백그라운드로 보이지 않게 브라우저를 띄워서 테스트하는 방식입니다. GitHub Actions나 AWS 같은 CI/CD 서버 컴퓨터에는 모니터가 없잖아요? 그래서 이런 CI 환경에서는 화면을 그릴 필요가 없는 헤드리스 모드로 테스트를 돌리는 게 훨씬 빠르고 자원도 적게 먹는답니다. 반대로, 여러분이 코드를 짤 때 눈으로 직접 클릭되는 걸 보고 싶다면 --headed 옵션을 붙여서 실행하면 브라우저 창이 뜨는 걸 볼 수 있어요!

Playwright와 CI 연동에 대해 더 깊이 공부하고 싶다면 아래 리소스들을 확인해 보세요:

• Next.js와 Playwright 예제 코드 (Next.js with Playwright example)
• CI 제공업체에서 Playwright 실행하기 (Playwright on your CI provider)
• Playwright 공식 디스코드 커뮤니티 (Playwright Discord)

---

모든 문서의 의미론적 개요(semantic overview)를 보시려면 https://nextjs.org/docs/sitemap.md 를 확인해 주세요.

사용 가능한 모든 문서의 인덱스(목록)를 보시려면 https://nextjs.org/docs/llms.txt 를 확인해 주세요.