인터페이스 계약과 관측 포인트
locator, test id, API schema, domain event, log field를 안정적 테스트 계약으로 다루는 방법
핵심 요약
- 안정적 테스트 계약은 selector 하나가 아니라 UI·API schema·domain event·log field를 함께 읽는 구조입니다.
- 브라우저 locator는 getByRole/getByLabel→getByTestId→getByText→CSS/XPath 순으로 우선합니다.
- data-testid는 DOM 구조가 아니라 사용자 의도를
{도메인}-{화면}-{의도}-{요소}로 네이밍합니다. - test id·accessible name·API schema·event payload·trace field 변경은 suite/runner owner가 함께 알아야 합니다.
- contract 정책은 QA 문서가 아니라 프론트·백엔드·플랫폼 product code review 기준에 들어가야 합니다.
에이전틱 테스트 환경에서 중요한 것은 selector 하나가 아니라 시스템이 어디를 잡고 무엇을 관측하는가라는 계약입니다.
계약 표면을 먼저 정의한다
| 계약 표면 | 주로 쓰는 probe | 예시 | 깨졌을 때 문제 |
|---|---|---|---|
| 접근 가능한 UI contract | browser | role, label, heading | 화면은 바뀌었는데 intent를 잃음 |
| stable test id | browser | data-testid | locator drift, review 난이도 증가 |
| API schema / response | API, workflow | JSON schema, status code | 상태 전이와 데이터 무결성 설명 불가 |
| domain event | workflow, canary | order.paid, job.completed | async 완료 시점 판단 실패 |
| log / trace field | incident triage | request_id, tenant_id, run_id | 원인 분류 불가 |
UI 계약만 잘 잡는다고 충분하지 않습니다. agent와 사람이 같은 실패를 해석하려면 UI, API, 이벤트, 로그가 함께 읽히는 구조가 필요합니다.
브라우저 계약의 기본 우선순위
| 우선순위 | 방식 | 사용 조건 | 비고 |
|---|---|---|---|
| 1 | getByRole / getByLabel | 접근 가능한 UI 요소 | 사용자 관점에 가장 가까움 |
| 2 | getByTestId | role/label이 불안정하거나 숨겨진 구조 | 계약 필요 |
| 3 | getByText | 정적 문구, 짧은 CTA | 다국어·문구 변경 위험 |
| 4 | CSS/XPath | 구조 선택 외 대안이 없을 때만 | gate 시나리오 금지 권장 |
data-testid 네이밍 표준
{도메인}-{화면}-{의도}-{요소}
예시
- billing-checkout-submit-button
- admin-user-list-row
- auth-login-email-input규칙은 단순합니다.
- 화면 구조가 아니라 사용자 의도를 이름에 반영합니다.
- 숫자 index나 DOM 계층 정보를 넣지 않습니다.
- 공용 컴포넌트 test id는 제품 도메인과 섞지 않습니다.
언제 stable contract를 추가할까
- role/label만으로 안정적으로 찾기 어려운 커스텀 UI
- drag and drop, virtualized list, dense table row
- 텍스트가 자주 바뀌는 버튼/배지/카운터
- UI 외에도 domain event나 API response를 같이 봐야 하는 async 시나리오
반대로 아래는 stable contract를 남발하지 않습니다.
- 명확한 role과 accessible name이 이미 있는 요소
- 텍스트가 제품 정책상 안정적인 CTA
- purely decorative element
변경 계약
프론트엔드나 플랫폼이 아래를 바꿀 때는 suite owner와 runner owner가 같이 알아야 합니다.
data-testid추가/삭제/이름 변경- accessible name이 바뀌는 문구 변경
- API schema나 event payload field 변경
- key flow의 DOM 구조, virtualization, lazy loading 방식 변경
- triage에 쓰는 log / trace field 제거
code review 체크리스트
- 새 컴포넌트나 API에 어떤 contract를 노출하는지 정의되었는가?
- browser probe가 role/label 기반으로 먼저 읽을 수 있는가?
data-testid가 DOM 구조가 아니라 제품 의도를 반영하는가?- async workflow를 UI text만 보고 판단하고 있지 않은가?
권장 운영 방식
contract 정책은 QA 문서가 아니라 프론트엔드, 백엔드, 플랫폼 개발 기준에도 들어가야 합니다. contract를 product code review에서 다루지 않으면 테스트 환경은 항상 뒤늦게 깨집니다.
anti-pattern
- CSS class 이름을 contract처럼 쓰는 방식
nth-child기반 선택- schema/event/log 변경이 제품팀 로컬 판단으로만 끝나는 문화
- helper 안에 locator와 판정 로직을 숨겨 리뷰에서 보이지 않게 만드는 구조