Playwright 사용법 — 설치부터 첫 테스트 실행까지

Playwright 사용법을 처음부터 따라가면 설치에서 첫 테스트 실행까지 대략 10분이 걸립니다. 명령 하나로 설치되고, 예제 테스트가 함께 만들어지고, 명령 하나로 실행됩니다. 이 글은 그 10분을 순서대로 정리하고, 여기까지 하고 나면 무엇이 남는지 까지 짚습니다.

Playwright 사용법 — 무엇을 준비해야 하나

Node.js가 설치되어 있으면 됩니다. 그 외에 미리 준비할 것은 없습니다. 브라우저도 설치 과정에서 함께 받습니다.

테스트할 웹 화면은 아직 없어도 됩니다. 설치하면 예제 테스트가 함께 만들어지고, 그 예제는 Playwright 공식 사이트를 열어 확인하도록 되어 있어서 그대로 실행해 볼 수 있습니다.

Playwright 사용법은 설치·설정·실행·결과 확인 4단계입니다

Playwright 설치

터미널에서 프로젝트 폴더로 이동한 뒤 다음 명령을 실행합니다.

npm init playwright@latest

yarn이나 pnpm을 쓴다면 각각 yarn create playwright, pnpm create playwright입니다.

실행하면 공식 문서 기준으로 4가지를 물어봅니다.

브라우저를 받는 단계에서 시간이 조금 걸립니다. 용량이 있는 편이라 처음 한 번은 기다려야 합니다.

만들어지는 파일

설치가 끝나면 폴더 구조가 이렇게 됩니다.

playwright.config.ts    설정 파일
package.json
tests/
  example.spec.ts       예제 테스트

playwright.config.ts가 설정 파일입니다. 어떤 브라우저에서 돌릴지, 실패했을 때 다시 시도할지, 기록을 남길지 같은 것이 여기 적힙니다. 처음에는 손대지 않아도 됩니다.

tests/example.spec.ts가 예제 테스트입니다. 이 파일 하나만 읽어도 테스트가 어떻게 생겼는지 감이 옵니다.

Playwright 설치 후 설정 파일과 예제 테스트가 함께 만들어집니다

첫 테스트 실행

명령 하나입니다.

npx playwright test

실행하면 브라우저가 화면에 보이지 않는 상태로 열려 예제 테스트를 처리하고, 터미널에 통과 여부가 나옵니다. 기본 설정에서는 크롬·파이어폭스·사파리 계열 3종에서 각각 돌기 때문에, 테스트 2개를 적었어도 실행 결과는 6개로 나옵니다.

브라우저가 실제로 움직이는 것을 보고 싶다면 이렇게 실행합니다.

npx playwright test --headed

결과 보기

터미널 출력만으로 부족하면 결과 화면을 엽니다.

npx playwright show-report

브라우저에 결과 화면이 열리고, 테스트별로 통과·실패와 걸린 시간이 나옵니다. 실패한 테스트를 누르면 어느 단계에서 멈췄는지 볼 수 있습니다.

이어서 읽기Playwright trace viewer란? 테스트가 실패했을 때 남는 것playwright trace viewerPlaywright5분

내 화면으로 바꿔 보기

예제를 확인했으면 내가 만든 화면으로 바꿔 봅니다. 앞선 codegen 편을 함께 보면 더 빠릅니다. 테스트 하나는 대략 이렇게 생겼습니다.

import { test, expect } from '@playwright/test';

test('로그인하면 대시보드로 이동한다', async ({ page }) => {
  await page.goto('http://localhost:3000/login');

  await page.getByLabel('이메일').fill('me@example.com');
  await page.getByLabel('비밀번호').fill('비밀번호');
  await page.getByRole('button', { name: '로그인' }).click();

  await expect(page.getByRole('heading', { name: '대시보드' })).toBeVisible();
});

읽어 보면 사람이 하던 순서 그대로입니다. 화면을 열고, 입력칸을 채우고, 버튼을 누르고, 원하는 화면이 나왔는지 확인합니다.

여기서 getByLabel이나 getByRole이 요소를 지목하는 방법입니다. 이것을 어떻게 고르느냐가 나중에 테스트가 오래 가는지를 결정합니다.

이어서 읽기Playwright locators란? 화면이 바뀌어도 멈추지 않는 테스트 쓰는 법playwright locatorsPlaywright7분

직접 적기 어렵다면 조작을 그대로 코드로 받아 적게 하는 방법도 있습니다.

npx playwright codegen http://localhost:3000

이어서 읽기Playwright codegen이란? 테스트 코드를 대신 만드는 2가지 방법playwright codegenplaywright8분

여기까지 하고 나면 남는 일

설치와 첫 실행은 10분이면 끝납니다. 문제는 그다음부터입니다.

첫째, 무엇을 테스트할지 정하는 일이 남습니다. 도구는 정해 준 것만 확인합니다. 화면이 20개인 서비스에서 어느 흐름을 확인할지, 어디까지 통과로 볼지는 사람이 정해야 합니다.

둘째, 화면이 바뀔 때마다 손봐야 합니다. 기능을 고치면 테스트도 함께 고쳐야 하고, 이 일은 계속 돌아옵니다.

셋째, 언제 돌릴지 정해야 합니다. 손으로 실행하는 동안에는 잊어버리기 쉽습니다. 배포마다 자동으로 돌게 만들어야 의미가 생깁니다.

세 가지 모두 코드를 읽고 고칠 수 있는 사람이 있어야 합니다. Playwright 사용법을 익히는 것과 테스트를 계속 유지하는 것은 다른 일입니다.

Specnote는 그 뒤를 맡습니다

코드를 읽고 고칠 수 있다면 Playwright로 직접 적는 편이 정밀하고 자유롭습니다. 이 글의 순서대로 시작하시면 됩니다.

Specnote는 그 일을 할 시간이나 사람이 없는 경우를 위한 도구입니다. AI가 무엇을 만들었는지 목록으로 보여 주고, 사람이 확인해 승인하면, 승인된 범위만 실제 브라우저에서 확인합니다. 설치할 것도, 적을 코드도 없습니다.

이 글의 명령과 설치 절차는 Playwright 공식 문서 · Installation을 기준으로 2026년 8월 21일에 확인했습니다.