파이썬 Selenium과 aXe-core로 웹 접근성 자동화 검사하기

파이썬 Selenium과 aXe-core로 웹 접근성 자동화 검사하기

⚡ 접근성 표준을 지키는 자동화, Selenium 스크립트로 aXe-core 활용하는 법

웹 개발을 하다 보면 디자인이나 기능 구현에 집중하다가 접근성을 놓치는 경우가 많습니다.
하지만 장애가 있는 사용자도 원활하게 웹사이트를 이용할 수 있도록 만드는 것은 선택이 아니라 필수입니다.
특히 전 세계적으로 WCAG(Web Content Accessibility Guidelines)와 같은 표준이 강화되면서, 자동화된 접근성 검사의 필요성이 커지고 있죠.
개발자 입장에서는 수동으로 일일이 확인하기보다는 코드 레벨에서 접근성 검사를 자동화할 수 있다면 큰 도움이 됩니다.
파이썬 Selenium과 aXe-core를 결합하면 실제 브라우저 환경에서 aria-role 속성을 비롯한 다양한 접근성 검사를 자동으로 실행하고 결과를 수집할 수 있습니다.
이번 글에서는 그 방법을 구체적으로 알아보겠습니다.

Selenium은 브라우저를 자동으로 제어할 수 있는 강력한 테스트 도구입니다.
여기에 Deque Systems에서 만든 오픈소스 라이브러리 aXe-core를 스크립트로 주입하면, 페이지 내의 버튼, 링크, 이미지, 폼 요소가 접근성 규칙을 따르고 있는지 점검할 수 있습니다.
즉, 단순히 화면이 잘 보이는지만 확인하는 것이 아니라, 보조 기술 사용자에게 의미 있는 역할(role), 이름(name), 상태(state)가 올바르게 전달되는지도 확인할 수 있는 것이죠.
이번 글은 자동화 스크립트 작성법부터 결과 수집 및 해석까지 다루며, 접근성 검사를 프로젝트에 통합하는 데 도움을 줄 것입니다.

🧩 Selenium과 aXe-core의 결합 원리

파이썬에서 Selenium은 크롬이나 파이어폭스 같은 실제 브라우저를 자동으로 제어할 수 있게 해주는 라이브러리입니다.
원래는 사용자 동작을 테스트하거나 크롤링을 위해 많이 활용되지만, 접근성 검사 도구인 aXe-core와 함께 사용하면 그 활용 범위가 확장됩니다.
즉, 개발자가 직접 브라우저 개발자 도구를 열고 검사하는 대신 코드로 자동화할 수 있는 것입니다.

aXe-core는 자바스크립트 기반의 라이브러리로, 페이지의 DOM을 분석하여 WCAG 가이드라인 준수 여부를 검사합니다.
예를 들어 버튼에 적절한 aria-label이 지정되어 있는지, 링크 텍스트가 모호하지 않은지, 이미지에 대체 텍스트가 있는지를 판별할 수 있습니다.
이 과정에서 개발자는 브라우저에 aXe-core 스크립트를 주입하고, 검사 결과를 JSON 형태로 받아 분석할 수 있습니다.

🔗 동작 흐름 이해하기

전체적인 동작 흐름은 간단합니다.
먼저 Selenium이 웹페이지를 로드합니다.
그 다음 aXe-core의 자바스크립트 파일을 주입하고, 페이지에서 실행합니다.
마지막으로 검사 결과를 JSON으로 받아 파이썬 코드에서 처리하는 방식입니다.
이런 구조 덕분에 UI 테스트와 접근성 검사를 동시에 수행할 수 있어 개발 효율성이 높아집니다.

from selenium import webdriver

# 브라우저 실행
driver = webdriver.Chrome()
driver.get("https://example.com")

# aXe-core 스크립트 주입
with open("axe.min.js", "r") as file:
    axe_source = file.read()

driver.execute_script(axe_source)

# 접근성 검사 실행
results = driver.execute_async_script("var callback = arguments[arguments.length - 1]; axe.run().then(callback);")

print(results)
driver.quit()

위 예제는 가장 기본적인 구조로, 브라우저를 열고 aXe-core를 주입한 뒤 검사 결과를 수집하는 과정을 보여줍니다.
이 결과는 JSON으로 반환되며, 위반된 규칙의 유형, 노드 위치, 추천 수정 사항까지 포함하기 때문에 바로 리포팅에 활용할 수 있습니다.

⚙️ aXe-core 스크립트 주입 방법

