본문으로 건너뛰기

모범 사례

이 안내서는 모범 사례를 따르는 테스트, 보다 탄력적인 테스트를 작성하는 데 도움이 됩니다.

탐지기 사용하기​

종단 간 테스트를 작성하려면 먼저 웹 페이지에서 요소를 찾아야 합니다. 플레이라이트의 내장 탐지기를 사용하여 이를 수행할 수 있습니다. 탐지기는 자동 대기와 재시도 기능을 제공합니다. 자동 대기는 플레이라이트가 클릭을 수행하기 전에 요소가 보이고 활성화 상태인지 확인하는 것처럼, 요소에 대한 다양한 동작 가능성 검사를 수행하는 것을 의미합니다. 테스트를 탄력적으로 만들려면 사용자 대면 속성과 명시적 계약의 우선 순위를 지정하는 것이 좋습니다.

js
👍 page.getByRole('button', { name: 'submit' })
js
👍 page.getByRole('button', { name: 'submit' })

연쇄와 필터링 사용하기​

탐지기는 연쇄되어 페이지의 특정 부분으로 검색 범위를 좁힐 수 있습니다.

js
const product = page.getByRole('listitem').filter({ hasText: 'Product 2' });
js
const product = page.getByRole('listitem').filter({ hasText: 'Product 2' });

텍스트나 다른 탐지기를 사용하여 탐지기를 필터링할 수도 있습니다.

js
await page
  .getByRole('listitem')
  .filter({ hasText: 'Product 2' })
  .getByRole('button', { name: 'Add to cart' })
  .click();
js
await page
  .getByRole('listitem')
  .filter({ hasText: 'Product 2' })
  .getByRole('button', { name: 'Add to cart' })
  .click();

XPath 또는 CSS 선택기가 아닌 사용자에게 표시되는 속성을 사용하기​

DOM은 쉽게 변경될 수 있으므로 테스트가 DOM 구조에 의존하면 테스트가 실패할 수 있습니다.

예를 들어 CSS 클래스로 버튼을 선택한다고 가정해 보겠습니다. 디자이너가 무언가를 변경하면 클래스가 변경되어 테스트가 깨질 수 있습니다.

js
👎 page.locator('button.buttonIcon.episode-actions-later')
js
👎 page.locator('button.buttonIcon.episode-actions-later')

DOM의 변화에 탄력적인 탐지기를 사용하는 것이 좋습니다.

js
👍 page.getByRole('button', { name: 'submit' })
js
👍 page.getByRole('button', { name: 'submit' })

탐지기 생성하기​

플레이라이트에는 테스트를 생성하고 탐지기를 선택할 수 있는 테스트 생성기가 있습니다. 페이지를 살펴보고 역할, 텍스트, 테스트 ID 탐지기의 우선 순위를 지정하여 최상의 탐지기를 찾습니다. 생성기가 탐지기와 일치하는 요소를 여러 개 찾으면, 탐지기를 개선하여 탄력성을 높이고 대상 요소를 고유하게 식별합니다. 탐지기로 인한 테스트 실패를 걱정할 필요가 없습니다.

코드젠을 사용하여 탐지기 생성하기​

탐지기를 선택하려면 codegen 명령 뒤에 탐지기를 선택할 URL을 붙이세요.

bash
npx playwright codegen playwright.dev
bash
npx playwright codegen playwright.dev

이제 새 브라우저 창과 플레이라이트 검사기가 열립니다. 탐지기를 선택하려면 먼저 Record 버튼을 클릭하여 기록을 중지합니다. 기본적으로 codegen 명령을 실행하면 새 기록이 시작됩니다. 기록을 중지하면 Pick Locator 버튼의 클릭이 가능해집니다.

브라우저 창에서 페이지의 요소 위에 마우스를 놓으면 커서 아래에 강조 표시된 탐지기를 볼 수 있습니다. 요소를 클릭하면 탐지기가 플레이라이트 검사기에 추가됩니다. 탐지기를 복사하여 테스트 파일에 붙여넣거나, 플레이라이트 검사기에서 탐지기를 편집(예: 텍스트를 수정)하고 브라우저 창에서 결과를 확인하며 탐지기 탐색을 계속할 수 있습니다.

VS 코드 확장을 사용하여 탐지기 생성하기​

VS 코드 확장을 사용하여 탐지기를 생성하고 테스트를 기록할 수 있습니다. VS 코드 확장은 또한 테스트 작성, 실행, 디버깅에서 훌륭한 개발자 경험을 제공합니다.

