Auto QA

Excel 또는 CSV QA 체크리스트를 qa-cases.json 실행 큐로 변환하고, 이 JSON을 실행하는 Cypress 테스트 코드를 생성하는 QA 자동화 도구입니다.

워크플로우

[사용자 입력]
    |
    v
[입력값 파싱]
    |
    v
[입력값 검증]
    |
    v
[시트 스캔]
    |
    v
[TC_ID 행을 JSON으로 생성]
  - 모든 케이스를 NA/대기 상태로 생성
  - CRUD 케이스에는 실제 생성/조회/수정/삭제 검증 지시 포함
    |
    v
[Cypress test code 작성]
  - qa-cases.json을 읽는 테스트 코드 생성
  - pending 케이스를 executionOrder 순서로 실행
  - 실행 결과를 JSON에 다시 기록
    |
    v
+------------------------------+
| 작업 루프                    |
|                              |
|  1. 다음 test JSON 확인      |
|  2. Cypress test 진행        |
|  3. 즉시 결과 기록/반환      |
|  4. 다음 test JSON 확인      |
+------------------------------+
    |
    v
[남은 test JSON 없음]
    |
    v
[최종 결과 반환]

빠른 시작

node skills/qa-runner/scripts/dist/qa-runner.js \
  url=https://example.com \
  qa_sheet=/path/to/qa-checklist.xlsx

CSV도 사용할 수 있습니다.

node skills/qa-runner/scripts/dist/qa-runner.js \
  url=https://example.com \
  qa_sheet=/path/to/qa-checklist.csv \
  out=qa-artifacts/example-run

dry_run=true를 지정하면 qa-cases.json만 생성하고 Cypress 코드는 생성하지 않습니다.

node skills/qa-runner/scripts/dist/qa-runner.js \
  url=https://example.com \
  qa_sheet=/path/to/qa-checklist.csv \
  dry_run=true

산출물

일반 실행 시 기본적으로 qa-artifacts/<run-id>/ 아래에 다음 파일이 생성됩니다.

qa-cases.json
qa-results.csv
cypress/e2e/<run-id>.cy.ts
cypress.config.js
tsconfig.json
<original-name>.result.xlsx  # 입력이 .xlsx일 때만

qa-cases.json은 실행 큐이자 권위 있는 결과 저장소입니다. qa-results.csv는 같은 결과 상태를 표 형태로 내보낸 파일이며, Cypress 실행 중 JSON이 갱신될 때 함께 갱신됩니다. 모든 케이스는 처음에 아래 상태로 생성됩니다.

{
  "excelResult": "NA",
  "progressStatus": "pending",
  "resultStatus": "unknown"
}

Cypress 실행 중에는 케이스별로 running이 기록되고, 실행 직후 pass 또는 fail 결과가 JSON과 CSV에 저장됩니다.

QA 시트 형식

필수 컬럼은 TC_ID입니다. TC_ID가 비어 있는 행은 무시되고, TC_ID 헤더가 없는 시트는 스캔 대상에서 제외됩니다.

주요 컬럼:

필드	허용 헤더
케이스 ID	TC_ID
제목	구분, 시나리오명, 제목
우선순위	우선순위, priority
사전조건	사전조건
테스트 절차	테스트 절차, 절차
기대결과	기대결과, 기대 결과
Cypress Prompt	cypress steps, cypress prompt, cypress_steps, Cypress 절차
테스트 입력값	test inputs, test input, test data, input, inputs, 테스트 입력값, 테스트 입력 값, 입력값, 입력 값, 테스트 데이터
결과	결과
비고	비고, notes
자동화 힌트	automation, 자동화 여부

cypress steps 계열 컬럼이 있으면 생성된 cy.prompt() 단계로 사용합니다. 없으면 사전조건, 테스트 절차, 기대결과를 조합해 prompt 단계를 만듭니다.

test inputs 계열 컬럼이 있으면 qa-cases.json의 testInputs에 그대로 구조화합니다. 컬럼이 없으면 생성/수정/삭제 검증에 필요한 빈 값, 길이 경계값, 중복값 placeholder, 유효 입력값 등을 테스트 절차와 기대결과에서 추론해 추가합니다.

전체 QA 및 CRUD 실행 기준

QA-Runner의 목표는 QA 시트에 있는 모든 TC_ID 케이스를 실행하는 것입니다. 별도 범위 지정이 없다면 모든 케이스를 시트 순서와 행 번호 순서대로 실행 큐에 넣고, 실행자는 각 케이스를 실제 UI에서 수행해야 합니다.

CRUD 케이스는 비파괴 관찰만으로 통과 처리하지 않습니다. 테스트/QA 환경에서 고유한 QA 소유 데이터를 사용해 생성, 조회 또는 확인, 수정, 수정값 확인, 삭제, 삭제 후 미노출 확인까지 수행해야 합니다. 기존 운영성 데이터는 수정하거나 삭제하지 않습니다.

환경, 권한, 계정, 데이터 정책 때문에 실제 생성/수정/삭제가 불가능하면 해당 케이스는 pass가 아니라 blocked 또는 manual로 기록하고, 차단 사유를 qa-cases.json의 결과 요약이나 상세 실행 과정에 남깁니다.

실행 순서

실행 순서는 워크북 작성 순서를 따릅니다.

1. 시트 순서
2. 각 시트 안의 행 번호 오름차순

각 케이스에는 executionOrder와 executionOrderReason이 기록됩니다.

Cypress 실행

생성된 Cypress 프로젝트 디렉터리에서 Cypress와 TypeScript를 설치합니다.

npm install --save-dev cypress typescript

그 다음 생성된 artifact 디렉터리를 Cypress project로 실행합니다.

npx cypress run --project qa-artifacts/<run-id>

주의: 생성된 테스트는 cy.prompt()를 사용합니다. cy.prompt() 실행에는 Cypress Cloud 프로젝트 설정과 유효한 projectId가 필요합니다.

결과 기록

생성된 cypress.config.js는 다음 Cypress task를 제공합니다.

task	역할
qa:getCase	JSON에서 케이스를 읽습니다.
qa:startCase	케이스를 running으로 변경하고 시작 시각을 기록합니다.
qa:completeCase	케이스 결과와 종료 시각을 기록합니다.
qa:summary	전체 진행 요약을 반환합니다.

완료 상태는 다음처럼 기록됩니다.

결과	progressStatus	resultStatus
통과	completed	pass
실패	completed	fail
차단	blocked	blocked
수동 판단 필요	manual	manual
스킵	skipped	skipped

개발 검증

번들 runner 문법 확인:

node --check skills/qa-runner/scripts/dist/qa-runner.js

CSV fixture로 산출물 생성:

node skills/qa-runner/scripts/dist/qa-runner.js \
  url=https://example.com \
  qa_sheet=/tmp/qa-runner-cypress-fixture.csv \
  out=/tmp/qa-runner-example

생성된 Cypress 파일 문법 확인:

node --check /tmp/qa-runner-example/cypress/e2e/<run-id>.cy.ts
node --check /tmp/qa-runner-example/cypress.config.js

관련 문서

• skills/qa-runner/SKILL.md
• skills/qa-runner/references/qa-sheet-format.md