우리 팀은 TestLink로 TC를 관리한다. 자동화 요청이 오면 TestLink에서 TC를 꺼내서 스크립트로 옮기는 것이 시작이다.
처음 이 작업을 했을 때 "어, 왜 실패하지?"를 서너 번 반복했다. 돌아보면 대부분 코드 문제가 아니었다. TC를 제대로 안 읽거나, 환경이 안 된 상태에서 실행한 게 대부분이었다. 그 경험을 정리한다.
TC에서 뭘 읽어야 하는가
TestLink TC에는 세 가지가 있다.
- 전제조건: 어떤 페이지에서 시작하는지, 어떤 상태여야 하는지
- 단계: 각 Step에서 무엇을 클릭/입력/확인하는지
- 테스트 데이터: 에이전트 ID, 파일 해시, 정책 이름 등 구체적인 값
전제조건에 "특정 메뉴 클릭"이 있다면, 스크립트에서는 해당 URL로 직접 goto()로 이동하면 된다. 네비게이션 클릭 자체를 테스트하는 게 아니라면 직접 이동이 더 안정적이다.
TC 단계와 스크립트를 1:1로 맞추는 게 중요하다. 빠르게 만들려고 단계를 건너뛰거나 합치면, 실패했을 때 어느 단계인지 파악하기 어려워진다.
스크립트 작성 전에 확인할 것
서버와 로그인 먼저. storageState: 'auth.json'을 쓴다면, 해당 서버로 미리 로그인해서 auth 파일을 갱신해 두어야 한다. 오래된 auth 파일로 시작하면 첫 goto()부터 리다이렉트된다.
테스트 데이터가 실제로 있는지. TC에 나오는 에이전트 ID, 해시값, 정책 이름이 서버에 실제로 있는지 브라우저에서 직접 검색해서 확인한다. 없으면 스크립트를 아무리 잘 써도 실패한다.
스크립트 작성할 때 챙겨야 할 것
TC 단계를 주석으로 남긴다.
/* Given [탐지 > 알림 목록] 메뉴로 진입한다 */
await page.goto('https://' + globalThis.domain + '/security/incidents/alerts');
/* Then 알림 목록 페이지가 표시된다 */
await expect(
page.getByRole('textbox', { name: '탐지 기간' })
).toBeVisible({ timeout: 5000 });
/* When 상세 버튼을 클릭하여 상세 검색 영역을 연다 */
await page.getByText('상세', { exact: true }).click();
실패 스크린샷을 보고 "어느 단계에서 멈췄는지"를 주석만 보고 바로 알 수 있다.
첫 검증은 항상 있는 요소로.
// ❌ 데이터가 없으면 없을 수도 있음
await expect(page.getByText('탐지 일시').first()).toBeVisible();
// ✅ 데이터 유무와 관계없이 항상 있는 요소
await expect(
page.getByRole('textbox', { name: '탐지 기간' })
).toBeVisible({ timeout: 5000 });
이걸 놓치면 "로그인 실패"와 "데이터 없음"을 구분할 수 없다. 항상 있는 요소로 페이지 진입을 먼저 확인하고, 그다음에 데이터 검증으로 넘어간다.
timeout 기준. 개별 검증은 5초, 네트워크가 느린 경우만 10초로 예외 처리한다. 테스트 전체는 test.setTimeout(60000)으로 명시한다.
실행 전 체크리스트
| # | 항목 | 확인 방법 |
|---|---|---|
| 1 | 서버 설정이 맞는가? | product.txt 내용이 실행 대상 서버와 일치하는지 확인 |
| 2 | auth 파일이 해당 서버 세션인가? | 로그인 스크립트 재실행 후 auth.json 갱신 |
| 3 | TC의 테스트 데이터가 서버에 있는가? | 브라우저에서 직접 검색해서 데이터 존재 여부 확인 |
| 4 | timeout이 가이드 기준에 맞는가? | 개별 검증 5초, test.setTimeout(60000) 명시 여부 |
| 5 | 첫 검증이 "항상 있는 요소"인가? | 검색창·날짜 필드·페이지 제목 등 구조 요소로 대체했는지 |
| 6 | TC 단계와 스크립트가 1:1인가? | TC 단계 번호 주석(/* Step 1 */)이 코드에 있는지 |
실패했을 때 원인 분류
첫 실행에서 실패해도 원인 파악이 빠르면 수정이 한 번으로 끝난다.
로그인 실패 → auth 파일 문제
리다이렉트 → 서버 설정 불일치
요소를 못 찾음 → 선택자 문제 (5편 참고)
timeout 초과 → 네트워크 느림 or 잘못된 페이지 검증
데이터 없음 → 테스트 데이터 준비 필요
--headed 옵션으로 실행하면 브라우저를 직접 보면서 어느 단계에서 멈추는지 확인할 수 있다.
npx playwright test 테스트파일.spec.ts --headed --project=chromium
npx playwright test -g "TC_번호" --headed
한 번에 성공하는 스크립트를 만드는 건 코드를 잘 짜는 것보다 준비가 먼저다. 실패해도 원인이 명확하면 수정이 한 번으로 끝난다. 그게 결국 빠른 것이다.
이 시리즈는 여기서 마무리한다. 1편의 단일 제품 자동화에서 시작해, 다중 제품 프레임워크 설계, CI 배포, 원격 에이전트 제어, Locator 심화, TC 변환 프로세스까지 이어졌다. 실제로 부딪히고 해결한 내용들이라 누군가에게 조금이라도 도움이 됐으면 한다.