Mcube333/playwright-java-test-writer

Playwright Java Test Writer

수동 테스트 케이스를 마치 프레임워크를 소유한 사람이 작성한 것처럼 유지보수 가능한 Playwright Java 테스트로 변환합니다: 병렬 안전, 불안정한 슬립 없음, 로케이터를 숨기는 페이지 오브젝트, 원본 테스트 케이스 ID로 추적 가능한 Allure 리포트.

워크플로

1. 수동 테스트 케이스 파싱

각 케이스에서 다음을 추출합니다: ID, 제목, 우선순위/심각도, 전제 조건, 테스트 데이터, 단계, 단계별 예상 결과. 입력 형식이 다양하므로(Excel 행, Jira 내보내기, Gherkin, 자유 텍스트) 코드를 작성하기 전에 이 형식으로 정규화합니다.

케이스가 작성된 그대로 자동화할 수 없는 경우(실제 휴대폰의 OTP 필요, "올바르게 보임"과 같은 시각적 판단, 실제 돈이 사용된 타사 결제), 가짜로 구현하지 마십시오. 출력에서 자동화되지 않음 아래에 이유와 함께 나열하고 제안(API 모킹, 테스트 OTP 사용, 시각적 스냅샷 비교)을 추가합니다.

2. 먼저 기존 프레임워크 규칙 감지

사용자가 repo 파일(BaseTest, page 클래스, testng.xml, pom.xml)을 공유하는 경우 이를 정확히 미러링합니다: 패키지 이름, 기본 클래스 이름, 명명 스타일, assertion 스타일, 설정 읽기 방식. 코드베이스와의 일관성이 아래 참조 스타일보다 우선합니다.

아무것도 공유되지 않은 경우 references/framework-scaffold.md의 스캐폴드를 사용합니다. 스캐폴드 파일(BaseTest, PlaywrightFactory, BasePage, config)은 사용자가 프레임워크를 요청하거나 분명히 프레임워크가 없는 경우에만 생성하고, 그렇지 않으면 이미 존재한다고 가정하고 페이지 오브젝트와 테스트만 생성합니다.

3. 페이지 오브젝트 설계

• 페이지 또는 재사용 가능한 컴포넌트(헤더, 장바구니 드로어, 필터 패널)당 하나의 클래스. 컴포넌트는 자체 클래스를 가지며 페이지에 합성됩니다.
• 로케이터는 생성자에서 초기화되는 private final Locator 필드입니다. 테스트는 절대 page.locator(...)를 직접 호출하지 않습니다.
• 페이지 메서드는 사용자 의도(login(user, pass), addToCart(productName))를 설명하고, 기계적인 동작(clickButton2)을 설명하지 않습니다. Allure @Step("...")으로 어노테이션하고 매개변수 플레이스홀더를 사용하여 보고서가 수동 케이스처럼 읽히도록 합니다.
• 페이지를 이동하는 액션은 다음 페이지 오브젝트를 반환합니다(fluent flow). 페이지에 머무는 메서드는 this 또는 void를 반환합니다.
• 새 메서드를 추가하기 전에 기존 페이지 메서드를 재사용합니다. 두 단계가 같은 의도에 매핑되면 하나의 메서드를 사용합니다.
• Assertion을 위한 상태는 의도 이름을 가진 getter를 통해 Locator(예: errorMessage())로 노출하여 테스트가 웹 퍼스트 assertion을 사용할 수 있도록 합니다.

로케이터 우선순위(가장 안정적인 순서부터):

1. getByTestId(앱에서 data-test, data-qa 등을 사용하는 경우 속성 이름을 한 번 구성)
2. 접근 가능한 이름과 함께 getByRole
3. 사용자가 볼 수 있는 텍스트에 대해 getByLabel / getByPlaceholder / getByText
4. 안정적인 속성에 대한 CSS
5. XPath, 최후의 수단으로만 사용하고 이유를 설명하는 주석 추가

사용자가 DOM, HTML 또는 스크린샷을 제공하지 않은 경우 로케이터를 추측하고 있습니다. 최선의 추측을 작성하고 // TODO-VERIFY locator로 표시하여 검증되지 않은 선택자가 조용히 배포되지 않도록 합니다. 요약에 검증되지 않은 로케이터의 개수를 명시합니다.

4. 테스트 작성

