Playwright 구조 뜯어보기

요즘 릴리즈가 끝나면 다음 릴리즈 준비까지 잠시 생긴 틈새 시간에, 회사 서비스 자동화 프로젝트를 진행하고 있다. 회사 스터디에서는 JavaScript를 공부하고, 개인적으로는 TypeScript와 Playwright를 함께 파고들며 ‘자동화 프로세스’라는 완전 새로운 영역을 혼자서 부딪히며 구축하고 있다.

 

QA Manager로서 '테스트 자동화 구축'이라는 큰 과제를 받았지만, 실제 서비스 기반에서의 경험은 거의 전무했다. 그래서 모든 것이 새로웠고, 그래서 더 궁금했다.

 

본인 성격상 항상 '왜?'라는 질문을 끊임없이 던지기에, Playwright 구조를 봤을 때도 마찬가지였다. '이게 왜 이렇게 동작하지?', '왜 이런 문법을 사용하지?', '저 객체는 어디서 생성되는 거지?' 라는 질문들을 끊임없이 던지며 파고들었다. 파고들다 보니 자연스럽게 타입스크립트의 문법도 알게 되었고, 올해 초 부트캠프에서 배웠던 Pytest + Selenium과의 차이점도 자연스럽게 이해할 수 있었다. 이에 대한 부분은 다음 포스팅을 통해 자세히 다룰 예정이다.

 

그래서 오늘 글은 Playwright의 구조를 하나씩 뜯어보며 ‘왜 이런 구조를 쓰는지’ 이해한 과정을 정리해보려 한다. 누군가는 "이게 왜 궁금하지?"라고 생각할 수도 있지만, 나에게는 정말 궁금했고 파고드는 과정 자체가 큰 도움이 되었다. 표면적인 사용법만 아는 것과, 내부 구조까지 이해하고 사용하는 것의 차이는 실제로 엄청 컸기 때문이다.

 