aXe-core를 Selenium 테스트 환경에 통합하기 위해서는 먼저 axe.min.js 파일을 다운로드해야 합니다.
Deque Systems의 GitHub 저장소에서 최신 버전을 받을 수 있으며, 해당 파일은 브라우저 DOM 내에 직접 삽입되어 실행됩니다.
이 과정은 일반적인 자바스크립트 인젝션 방식과 유사하며, Selenium의 execute_script() 또는 execute_async_script() 메서드를 사용합니다.

실제로는 테스트 시작 시 브라우저에 접근하여 axe.min.js의 내용을 불러오고, DOM에 주입한 뒤 axe.run() 명령을 실행합니다.
이 명령은 비동기적으로 동작하기 때문에 콜백을 통해 검사 결과를 반환받게 됩니다.
Selenium은 이러한 비동기 자바스크립트 실행을 지원하므로 접근성 검사 결과를 바로 수집할 수 있습니다.

📥 스크립트 주입 예제

from selenium import webdriver

driver = webdriver.Chrome()
driver.get("https://example.com")

# axe-core 파일 읽기
with open("axe.min.js", "r", encoding="utf-8") as f:
    axe_js = f.read()

# 브라우저에 주입
driver.execute_script(axe_js)

# 비동기 실행
results = driver.execute_async_script("""
var callback = arguments[arguments.length - 1];
axe.run().then(function(results) {
    callback(results);
});
""")

print(results["violations"])
driver.quit()

위 코드는 Selenium을 통해 웹페이지를 연 뒤 axe.min.js를 실행하여 결과를 가져오는 방식입니다.
결과 객체에는 violations(위반사항), passes(통과된 규칙), incomplete(검사 불완전) 항목이 포함되어 있으며, 각 위반 항목마다 DOM 노드와 수정 권장 사항이 함께 기록됩니다.

⚠️ 주의사항

이와 같은 주입 방식을 적용하면 반복적인 테스트 환경에서 자동으로 접근성 검사를 수행할 수 있습니다.
특히 UI 변경이 잦은 프로젝트에서는 수동 점검을 줄이고 품질 보증 속도를 크게 높일 수 있습니다.

📊 검사 결과 수집과 리포팅

aXe-core는 검사 결과를 JSON 객체로 반환합니다.
이 데이터에는 각 위반 규칙의 ID, 설명, 심각도, 그리고 위반된 요소의 CSS 셀렉터까지 포함되어 있어 매우 상세합니다.
개발자는 이 데이터를 파싱하여 로그 파일로 저장하거나, HTML·CSV 형태의 리포트로 변환해 팀 내에서 공유할 수 있습니다.

특히 violations 항목은 우선적으로 확인해야 할 핵심 결과이며, 여기에는 해당 요소의 문제점과 수정 방법이 함께 제공됩니다.
반대로 passes는 규칙을 만족한 요소, incomplete는 분석이 불완전한 요소를 의미합니다.
이 구조 덕분에 어떤 부분이 심각한 접근성 위반인지 빠르게 파악할 수 있습니다.

📂 결과 데이터 구조 예시

{
  "violations": [
    {
      "id": "aria-roles",
      "impact": "serious",
      "description": "ARIA role must be appropriate for the element",
      "nodes": [
        {
          "target": ["#menu"],
          "html": "<div role='button'>",
          "failureSummary": "Fix the ARIA role or use a semantic element"
        }
      ]
    }
  ],
  "passes": [...],
  "incomplete": [...]
}

위 예시는 aria-role 규칙을 위반한 사례를 보여줍니다.
role 속성이 div에 잘못 지정된 경우 경고가 발생하며, 해당 요소의 위치와 문제 해결 방법까지 안내합니다.
이처럼 자동 리포트는 실무에서 바로 적용 가능한 수준의 정보를 제공합니다.

📑 리포트 활용 방법

• 📌JSON 결과를 로그 파일로 저장하여 회귀 테스트 시 비교
• 📌CSV나 Excel 파일로 변환해 QA 팀과 공유
• 📌CI/CD 파이프라인에 통합하여 빌드 실패 조건으로 활용

이처럼 검사 결과를 구조화해 리포트화하면 단순 확인을 넘어 조직 차원에서 품질 관리 프로세스로 활용할 수 있습니다.
또한 문제 요소가 추적 가능해지므로 수정 우선순위를 정하는 데도 효과적입니다.

🔍 aria-role과 접근성 속성 검사 활용

웹 접근성 검사에서 가장 중요한 항목 중 하나가 바로 ARIA 속성입니다.
특히 role 속성은 보조 기술(예: 스크린리더) 사용자에게 요소의 의미를 전달하는 데 핵심적인 역할을 합니다.
예를 들어 버튼을 <div> 태그로 구현하면서 role=”button”을 지정하지 않으면 보조 기술은 단순한 영역으로 인식하여 사용자가 동작을 이해하기 어렵습니다.

