@redicedev/e2e-manual-kit

Playwright E2E 테스트를 실행하면 사용자 매뉴얼(Markdown / HTML / PDF)을 자동 생성하는 키트입니다.

설치

npm install --save-dev @redicedev/e2e-manual-kit

Peer dependency로 @playwright/test >= 1.45.0이 필요합니다.

빠른 시작

1. 테스트 파일 작성

// tests/e2e/settlement-create.spec.ts
import { test } from '@playwright/test';
import { manualMeta, manualStep } from '@redicedev/e2e-manual-kit/helpers';

manualMeta({
  title: '정산 등록 매뉴얼',
  audience: '정산 담당자',
  outputPath: 'docs/manuals/settlement-create.md',
});

test('정산 등록 플로우', async ({ page }) => {
  await manualStep(
    page,
    '로그인 화면 진입',
    '정산 시스템 URL에 접속하면 로그인 화면이 표시됩니다.',
    async () => {
      await page.goto('/login');
    }
  );

  await manualStep(
    page,
    '계정 정보 입력',
    '이메일과 비밀번호를 입력합니다.',
    async (p) => {
      await p.getByTestId('email').fill('[email protected]');
      await p.getByTestId('password').fill('***');
      await p.getByTestId('login-submit').click();
    },
    { highlightClicks: true, showLegend: true }
  );
});

2. Playwright 설정

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { baseConfig, withManualReporter } from '@redicedev/e2e-manual-kit/config';

export default defineConfig(
  withManualReporter(baseConfig, { outputRoot: process.cwd() })
);

3. 테스트 실행

npx playwright test

docs/manuals/ 아래에 Markdown 매뉴얼이 자동 생성됩니다.

주요 기능

manualStep 옵션

| 옵션 | 타입 | 기본값 | 설명 | |------|------|--------|------| | highlightClicks | boolean | true | 스크린샷에 클릭·입력 위치를 번호 마커로 표시 | | showLegend | boolean | — | 스크린샷 하단에 인터랙션 범례 삽입 | | includeInManual | boolean | true | false로 설정하면 테스트는 실행되지만 매뉴얼에서 해당 스텝 제외 | | fullPage | boolean | true | 전체 페이지 스크린샷 | | skipScreenshot | boolean | false | 스크린샷 캡처 건너뛰기 | | annotation | string | — | 스텝에 추가 주석 삽입 |

매뉴얼 제외 스텝 (includeInManual)

로그인, 테스트 데이터 정리 등 테스트에는 필요하지만 사용자 매뉴얼에는 불필요한 스텝을 제외할 수 있습니다.

// 이 스텝은 테스트로 실행되지만 매뉴얼에는 포함되지 않습니다
await manualStep(
  page,
  '테스트 데이터 초기화',
  '관리자 API로 테스트 데이터를 정리합니다.',
  async () => {
    await page.request.post('/api/test/reset');
  },
  { includeInManual: false }
);

인터랙션 마커 색상

| 색상 | 인터랙션 | |------|---------| | 빨간색 | click | | 파란색 | fill, type | | 녹색 | selectOption |

HTML 리포터

Markdown 대신 self-contained HTML 매뉴얼을 생성합니다. 다크 모드, 스크롤 목차 하이라이트를 지원합니다.

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { baseConfig } from '@redicedev/e2e-manual-kit/config';

export default defineConfig({
  ...baseConfig,
  reporter: [
    ['line'],
    ['@redicedev/e2e-manual-kit/html-reporter', {
      outputRoot: process.cwd(),
      imageStrategy: 'data-uri',  // 'data-uri' | 'copy' | 'reference'
    }],
  ],
});

이미지 전략 (imageStrategy)

| 전략 | 설명 | |------|------| | 'data-uri' (기본) | 이미지를 Base64로 인코딩하여 HTML에 인라인 삽입. 단일 파일로 오프라인 열람 가능 | | 'copy' | 이미지를 {outputDir}/images/ 폴더로 복사. 상대 경로로 참조 | | 'reference' | 원본 이미지 경로를 그대로 사용 | | (fn) | 커스텀 함수. (originalPath, outputDir) => { src, copyTo? } |