웹 우선 단언 사용하기​

단언은 예상과 실제 결과의 일치 여부를 확인하는 방법입니다. 웹 우선 단언을 사용하여 플레이라이트는 예상 조건이 충족될 때까지 기다립니다. 예를 들어 경고 메시지를 테스트할 때, 테스트는 메시지를 표시하는 버튼을 클릭하고 경고 메시지가 있는지 확인합니다. 경고 메시지가 나타나는 데 0.5초가 걸리면 toBeVisible()과 같은 단언이 기다렸다가 필요하다면 다시 시도합니다.

js
👍 await expect(page.getByText('welcome')).toBeVisible();
👎 expect(await page.getByText('welcome').isVisible()).toBe(true);
js
👍 await expect(page.getByText('welcome')).toBeVisible();
👎 expect(await page.getByText('welcome').isVisible()).toBe(true);

수동 단언을 사용하지 마세요​

expect를 기다리지 않는 수동 주장을 사용하지 마세요. 아래 코드에서 await는 expect 앞이 아니라 expect 내부에 있습니다. isVisible()과 같은 단언을 사용할 때 테스트는 1초도 기다리지 않습니다. 테스트는 탐지기가 있는지 확인하고 즉시 반환합니다.

js
👎 expect(await page.getByText('welcome').isVisible()).toBe(true);
js
👎 expect(await page.getByText('welcome').isVisible()).toBe(true);

대신 toBeVisible()과 같은 웹 우선 단언을 사용하세요.

js
👍 await expect(page.getByText('welcome')).toBeVisible();
js
👍 await expect(page.getByText('welcome')).toBeVisible();

디버깅 설정하기​

로컬 디버깅​

로컬 디버깅에서는 VS 코드 확장을 설치하여 테스트를 VS 코드에서 실시간 디버그하는 것이 좋습니다. 실행하려는 테스트 옆의 줄을 마우스 오른쪽 버튼으로 클릭하여 브라우저 창을 열고, 중단점이 설정된 위치에서 일시 중지하여 디버그 모드에서 테스트를 실행할 수 있습니다.

VS 코드에서 테스트의 탐지기를 클릭하거나 편집하여 테스트를 실시간 디버그할 수 있습니다. 브라우저 창에서 해당 탐지기를 강조 표시하고 페이지에서 찾은 다른 일치하는 탐지기를 표시합니다.

--debug 플래그로 테스트를 실행하여 플레이라이트 검사기로 테스트를 디버그할 수 있습니다.

bash
npx playwright test --debug
bash
npx playwright test --debug

그런 다음 테스트를 단계별로 진행하며 동작 가능성 로그를 보고, 탐지기를 실시간으로 편집하고, 브라우저 창에서 탐지기가 강조 표시되는 것을 볼 수 있습니다. 어떤 탐지기가 일치하는지, 얼마나 많은 탐지기가 일치하는지 확인할 수 있습니다.

특정 테스트를 디버그하려면 테스트 파일의 이름과 테스트의 줄 번호를 추가하고 --debug 플래그를 추가합니다.

bash
npx playwright test example.spec.ts:9 --debug
bash
npx playwright test example.spec.ts:9 --debug

CI에서의 디버깅​

CI에서 테스트가 실패하면 비디오와 스크린숏 대신 플레이라이트 추적 뷰어를 사용하세요. 추적 뷰어는 쉽게 공유할 수 있는 로컬 PWA(Progressive Web App)로 테스트의 전체 추적을 제공합니다. 추적 뷰어를 사용하면 타임라인을 보고, 개발 도구를 사용하여 각 동작에 대한 DOM 스냅숏을 검사하고, 네트워크 요청 등을 볼 수 있습니다.

추적은 플레이라이트 설정 파일에서 설정되며 실패한 테스트의 첫 번째 재시도 시 CI에서 실행되도록 설정됩니다. 자원을 많이 사용하므로 추적이 모든 테스트에서 실행되도록 on으로 설정하는 것은 권장하지 않습니다. 그러나 개발할 때 --trace 플래그로 로컬에서 추적을 실행할 수 있습니다.

bash
npx playwright test --trace on
bash
npx playwright test --trace on

이 명령을 실행하면 각 테스트에 대한 추적이 기록되고 HTML 보고서에서 직접 볼 수 있습니다.

bash
npx playwright show-report
bash
npx playwright show-report