aXe-core는 이러한 aria-role 속성의 적절성 여부를 검사하여, 잘못된 값이나 누락된 속성을 자동으로 탐지합니다.
예컨대 <nav> 같은 시맨틱 태그에 불필요한 role을 추가한 경우에도 경고를 발생시키며, aria-label 또는 aria-labelledby가 지정되지 않은 경우 문제를 보고합니다.

🛠️ 검사 대상 속성

이처럼 aXe-core는 단순히 role 속성만 보는 것이 아니라 접근성과 직결된 다양한 ARIA 속성을 함께 점검합니다.
따라서 스크립트 결과를 분석하면 어떤 속성이 누락되었는지, 잘못 지정되었는지 한눈에 파악할 수 있습니다.

💎 핵심 포인트

개발 단계에서 aria-role 검사를 자동화하면, 코드 리뷰 과정에서 미처 발견하지 못한 문제까지 탐지할 수 있습니다.
이는 제품 출시 전 품질 보증을 강화할 뿐 아니라, 장기적으로 사용자 만족도를 높이는 중요한 투자이기도 합니다.

🚀 CI/CD 파이프라인에 접근성 검사 통합

접근성 검사는 단순히 개발자의 개인 환경에서 실행하는 것에 그치지 않고, CI/CD 파이프라인에 통합하는 것이 이상적입니다.
이렇게 하면 새로운 코드가 배포될 때마다 자동으로 접근성 검사가 수행되어, 잠재적인 문제를 조기에 발견할 수 있습니다.

예를 들어 GitHub Actions, GitLab CI/CD, Jenkins 같은 도구에서 Selenium 테스트 스크립트를 실행하고, aXe-core의 검사 결과를 리포트 파일로 저장할 수 있습니다.
빌드 단계에서 심각한 접근성 위반 사항이 발견되면 파이프라인을 실패 조건으로 처리하여, 문제 해결 전에는 배포가 진행되지 않도록 할 수도 있습니다.

⚙️ CI/CD 연동 방식

• 🔧Selenium 테스트 스크립트를 CI 파이프라인 빌드 단계에 추가
• 📊aXe-core 검사 결과를 JSON/HTML 리포트로 저장
• 🚫심각도 높은 위반 발생 시 파이프라인 자동 실패 처리
• 📩QA 팀 또는 개발자에게 이메일·슬랙으로 자동 알림 전송

💡 실제 적용 예시

# GitHub Actions 워크플로 예시
name: Accessibility Test

on: [push, pull_request]

jobs:
  test-accessibility:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: pip install selenium
      - name: Run Selenium aXe-core test
        run: python tests/accessibility_test.py

이처럼 CI/CD 환경에 접근성 검사를 포함하면, 팀은 코드 변경 시마다 자동으로 품질을 점검할 수 있습니다.
이는 단순히 버그 방지 차원을 넘어, 제품 전체의 사용자 경험 품질을 보장하는 강력한 수단이 됩니다.

❓ 자주 묻는 질문 (FAQ)

✅ Selenium과 aXe-core로 접근성 자동화 검사 완성하기

파이썬 Selenium과 aXe-core를 활용하면 단순한 UI 테스트를 넘어 접근성까지 자동으로 검증할 수 있습니다.
특히 aria-role과 같은 ARIA 속성을 자동 검사하여 보조 기술 사용자가 불편 없이 웹사이트를 이용할 수 있도록 돕는 것이 핵심입니다.
또한 검사 결과를 JSON으로 수집하고, 이를 리포트화하여 QA 및 개발 프로세스에 반영하면 조직 차원에서 품질 관리가 한층 강화됩니다.

CI/CD 파이프라인에 접근성 검사를 통합하면 코드가 배포되기 전마다 자동으로 품질 검증이 이루어집니다.
이는 단순히 규정을 준수하기 위한 작업이 아니라, 실제 사용자 경험을 높이고 브랜드 신뢰도를 강화하는 중요한 투자입니다.
자동화된 접근성 검사는 장기적으로 개발 효율을 높이고 유지보수 비용을 줄여 주며, 더 많은 사용자가 차별 없이 서비스를 누릴 수 있도록 만듭니다.

🏷️ 관련 태그 : Selenium, 파이썬자동화, 웹접근성, aXe-core, aria-role, WCAG, QA자동화, 테스트자동화, CI/CD, 웹표준