@dhlab/e2e-autogen
Version:
Google 스프레드시트 기반 시나리오를 Playwright 테스트 스텁 코드로 자동 생성하고, 테스트 실행 결과를 다시 시트에 업데이트하는 CLI 도구
279 lines (200 loc) • 10.3 kB
Markdown
# 🤖 E2E Autogen
Google 스프레드시트 기반 시나리오를 E2E 테스트 **스텁 코드**로 자동 생성하고, 테스트 결과를 관리하는 CLI 도구입니다.
## ✨ 주요 기능
- 🌐 **Google Sheets 연동**: 서비스 어카운트 인증으로 시트를 안전하게 불러옵니다
- 🔍 **멀티 시트 자동 처리**: `[TC-x]` 시트를 자동 감지하여 한 번에 변환합니다
- 🧪 **프레임워크 지원**: Playwright와 Detox 테스트 코드 스텁을 생성합니다
- 🚀 **간편 CLI**: 한 줄 명령으로 손쉽게 실행할 수 있습니다
- 📝 **결과 자동 업데이트**: 테스트 실행 결과를 Google Sheets에 자동으로 업데이트합니다
- 📊 **커버리지 분석**: 테스트 실행률, 성공률, 시트별 상세 통계를 제공합니다
- 🎯 **커스텀 리포터**: 전용 리포터로 정확한 테스트 결과 분석을 지원합니다
- ⚙️ **유연한 설정**: 사용자 정의 컬럼 매핑으로 다양한 시트 구조를 지원합니다
> 💡 **스텁 코드(Stub Code)란?**
> 실제 구현 로직은 없지만 기본 구조와 가이드 주석이 포함된 코드 틀입니다.
> 개발자는 생성된 틀에 실제 테스트 로직만 추가하면 됩니다.
## 📦 설치
```bash
npm install @dhlab/e2e-autogen
```
### 🔍 설치 확인
설치가 정상적으로 완료되었는지 확인해보세요:
```bash
# 버전 정보 확인
e2e-autogen --version
# 사용법 확인
e2e-autogen --help
```
## 📊 Google Sheets 연동 설정
### 1️⃣ 서비스 어카운트 설정
Google Sheets API를 사용하기 위해 서비스 어카운트 인증이 필요합니다:
```bash
# 인증 파일 디렉토리 생성
mkdir -p playwright/.auth
# 노션에 있는 credentials.json 내용을 복사하여 다음 위치에 저장
# playwright/.auth/credentials.json
```
> **💡 인증 파일 준비 방법**
>
> - 팀 계정으로 생성된 서비스 어카운트를 사용합니다
> - 노션에서 `credentials.json` 파일 내용을 복사하여 저장하세요
### 2️⃣ 스프레드시트 데이터 구조
팀 공통 QA 시트를 이용해주세요.
스프레드시트는 다음과 같은 컬럼 구조로 이루어져 있습니다.
| 컬럼 | 설명 | 예시 |
| ----------------- | ---------------------------------------- | ------------------------------------------------------ |
| A (시나리오 ID) | 테스트 시나리오 식별자 | TC-1.1 |
| B (e2e 시나리오) | 시나리오 설명 | 질문 입력 |
| C (UI path) | 테스트 대상 UI 경로 | 홈 / 입력창 |
| D (action/when) | 테스트 액션 또는 조건 | 메인화면 로드 |
| E (expected/then) | 기대 결과 | 질문 입력창이 정상적으로 표시 |
| F (테스트 ID) | 개별 테스트 스텝 식별자 | TC-1.1.1 |
| G (Tag) | 어떤 맥락에서 나온 테스트케이스인지 기록 | `bugfix`, `new` |
| H (Comment) | 자유롭게 작성 | |
| I~ (결과 컬럼) | 테스트 실행 결과 (자동 업데이트) | `pass`, `fail`, `flaky`, `not_executed`, `manual_only` |
### 3️⃣ 스프레드시트 공유 설정
1. Google Sheets에서 테스트할 스프레드시트를 엽니다
2. **공유** 버튼 클릭
3. 노션에 안내된 서비스 어카운트 이메일을 **Editor** 권한으로 추가
4. 스프레드시트 URL을 복사합니다 (URL에 포함된 gid가 특정 시트를 지정합니다)
## ⚙️ 설정 파일
프로젝트 루트에 `e2e-autogen.config.ts` 파일을 생성하고 다음과 같이 설정하세요:
```typescript
export default {
// Google Sheets URL (required)
sheetsUrl: "https://docs.google.com/spreadsheets/d/...",
// 테스트 프레임워크 (optional, default: "playwright")
framework: "playwright",
// 스텁 코드 생성 디렉토리 (optional, default: "./playwright/__generated-stub__")
stubOutputFolder: "./playwright/__generated-stub__",
// 테스트 결과 JSON 파일 경로 (optional, default: "./playwright/e2e-autogen-reporter.json")
jsonReporterFile: "./playwright/e2e-autogen-reporter.json",
// Google API 인증 파일 경로 (optional, default: "./playwright/.auth/credentials.json")
credentialsFile: "./playwright/.auth/credentials.json",
// Google Sheets 컬럼 매핑 (optional, 사용자 정의 가능)
googleSheetColumns: {
scenarioId: "A", // 시나리오 ID 컬럼
scenarioDescription: "B", // 시나리오 설명 컬럼
uiPath: "C", // UI 경로 컬럼
when: "D", // 액션/조건 컬럼
then: "E", // 기대결과 컬럼
testId: "F", // 테스트 ID 컬럼
tag: "G", // 태그 컬럼
comment: "H", // 코멘트 컬럼
},
};
```
## 🚀 사용법
### 💻 CLI 명령어
```bash
# 스프레드시트에서 [TC-x] 시트 자동 처리
e2e-autogen generate
# 시트에 테스트 결과 자동 업데이트
e2e-autogen update
# 도움말 보기
e2e-autogen --help
# 버전 확인
e2e-autogen --version
```
## 🎯 생성된 테스트 코드 예시
Google Sheets 데이터에서 다음과 같은 테스트 스텁 코드가 생성됩니다:
### Playwright 스텁 코드
```typescript
// 📝 Auto-generated by E2E-Autogen
// 🔧 Generated from: TC-1.1
import { test } from "@playwright/test";
test("[TC-1.1] 질문 입력", async ({ page }) => {
await test.step("[TC-1.1.1] 메인화면 로드 -> 질문 입력창이 정상적으로 표시", async () => {
// 📍 UI Path: 홈 / 입력창
// 🎬 When: 메인화면 로드
// ✅ Then: 질문 입력창이 정상적으로 표시
});
await test.step("[TC-1.1.2] 질문 입력창에 문자 입력 -> 정상적으로 입력됨", async () => {
// 📍 UI Path: 홈 / 입력창
// 🎬 When: 질문 입력창에 문자 입력
// ✅ Then: 정상적으로 입력됨
});
});
```
> **💡 스텁 코드 특징**
>
> - 각 테스트 케이스는 여러 스텝으로 구성됩니다
> - 실제 구현 로직은 포함되지 않으며, 개발자가 직접 추가해야 합니다
> - Given/When/Then 패턴을 따르는 BDD 스타일 주석이 포함됩니다
> - Playwright Test Generator를 활용하면 빠르게 작성 가능합니다
## 📁 생성된 파일 구조
```
<output-directory>/
└── TC-1.stub.ts # sheetId(대분류)별 테스트 파일
```
## 🎯 커스텀 리포터 설정
정확한 테스트 결과 분석을 위해 전용 리포터를 사용하세요:
### Playwright 설정
`playwright.config.ts`에 리포터를 추가하세요:
```typescript
import { defineConfig } from "@playwright/test";
export default defineConfig({
// ... 기존 설정
reporter: [
["html"],
[
require.resolve("@dhlab/e2e-autogen/playwright/reporter"),
{
outputFile: "./playwright/e2e-autogen-report.json",
},
],
],
// ... 나머지 설정
});
```
### 리포터 기능
- **test.step별 상태 추적**: 각 테스트 스텝의 성공/실패/재시도 상태를 정확히 기록
- **Flaky 테스트 감지**: 재시도 시 성공/실패가 혼재하는 불안정한 테스트를 자동 감지
- **Manual 테스트 지원**: 수동으로만 실행 가능한 테스트 케이스 구분
- **상세 메타데이터**: 실행 시간, 에러 메시지, 테스트 ID 등 상세 정보 수집
## 📊 테스트 결과 자동 업데이트
테스트 실행 결과를 Google Sheets에 자동으로 업데이트하는 기능입니다:
### 📍 결과 기록 방식
- **위치**: 마지막 컬럼 다음에 자동으로 추가됩니다
- **구조**: 결과 + 실행 날짜/시간 컬럼으로 구성됩니다
- **드롭다운**: 결과 컬럼에는 선택 가능한 드롭다운 메뉴가 제공됩니다
### 🎯 지원 결과 유형
- ✅ `pass`: 테스트 성공
- ❌ `fail`: 테스트 실패
- ⚠️ `flaky`: 불안정한 테스트 (일부 성공, 일부 실패)
- ⏭️ `not_executed`: 미실행
- 📝 `manual_only`: 수동 테스트만 가능
### ⚡ 자동화 기능
- **시트 업데이트**: 테스트 실행 후 결과가 시트에 반영
- **이력 관리**: 실행 날짜와 시간을 `YYYYMMDD:HH:mm` 형식으로 기록
- **시트별 처리**: `[TC-x]` 패턴의 시트를 자동 감지하여 각각 업데이트
- **결과 통계**: 테스트 ID별로 성공/실패 횟수를 집계하여 상태 결정
## 📊 커버리지 분석
테스트 실행 결과를 바탕으로 상세한 커버리지 분석을 제공합니다:
### 📈 제공 지표
#### 전체 요약
- **총 스위트 수**: 분석된 테스트 스위트 개수
- **시나리오 수**: 총 테스트 시나리오 개수
- **테스트 케이스 수**: 총 테스트 케이스 개수
- **실행률**: (실행된 테스트 / 전체 테스트) × 100
- **성공률**: (성공한 테스트 / 실행된 테스트) × 100
#### 상태별 통계
- `pass`: 성공한 테스트 수
- `fail`: 실패한 테스트 수
- `flaky`: 불안정한 테스트 수
- `not_executed`: 미실행 테스트 수
- `manual_only`: 수동 테스트 수
#### 스위트별 분석
각 테스트 스위트(`[TC-x]`)별로 개별 커버리지 통계를 제공합니다.
### 📋 커버리지 시트 자동 생성
`e2e-autogen update` 실행 시 `[COVERAGE]` 시트가 자동으로 생성되어 다음 정보를 기록합니다:
- 실행 시간 및 날짜
- 전체 커버리지 요약
- 스위트별 상세 통계
- 시간별 커버리지 변화 추이
> **💡 주의사항**
>
> - 서비스 어카운트에 **Editor** 권한이 필요합니다
> - 커스텀 리포터 설정이 필요합니다
> - 각 시트는 `[TC-x]` 형식으로 작성되어야 합니다
## 📄 라이선스
MIT © dhlab-fe