추적은 테스트 옆에 있는 아이콘을 클릭하거나, 각 테스트 보고서를 열고 하단의 추적 부분까지 스크롤하여 열 수 있습니다.

플레이라이트의 도구 사용하기​

플레이라이트는 테스트를 작성하는 데 도움이 되는 다양한 도구를 제공합니다.

  • VS 코드 확장 - 테스트 작성, 실행, 디버깅에서 훌륭한 개발자 경험을 제공합니다.
  • 테스트 생성기 - 테스트를 생성하고 탐지기를 선택할 수 있습니다.
  • 추적 뷰어 - 쉽게 공유할 수 있는 로컬 PWA로 테스트의 전체 추적을 제공합니다. 추적 뷰어를 사용하면 타임라인을 보고, 각 동작에 대한 DOM 스냅숏을 검사하고, 네트워크 요청 등을 볼 수 있습니다.
  • 타입스크립트 - 기본적으로 사용 가능하며 더 나은 IDE 통합을 제공합니다. IDE는 할 수 있는 모든 것을 보여주며 뭔가 잘못됐다면 강조 표시할 것입니다. 타입스크립트 경험이 필요하지 않으며 코드가 타입스크립트에 있을 필요가 없다면 테스트를 .js 확장자로 생성하면 됩니다.

모든 브라우저에서 테스트하기​

플레이라이트를 사용하면 플랫폼에 관계없이 모든 브라우저에서 사이트를 쉽게 테스트할 수 있습니다. 모든 브라우저에서 테스트하면 앱이 모든 사용자에게 작동하는지 확인할 수 있습니다. 설정 파일에서 이름과 사용할 브라우저나 장치를 추가하여 프로젝트를 설정할 수 있습니다.

playwright.config.ts
tsx
import { type PlaywrightTestConfig, devices } from '@playwright/test';
const config: PlaywrightTestConfig = {
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
};
export default config;
playwright.config.ts
tsx
import { type PlaywrightTestConfig, devices } from '@playwright/test';
const config: PlaywrightTestConfig = {
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
};
export default config;

플레이라이트 의존성을 최신으로 유지하기​

플레이라이트 버전을 최신 상태로 유지하면, 최신 브라우저 버전에서 앱을 테스트하고 최신 브라우저 버전이 공개되기 전에 오류를 포착할 수 있습니다.

bash
npm install -D @playwright/test@latest
bash
npm install -D @playwright/test@latest

최신 버전과 변경 사항을 보려면 배포 노트를 확인하세요.

다음 명령을 실행하여 현재 플레이라이트 버전을 확인할 수 있습니다.

bash
npx playwright --version
bash
npx playwright --version

CI에서 테스트 실행하기​

CI/CD를 설정하고 테스트를 자주 실행하세요. 테스트를 자주 실행할수록 더 좋습니다. 이상적으로는 각 커밋과 풀 요청마다 테스트를 실행해야 합니다.

플레이라이트는 깃허브 액션 작업 흐름과 함께 제공되므로 별도의 설정 없이 CI에서 테스트를 실행할 수 있습니다. 플레이라이트를 원하는 CI 환경에 설정할 수 있습니다.

CI에서 테스트를 실행할 때 저렴한 리눅스를 사용할 수 있습니다. 개발자는 로컬에서 실행할 때 어떤 환경이든 사용할 수 있지만 CI에서는 리눅스를 사용합니다.

병렬 처리와 샤딩 사용하기​

플레이라이트는 기본적으로 병렬로 테스트를 실행합니다. 단일 파일의 테스트는 동일한 작업자 프로세스에서 순서대로 실행됩니다. 단일 파일에 많은 독립 테스트가 있다면 병렬로 실행하는 것이 좋습니다.

js
import { test } from '@playwright/test';
test.describe.configure({ mode: 'parallel' });
test('runs in parallel 1', async ({ page }) => {
  /* ... */
});
test('runs in parallel 2', async ({ page }) => {
  /* ... */
});
js
import { test } from '@playwright/test';
test.describe.configure({ mode: 'parallel' });
test('runs in parallel 1', async ({ page }) => {
  /* ... */
});
test('runs in parallel 2', async ({ page }) => {
  /* ... */
});

플레이라이트는 테스트 스위트를 샤딩하여 여러 시스템에서 실행할 수 있습니다.

bash
npx playwright test --shard=1/3
bash
npx playwright test --shard=1/3