PDF 리포터

Markdown 리포터에 pdf 옵션을 추가하면 매뉴얼을 PDF로도 생성합니다.

export default defineConfig({
  ...baseConfig,
  reporter: [
    ['line'],
    ['@redicedev/e2e-manual-kit/reporter', {
      outputRoot: process.cwd(),
      pdf: true,  // 또는 { format: 'A4', margin: { top: '20mm', bottom: '20mm' } }
    }],
  ],
});

Markdown + HTML 동시 사용

리포터를 여러 개 등록하면 두 형식을 동시에 생성할 수 있습니다.

export default defineConfig({
  ...baseConfig,
  reporter: [
    ['line'],
    ['@redicedev/e2e-manual-kit/reporter', { outputRoot: process.cwd() }],
    ['@redicedev/e2e-manual-kit/html-reporter', { outputRoot: process.cwd() }],
  ],
});

Entry Points

| Import 경로 | 설명 | |-------------|------| | @redicedev/e2e-manual-kit/helpers | manualMeta(), manualStep() | | @redicedev/e2e-manual-kit/reporter | Markdown 리포터 (ManualBuilderReporter) | | @redicedev/e2e-manual-kit/html-reporter | HTML 리포터 (HtmlManualReporter) | | @redicedev/e2e-manual-kit/config | baseConfig, withManualReporter() | | @redicedev/e2e-manual-kit/pdf | manualToPdf() — Markdown → PDF 변환 |

디렉토리 컨벤션

| 항목 | 경로 | 비고 | |------|------|------| | 테스트 | tests/e2e/**/*.spec.ts | | | 스크린샷 | tests/e2e/screenshots/{spec}/{step}.png | .gitignore 권장 | | Markdown 매뉴얼 | docs/manuals/{name}.md | 체크인 권장 | | HTML 매뉴얼 | docs/manuals/{name}.html | 체크인 권장 | | 매뉴얼 인덱스 | docs/manuals/_index.md | 자동 생성 |

권장 패턴

Selector 규칙

• 모든 인터랙션 요소에 data-testid 부여
• getByTestId('...') 만 사용 (CSS class, 텍스트 selector 지양)
• 매뉴얼 캡처 시점에서 i18n 텍스트가 깨져도 testid는 유지됨

TypeScript / 모듈 호환성

| Consumer | Resolution / Loader | 지원 | |---|---|---| | TS 5.x | bundler / node16 / nodenext | ✅ | | TS 4.9 | node (classic) | ✅ | | Node ESM | import() | ✅ | | Node CJS | require() | ✅ | | Playwright config loader | (CJS-like) | ✅ |

변경 이력

v1.0.1

• includeInManual 옵션 추가 — 매뉴얼에 포함/제외할 스텝을 구분

v1.0.0

• npm 레지스트리 퍼블리시 (@redicedev/e2e-manual-kit)
• HtmlManualReporter 추가 — self-contained HTML 매뉴얼 생성
• 이미지 전략 시스템 (data-uri / copy / reference / custom)
• HTML 다크 모드 & 스크롤 목차 하이라이트(scrollspy)
• 패키지 이름 @redicedev/e2e-manual-kit 으로 통일

v0.1.3

• highlightClicks / showLegend 옵션 — 인터랙션 마커 시각 표시
• Page Proxy → Locator Proxy 재귀 체인으로 모든 Playwright 인터랙션 추적

v0.1.2

• Dual ESM+CJS 빌드 — Node CJS, Jest, Playwright config loader 등 모든 환경 지원

v0.1.1

• typesVersions 추가 — TS 4.9 + classic resolution 정적 type 해결

개발

git clone [email protected]:Redice-Studio/e2e-manual-kit.git
cd e2e-manual-kit
npm install
npm run build
npm run typecheck

License

UNLICENSED — Red Ice Studio internal use only.