Storybook 컴포넌트 테스트#

Vue 컴포넌트의 접근성 위반을 자동으로 테스트하기 위해 Storybook test-runner와 axe-playwright를 사용합니다.

이 방식으로 컴포넌트를 독립적으로 테스트하고 개발 과정 초기에 접근성 문제를 발견할 수 있습니다.

사전 요구 사항#

Storybook 접근성 테스트를 실행하기 전에 다음을 준비합니다.

1. 모든 의존성이 설치되어 있어야 합니다(yarn install). 이 작업은 storybook 디렉터리(cd storybook) 안에서 수행합니다.
2. yarn playwright install chromium으로 playwright를 설치합니다. 모든 브라우저 엔진을 설치하려면 yarn playwright install을 사용합니다.
3. 빌드된 Storybook 인스턴스가 실행 중이어야 합니다.

Storybook 접근성 테스트 실행#

Vue 컴포넌트의 자동화된 접근성 테스트는 다음과 같이 실행합니다.

1단계: Storybook 시작#

먼저 Storybook 개발 서버를 시작합니다. 두 가지 방법이 있습니다.

# Option 1: Start Storybook with fresh fixtures
yarn storybook:start

# Option 2: Start Storybook without updating fixtures (faster for subsequent runs)
yarn storybook:start:skip-fixtures-update

중요: 테스트를 진행하는 동안 Storybook 서버를 계속 실행해 둡니다. 테스트가 제대로 실행되려면 Storybook 이 빌드되어 접근 가능한 상태여야 합니다.

2단계: 접근성 테스트 실행#

별도의 터미널에서 GitLab 프로젝트 루트 디렉터리에서 다음을 실행합니다.

yarn storybook:dev:test

이 명령은 다음을 수행합니다.

1. 실행 중인 Storybook 인스턴스를 대상으로 테스트 러너를 시작합니다.
2. 모든 스토리를 순회합니다.
3. 각 스토리에 axe-playwright 접근성 검사를 실행합니다.
4. 발견된 접근성 위반을 보고합니다.

테스트 결과 해석#

테스트 러너는 다음을 출력합니다.

• 통과한 테스트: 접근성 기준을 충족하고 런타임 오류가 없는 컴포넌트입니다.
• 실패한 테스트:
  • 런타임 오류가 있는 컴포넌트입니다.
  • 접근성 위반이 있는 컴포넌트이며, 다음 정보가 함께 표시됩니다.
    • 실패한 구체적인 접근성 규칙
    • 위반을 일으킨 요소
    • 심각도 수준(critical, serious, moderate, minor)
    • 제공 가능한 경우 권장 수정 방안

테스트 실행의 전체 출력은 storybook/tmp/storybook-results.json 파일에서 확인할 수 있습니다.

Storybook 접근성 테스트 모범 사례#

1. 모든 스토리 변형을 테스트합니다: 컴포넌트의 각 스토리가 서로 다른 상태와 구성을 표현하도록 합니다.
2. 상호작용 상태를 포함합니다: hover, focus, active, disabled 상태를 보여 주는 스토리를 만듭니다.
3. 다양한 데이터로 테스트합니다: 실제 사용 상황을 반영하는 현실적인 데이터를 사용합니다.
4. 위반은 즉시 해결합니다: 접근성 문제가 확인되는 즉시 수정합니다.
5. 컴포넌트 접근성을 문서화합니다: 컴포넌트의 스토리 문서에 접근성 관련 고려 사항을 포함합니다.

개발 워크플로와의 통합#

Storybook 접근성 테스트를 개발 과정에 통합하는 방안을 검토합니다.

1. 컴포넌트 개발 중: 테스트를 자주 실행해 문제를 조기에 발견합니다.
2. 머지 리퀘스트 전: 새로 만들었거나 수정한 컴포넌트가 모두 접근성 테스트를 통과하는지 확인합니다.

이 테스트는 *.vue 또는 *.stories.js 파일을 수정할 때마다 CI에서도 실행됩니다. test-frontend 파이프라인의 storybook-test job에서 확인할 수 있습니다.

문제 해결#

테스트가 실행되지 않는다면 다음을 확인합니다.

1. Storybook 실행 여부 확인: Storybook 서버가 예상한 URL에서 접근 가능한지 확인합니다.
2. 의존성 확인: yarn install을 실행해 모든 패키지가 설치되었는지 확인합니다.
3. 빌드 오류 확인: Storybook 빌드 출력에 오류가 있는지 확인합니다.
4. 캐시 정리: 예상하지 못한 문제가 생기면 Storybook을 다시 시작합니다.

도움 받기#

• 접근성 테스트에 관한 질문은 프론트엔드 테스트 가이드를 참고합니다.
• 접근성 모범 사례는 접근성 모범 사례 가이드를 참고합니다.
• 컴포넌트별 접근성 지침은 Pajamas 컴포넌트 문서를 확인합니다.
• 전역 변경이 필요한 접근성 문제를 발견하면 accessibility 레이블과 접근성 심각도 레이블(예를 들어 accessibility:critical)을 붙여 후속 이슈를 만듭니다. 심각도는 테스트 출력에 표시됩니다.