• 수동 케이스당 하나의 @Test 메서드. 메서드 이름 = 동작(shouldShowErrorForLockedUser), ID가 아님.
• 추적성: 케이스 ID를 @TmsLink("TC-012")와 description에 넣습니다. 케이스의 우선순위에 따라 @Epic, @Feature, @Story, @Severity를 매핑합니다(P0/Critical → BLOCKER/CRITICAL, P1 → NORMAL, P2+ → MINOR).
• 모든 예상 결과는 assertion이 됩니다. assertion이 없는 단계는 수동 검사가 누락되었음을 의미하므로 완료하기 전에 다시 확인합니다.
• 전제 조건은 API나 딥 링크가 존재하는 경우 긴 UI 클릭 체인이 아닌 설정 헬퍼나 API 호출에 넣습니다. 로그인 전제 조건(특히 OTP/SSO)의 경우 API 로그인을 한 번 수행하고 context.storageState() / Browser.NewContextOptions().setStorageStatePath(...)를 통해 재사용하는 것을 선호합니다.
• 다른 데이터로 반복되는 케이스 → TestNG @DataProvider를 사용하는 하나의 테스트. @TmsLink는 정적이므로 케이스 ID를 첫 번째 데이터 열로 전달하고 테스트 내에서 Allure.link(caseId, "tms", caseId)를 호출하여 행별 추적성을 유지합니다. 테스트 데이터는 테스트 본문 밖에 둡니다(데이터 제공자, JSON 또는 상수 클래스). 실제 고객 데이터는 절대 사용하지 않습니다.
• 테스트는 독립적이어야 합니다: 실행 순서에 의존하지 않고, 테스트당 새로운 컨텍스트, 생성된 모든 것을 정리합니다.

5. 대기: 조건 기반만

이것이 불안정성의 주요 원인이므로 엄격한 규칙으로 취급합니다:

• Thread.sleep 또는 page.waitForTimeout을 절대 사용하지 않습니다.
• 웹 퍼스트 assertion을 선호합니다: assertThat(locator).isVisible(), hasText, hasCount, assertThat(page).hasURL(...). 이들은 자동 재시도합니다.
• 액션은 이미 조작 가능성을 위해 자동 대기하므로 click()/fill() 앞에 중복 대기를 추가하지 않습니다.
• 결과가 중요한 네트워크 호출을 트리거하는 액션의 경우 래핑합니다: page.waitForResponse(r -> r.url().contains("/cart") && r.ok(), () -> addButton.click()).
• 스피너/로더의 경우: assertThat(loader).isHidden().
• 탐색의 경우: page.waitForURL("**/checkout**").
• 사용자 정의 타임아웃은 설정에서 가져오며, 인라인 매직 넘버를 사용하지 않습니다.

스니펫은 references/framework-scaffold.md → "Wait patterns"를 참조하십시오.

6. 병렬 안전성

모든 Playwright 객체(Playwright, Browser, BrowserContext, Page)는 기본 클래스/팩토리에 의해 관리되는 ThreadLocal에 있으며 테스트 메서드별로 생성 및 종료됩니다. 정적 필드에 저장하거나 테스트 간에 Page를 공유하지 마십시오. 페이지 오브젝트는 생성자를 통해 Page를 전달받습니다. 페이지 오브젝트의 정적 상태는 허용되지 않습니다.

출력 형식

다음 순서로 응답합니다:

1. 파일: 각 파일은 자체 코드 블록에 전체 경로를 제목으로 포함합니다(예: src/test/java/com/example/pages/LoginPage.java). 사용자가 스니펫을 요청하지 않는 한, 가져오기가 포함된 전체 컴파일 가능한 파일(조각이 아님). 약 3개 파일 이상이거나 사용자가 다운로드를 원하는 경우 프로젝트 폴더로 디스크에 씁니다.
2. 추적성 테이블: 케이스 ID | 테스트 메서드 | 자동화된 단계 | 참고.
3. 자동화되지 않음/갭: 건너뛴 케이스 또는 단계와 그 이유.
4. 확인 필요: TODO-VERIFY 로케이터의 개수와 목록, 테스트 데이터 또는 환경에 대한 가정.

프로세는 짧게 유지하고 코드가 전달물입니다.

기밀 유지

사용자가 공개 포트폴리오를 구축 중이거나 요청이 공개 데모 앱을 언급하는 경우 모든 것을 일반적으로 유지합니다: 패키지 com.example(또는 사용자가 지정한 것), 회사 이름 없음, 내부 URL 없음, 내부 엔드포인트 없음, 실제 사용자 데이터 없음, 독점 이벤트 이름 없음. 붙여넣은 수동 케이스에 이러한 내용이 포함된 경우 중립적인 등가물로 바꾸고 한 줄로 명시합니다.

참조 파일

• references/framework-scaffold.md: pom.xml 의존성, ThreadLocals가 있는 PlaywrightFactory, 실패 시 추적 및 Allure 첨부 파일이 있는 BaseTest, BasePage, ConfigReader, 병렬 실행을 위한 testng.xml, 대기 패턴 스니펫. 스캐폴딩 시 또는 정확한 API 형태가 필요할 때 읽습니다.
• references/example-saucedemo.md: 공개 saucedemo.com 앱에 대한 완전한 작업 예제(수동 케이스 → 페이지 오브젝트 → 테스트 → 추적성 테이블). 출력 스타일을 조정하기 위해 읽습니다.