🔍 시작: 자동 생성된 예제 코드

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

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Click the get started link.
  await page.getByRole('link', { name: 'Get started' }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Playwright 프로젝트를 생성하면 자동으로 제공되는 tests/example.spec.ts 파일은 위와 같다.

처음 이 코드를 봤을 때 나는 다음과 같은 질문들이 떠올랐다.

• @playwright/test는 도대체 뭐지?
• test() 함수는 어떤 구조를 갖는 거지?
• page는 뭐고, 왜 함수 인자에서 { page }처럼 구조 분해 할당을 쓰는 거지?

이 질문들을 하나씩 따라가 보기로 했다.

 

📌 @playwright/test

Playwright는 크게 2가지 레이어로 이루어져 있다.

1. Core API
   -> Browser / Page / Locator 같은 '자동화 엔진'
2. Test Runner (@playwright/test)
   -> test(), expect(), fixtures, 병렬 실행 등 테스트 러너 기능

우리가 보통 사용하는 '@playwright/test'는 Core API가 아닌 Playwright가 자체 제공하는 테스트 러너 패키지다.

 

여기에는 다음 기능들이 함께 포함된다:

• 테스트 실행기
• test / expect 같은 전역 함수
• 테스트마다 독립적인 BrowserContext 관리
• 확장 가능한 Fixture 시스템
• 병렬 실행, 프로젝트 구조, 셰도잉 등

즉, 'Playwright를 테스트 프레임워크처럼 사용하고 싶다면 반드시 필요한 패키지'가 바로 이에 해당한다.

 

📌 test() 함수와 구조 분해 할당

겉보기에는 단순한 함수처럼 보이지만, test()는 사실 여러 타입과 기능이 조합된 복합적인 함수다.

테스트 러너의 핵심 기능 대부분이 이 test 객체를 중심으로 동작한다.

 

정의를 따라가 보면, 아래와 같다.

const test: TestType = (
  title: string,
  body: TestBody<
    PlaywrightTestArgs &
    PlaywrightTestOptions &
    PlaywrightWorkerArgs &
    PlaywrightWorkerOptions
  >
) => void

 

즉, Playwright의 test 함수는 단일 타입만 넘기지 않고 다음 네 가지 타입을 전부 합친 하나의 객체를 넘긴다.

• PlaywrightTestArgs: 테스트마다 새로 만들어지는 자원 (page, context 등)
• PlaywrightWorkerArgs: 같은 워커에 속한 테스트들이 공유하는 자원
• PlaywrightTestOptions: 테스트 단위 설정
• PlaywrightWorkerOptions: 워커 단위 설정

위 네 개의 타입이 합쳐져 최종적으로 하나의 인자 객체(args)가 만들어진다.

 

여기서 또 PlaywrightTestArgs의 정의를 따라가 보면:

export interface PlaywrightTestArgs {
  page: Page;
  context: BrowserContext;
  request: APIRequestContext;
}

이 정의를 보면 page가 단순한 값이 아니라 Playwright가 미리 생성해 전달해주는 Page 객체라는 점이 명확해진다.
그리고 page뿐만 아니라 context, request 역시 모두 Playwright가 테스트 실행 전에 자동으로 준비해주는 기본 fixture다.

 

즉, test()는 겉으로 보기에는 하나의 인자(args)만 받지만, 실제로는 다음과 같은 '큰 객체 하나'를 테스트 함수로 전달한다.

{
  page: Page,
  context: BrowserContext,
  request: APIRequestContext,
  ...기타 Playwright 기본 fixture들,
  ...내가 extend()로 추가한 custom fixture들
}

이처럼 args 내부에 수많은 값이 들어 있기 때문에, 테스트 코드에서는 필요한 값만 골라 쓰기 위해 다음과 같이 구조 분해 할당을 사용하는 것이 기본 패턴이 된다.

 

구조 분해를 사용하지 않으면 모든 fixture에 접근할 때마다 다음처럼 작성해야 한다.

test('example', async (args) => {
  await args.page.goto('/');
});

즉, Playwright가 구조 분해 할당을 기본 사용 방식으로 안내하는 이유는 테스트 함수에 전달되는 인자 객체가 매우 크고 복합적이기 때문이다.

필요한 fixture만 간단하게 꺼내 쓸 수 있도록 구조 분해가 자연스럽게 최적의 선택이 된다.

 

🔍 더 나아가: Custom Fixture 코드

import { test as base } from '@playwright/test';
import { TodoPage } from './todo-page';

// Extend basic test by providing a "todoPage" fixture.
const test = base.extend<{ todoPage: TodoPage }>({
  todoPage: async ({ page }, use) => {
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await todoPage.addToDo('item1');
    await todoPage.addToDo('item2');
    await use(todoPage);
    await todoPage.removeAll();
  },
});

test('should add an item', async ({ todoPage }) => {
  await todoPage.addToDo('my item');
  // ...
});

test('should remove an item', async ({ todoPage }) => {
  await todoPage.remove('item1');
  // ...
});

이 코드를 처음 봤을 때, 또 다시 다음과 같은 질문들이 떠올랐다.

• as는 왜 쓰는 걸까?
• extend는 무슨 역할?
• <{ ... }> 구조는 뭐지?
• ({ ... }) 구조는 뭐지?

다시 해당 질문들을 하나씩 따라가 보기로 했다.

 

📌 as: 기본 test 이름 변경

import { test as base } from '@playwright/test';

as는 단순히 import한 식별자의 이름을 바꾸는 문법이다.

 

기본 test를 확장해서 새로운 test 객체를 만들 것이기 때문에, 원본과 구분하기 위해 base라는 이름으로 바꿔서 가져오는 것이다.

• base: Playwright가 제공하는 기본 test
• test: 내가 확장한 커스텀 test

이렇게 이름을 나누지 않으면 혼란이 생긴다.

 

📌 Playwright에서 extend()는 어떤 역할을 하는가?

Playwright는 fixture 기반 테스트 프레임워크다. test()가 넘겨주는 page, context 역시 기본 fixture다.

extend()는 여기에 새로운 fixture를 추가하거나 기존 fixture를 재정의할 수 있는 기능이다.

 

const test = base.extend<{ todoPage: TodoPage }>({ ... });

이렇게 작성하면,

• 기존 test 기능은 그대로 유지하고
• todoPage라는 새 fixture를 테스트 함수에서 사용할 수 있게 된다

즉, 테스트 실행 환경을 커스터마이징하는 Playwright의 정식 방식이다.

 

📌 왜 <{ todoPage: TodoPage }>처럼 제네릭을 쓰는가?

여기서 <{ todoPage: TodoPage }>는 TypeScript 제네릭이다.
이 제네릭은 '내가 새로 추가할 fixture가 어떤 타입을 가지는지'를 Playwright에게 알려준다.

• key: fixture 이름 (todoPage)
• value: 해당 fixture가 어떤 타입인지 (TodoPage 클래스)

이 타입 정보를 넘겨두어야 테스트 함수 내부에서 자동 완성 및 타입 추론이 정상적으로 동작한다.

 

그리고 내가 새로 추가할 fixture는 한 개일 수도 있고, 여러 개일 수도 있다.

Playwright는 이런 다양한 경우를 모두 지원하기 위해, ‘fixture 이름: fixture 타입’들을 하나의 객체 타입으로 묶어서 전달하는 방식을 사용한다.

 

만약 fixture가 여러 개라면 자연스럽게 아래처럼 확장된다.

extend<{
  todoPage: TodoPage;
  userPage: UserPage;
  apiClient: ApiClient;
}>

결국 제네릭에 {}를 쓰는 이유는 단일 fixture든 여러 fixture든 동일한 객체 구조로 확장 가능하도록 하기 위해서다.

 

📌 extend() 안의 {}는?

extend()에 전달하는 객체는 '추가하거나 재정의하고 싶은 fixture 목록'을 선언하는 영역이다.

const test = base.extend<{ todoPage: TodoPage }>({
  todoPage: async ({ page }, use) => {
    // ...
  },
});

 

여기서 핵심은 다음 두 가지다:

• key: fixture 이름
• value: 해당 fixture가 호출될 때 실행할 로직

 

실제로는 이런 순서로 동작한다:

const test = base.extend<{ todoPage: TodoPage }>({
  // 1) fixture 이름: fixture 생성/초기화/정리까지 담당하는 비동기 함수
  todoPage: async ({ page }, use) => {

    // 2) Playwright가 미리 만들어둔 기본 fixture(page 등)를 받아
    //    우리가 원하는 fixture를 생성한다.
    const todoPage = new TodoPage(page);

    // 3) 테스트 실행 전에 필요한 초기화 작업을 수행한다.
    await todoPage.goto();

    // 4) use()를 호출해 fixture를 테스트에 전달한다.
    //    → test('...', async ({ todoPage }) => { ... }) 에서 접근 가능해짐
    await use(todoPage);

    // 5) 테스트 완료 후 cleanup 로직을 실행한다.
    await todoPage.removeAll();
  },
});