dequelabs/axe-core 딥다이브
— "규칙 하나하나가 selector + matches + checks"로 조립되는 방식

1한 줄 정체

axe-core는 브라우저의 DOM을 직접 들여다보는 접근성 자동 검사기다. axe.run() 한 줄을 페이지 위에서 실행하면, 지금 화면에 그려진 요소들을 규칙(rule) 100여 개에 대고 하나씩 확인한다. 각 규칙은 "어떤 요소를 볼지(selector) → 그 요소가 이 규칙 대상이 맞는지(matches) → 실제 조건을 만족하는지(checks)"라는 3단 구조로 짜여 있고, 그 결과가 모여 violations(위반) · passes(통과) · incomplete(불확실, 사람이 봐야 함) · inapplicable(해당 요소 없음) 4개 배열로 반환된다.

중요한 건 axe-core 혼자서는 아무 화면도 보여주지 않는다는 점이다. npm으로 설치해 axe.js를 페이지에 넣고 콘솔이나 테스트 코드에서 axe.run()을 호출해야 결과(JSON)를 받는다. 그 JSON을 예쁘게 그려주는 일은 Lighthouse·axe DevTools·Playwright 리포터 같은 상위 도구들의 몫이다.

2왜 지금 주목받는가

axe-core는 2016년 첫 릴리스 이후 꾸준히 쓰여온 프로젝트라 "신생 트렌드"는 아니다. 그런데도 최근 다시 주목받는 이유는 아래 세 갈래로 정리된다.

① 접근성 규제가 전 세계적으로 강화되는 시기

유럽연합의 웹 접근성 지침(EN 301 549), 미국의 ADA(장애인차별금지법) 관련 소송 증가, 한국의 웹 접근성 품질인증 요구 등으로 기업들이 "우리 사이트가 WCAG를 지키는지"를 실제로 자동화된 코드로 증명해야 하는 상황이 늘었다. axe-core의 규칙 태그 체계에는 wcag2a·wcag21aa·section508·EN-301-549 같은 국제 표준 코드가 직접 박혀 있어, "이 코드가 어떤 법적 기준에 대응하는지"를 그대로 추적할 수 있다.

② 사실상 업계 표준 엔진 — 경쟁 도구조차 이걸 쓴다

구글 크롬 개발자도구에 내장된 Lighthouse의 접근성 감사가 실제로는 axe-core 기반 규칙을 가져다 쓰고, Deque 자체 상용 제품(axe DevTools)은 물론 @axe-core/playwright·@axe-core/react·webdriverjs·puppeteer용 공식 래퍼까지 전부 이 저장소 하나의 axe.core 엔진을 감싼 것이다. "접근성 자동 검사"라는 카테고리에서 이 저장소가 사실상 공용 코어 역할을 한다.

③ AI가 코드를 대량 생성하는 시대의 안전망

AI 코딩 도구가 UI 컴포넌트를 빠르게 찍어내는 지금, "빠르게 만든 코드가 스크린리더 사용자·저시력 사용자에게도 쓸 수 있는가"를 사람이 매번 손으로 확인하기는 현실적으로 어렵다. axe-core처럼 CI 파이프라인에 넣어 자동으로 회귀를 잡는 엔진의 필요성이 오히려 더 커졌다.

3무엇을 해결하나

접근성 문제(이미지에 설명 없음, 색 대비 부족, 폼 입력에 라벨 없음 등)는 전문 지식이 있어야 눈에 띄는 경우가 많고, 사람이 수동으로 훑으면 느리고, 사람마다 결과가 다르고, 매번 반복해야 하는 3중고가 있다. axe-core는 이 중 "기계적으로 판단 가능한 부분"을 명확히 잘라내 자동화한다.

해결 ① — 반복 검토를 코드 한 줄로

axe.run() 한 줄이면 화면에 보이는 모든 요소를 규칙 100여 개에 대해 검사한다. 사람이 페이지를 열 때마다 눈으로 훑을 필요 없이, 단위 테스트·통합 테스트 안에 끼워 넣어 매 커밋마다 자동으로 돌릴 수 있다. README의 "Getting started" 예시처럼 results.violations.length가 있으면 테스트를 실패시키는 식으로 CI에 바로 연결된다.

해결 ② — "확신 없는 결과"를 숨기지 않고 따로 분류

많은 접근성 문제는 기계가 100% 확신할 수 없다(예: 이미지의 대체 텍스트가 있긴 한데 그 내용이 적절한지는 사람이 봐야 안다). axe-core는 이런 경우를 억지로 통과·실패로 우기지 않고 incomplete(불확실)라는 별도 칸에 담아 "여기는 사람이 확인하라"고 명시적으로 신호를 준다. 이것이 4번째 결과 분류가 있는 근본 이유다(5번 섹션에서 소스로 자세히 짚는다).

해결 ③ — "이 규칙이 어떤 법적 기준인가"를 코드에 못박기

각 규칙 JSON에는 wcag2a·wcag21aa·best-practice·section508·EN-301-549 같은 태그가 붙어 있어, "이 위반이 WCAG 2.1 AA 기준 위반인지, 그냥 권장 사항(모범 사례)인지"를 코드 레벨에서 구분할 수 있다. 회사 정책이 "WCAG 2.1 AA까지만 강제한다"면 runOnly 옵션으로 그 태그만 골라 돌릴 수 있다.

4전체 구조

axe-core의 소스는 lib/ 아래 core(실행 엔진), rules(규칙 정의), checks(판정 함수), commons(공용 로직 — 색·DOM·텍스트 등), standards(ARIA/HTML 명세 데이터) 다섯 축으로 나뉜다. 전체 흐름을 한 장으로 보면 이렇다.

이 구조에서 가장 중요한 관찰은, "규칙(rule)"과 "체크(check)"가 분리돼 있다는 점이다. 규칙은 "어떤 요소를, 어떤 체크 조합으로 판정할지"를 정의한 선언(JSON)일 뿐이고, 실제 판정 코드(진짜 로직)는 체크 쪽에 있다. 체크는 여러 규칙에서 재사용된다 — 예를 들어 aria-label 체크는 이름을 요구하는 규칙 여러 개에서 공유된다.

5핵심 설계·동작 원리

이 섹션이 이 문서에서 가장 두꺼운 이유는, axe-core를 "그냥 쓰는" 사람과 "왜 이렇게 결과가 나오는지 이해하는" 사람의 차이가 전부 여기 있기 때문이다. 실제 소스 파일과 함수명을 하나씩 짚는다.

① 규칙 하나의 실체 — lib/rules/color-contrast.json

가장 유명한 규칙 하나를 실제 파일 그대로 보자(주석은 설명용으로 추가).

{
  "id": "color-contrast",              // 규칙 고유 ID
  "impact": "serious",                 // 위반 시 심각도
  "matches": "color-contrast-matches", // 이 규칙이 적용될 노드를 거르는 함수
  "excludeHidden": false,
  "tags": [
    "cat.color", "wcag2aa", "wcag143", // WCAG 2 AA / 기준 1.4.3
    "TTv5", "EN-301-549", "ACT"
  ],
  "actIds": ["afw4f7", "09o5cg"],       // W3C ACT 규칙 대응 ID
  "metadata": {
    "description": "...",
    "help": "Elements must meet minimum color contrast ratio thresholds"
  },
  "all": [],
  "any": ["color-contrast"],           // any 목록에 체크 1개
  "none": []
}

selector 필드가 없으면 lib/core/base/rule.js의 Rule 생성자가 this.selector = spec.selector || '*'로 기본값을 채운다. 즉 규칙 JSON은 "어떤 요소(selector) + 어떤 필터(matches) + 어떤 체크 묶음(any/all/none)"이라는 선언일 뿐이고, 실제 실행은 자바스크립트 코드(Rule.prototype)가 담당한다.

② 규칙 실행 — gather → matches → runChecks

lib/core/base/rule.js의 Rule.prototype.gatherAndMatchNodes가 실제 흐름을 보여준다.

Rule.prototype.gatherAndMatchNodes = function (context, options) {
  let nodes = this.gather(context, options);      // selector 로 후보 수집
  return nodes.filter(node => {
    return this.matches(node.actualNode, node, context); // matches 함수로 필터
  });
};

그 뒤 Rule.prototype.run은 살아남은 노드마다 ['any', 'all', 'none'].forEach(type => ...)로 세 목록을 각각 runChecks에 넘겨 병렬 실행하고, 노드별로 { any: [...], all: [...], none: [...] } 형태의 원시 결과를 만든다. runChecks 내부에서는 각 체크의 check.run(node, option, context, resolve, reject)를 호출하는데, 이 check.run이 바로 다음 항목이다.

③ 체크 하나의 실체 — evaluate 함수와 true/false/undefined

lib/core/base/check.js의 체크 실행은 checkHelper가 만든 this(data()·relatedNodes()·async() 메서드 제공) 컨텍스트 안에서 evaluate 함수를 돌린다. evaluate가 true를 반환하면 통과, false면 실패, undefined를 반환하면 "확신 못 함"으로 취급된다 — 이 세 번째 값이 바로 incomplete가 생기는 근원지다.

④ any/all/none을 하나의 판정으로 합치기 — 우선순위 산술

세 목록의 개별 결과를 노드 하나의 최종 판정으로 합치는 코드가 lib/core/utils/aggregate-checks.js다. 여기서 핵심은 결과값을 우선순위 숫자로 바꿔 최댓값을 취하는 산술이다.

const checkMap = [];
checkMap[PASS_PRIO] = true;      // 우선순위 1
checkMap[CANTTELL_PRIO] = null;  // 우선순위 2
checkMap[FAIL_PRIO] = false;     // 우선순위 3

// none 타입은 pass/fail 을 뒤집는다 (있으면 실패인 규칙이므로)
if (type === 'none') {
  if (check.priority === PASS_PRIO) check.priority = FAIL_PRIO;
  else if (check.priority === FAIL_PRIO) check.priority = PASS_PRIO;
}

priorities.all  = max(all 체크들의 priority, 0 초기값)
priorities.none = max(none 체크들의 priority, 0 초기값)
priorities.any  = min(any 체크들의 priority, 4) % 4   // any는 "가장 낮은(가장 잘 통과한)" 것 채택

nodeResult.priority = max(all, none, any)  // 셋 중 가장 나쁜(높은) 것이 최종 판정

any는 "하나만 통과해도 됨"이므로 가장 낮은 우선순위(가장 좋은 결과)를 찾고, all과 none은 "하나라도 걸리면 안 됨"이므로 가장 높은 우선순위(가장 나쁜 결과)를 찾는다. 그리고 세 그룹 중에서도 다시 최댓값을 취해 "하나라도 나쁘면 전체가 나쁘다"는 논리를 관철한다. 이 코드 한 파일이 "규칙 하나 = selector + matches + checks 조합"이라는 아키텍처의 실제 심장이다.

⑤ 4가지 결과 분류의 실제 정의 — lib/core/constants.js

violations/passes/incomplete/inapplicable이라는 이름이 어디서 나오는지, 소스에 그대로 있다.

const definitions = [
  { name: 'NA',       value: 'inapplicable', priority: 0, group: 'inapplicable' },
  { name: 'PASS',     value: 'passed',       priority: 1, group: 'passes' },
  { name: 'CANTTELL', value: 'cantTell',     priority: 2, group: 'incomplete' },
  { name: 'FAIL',     value: 'failed',       priority: 3, group: 'violations' }
];

lib/core/utils/aggregate-result.js는 각 노드 결과를 이 우선순위에 따라 4개 배열 중 하나로 나눈다. 에러가 났으면 강제로 incomplete, 결과가 NA면 inapplicable, 그 외엔 해당 그룹 배열에 내용이 있는지로 판단한다.

⑥ 색 대비 계산 — 실제 공식이 그대로 코드에 있다

color-contrast 체크의 핵심 수학은 lib/commons/color/get-contrast.js 한 파일에 있다.

function getContrast(bgColor, fgColor) {
  if (!fgColor || !bgColor) return null;
  if (fgColor.alpha < 1) {
    fgColor = flattenColors(fgColor, bgColor);   // 반투명이면 배경과 합성
  }
  const bL = bgColor.getRelativeLuminance();      // 상대 휘도(밝기)
  const fL = fgColor.getRelativeLuminance();
  return (Math.max(fL, bL) + 0.05) / (Math.min(fL, bL) + 0.05); // WCAG 공식
}

이건 WCAG 2 명세에 나오는 상대 휘도 대비 공식 그 자체다. 이렇게 구한 비율은 has-valid-contrast-ratio.js에서 글자 크기·굵기에 따라 4.5:1(작은 글자) 또는 3:1(큰 글자·굵은 글자) 기준과 비교된다. 실제로는 이 앞에 get-foreground-color.js·get-background-color.js·flatten-colors.js·stacking-context.js 같은 파일들이 "이 텍스트의 진짜 전경색·배경색이 뭔지"(그림자, 겹친 레이어, 투명도까지 고려)를 먼저 알아내는 훨씬 복잡한 선행 작업을 한다 — 색상 연산 자체는 devDependency인 colorjs.io 라이브러리가 담당한다.

⑦ VirtualNode — 진짜 DOM과 판정 로직 사이의 완충지대

axe-core는 규칙·체크가 진짜 브라우저 Node 객체를 직접 쥐지 않고, lib/core/base/virtual-node/의 AbstractVirtualNode를 상속한 VirtualNode(진짜 DOM용)·SerialVirtualNode(직렬화된 가짜 DOM용, 다른 프레임에서 넘어온 데이터를 재구성할 때 사용)로 감싸 쓴다. hasClass() 같은 공통 헬퍼를 여기 한 곳에 두고, "노드가 진짜 DOM인지 프레임 너머에서 온 데이터인지"를 규칙 코드가 신경 쓰지 않아도 되게 만든다.

⑧ 프레임(iframe) 순회 — 무한 깊이까지 재귀

lib/core/base/context.js는 select('frame, iframe', this)로 현재 범위 안의 모든 프레임을 찾고, pushUniqueFrame()이 화면에 보이지 않는(스크린리더에 노출 안 되는) iframe은 건너뛰며 나머지를 context.frames 큐에 쌓는다. 각 프레임은 createFrameContext()로 별도 Context를 만들어 재귀적으로 같은 파이프라인을 탄다. README의 매니페스토에 있는 "무한 깊이의 iframe을 지원한다"는 문장이 정확히 이 코드로 구현돼 있다.

같은 창(window) 안의 프레임은 lib/core/utils/respondable.js가 postMessage 기반으로 부모↔자식 프레임 간에 결과를 주고받는다. 반면 Playwright·Selenium처럼 브라우저를 외부에서 원격 조종하는 자동화 도구는 postMessage 왕복이 번거로우므로, lib/core/public/run-partial.js + finish-run.js라는 별도 경로를 쓴다 — 각 프레임에서 axe.runPartial()을 개별 실행해 부분 결과를 얻고, 최상위에서 axe.finishRun()으로 그 부분 결과들을 한 번에 병합한다. "같은 결과를 얻는 두 가지 경로"가 실제로 코드에 나뉘어 있다는 것 자체가 이 엔진이 다양한 실행 환경(브라우저 내부 vs 자동화 드라이버)을 어떻게 다르게 다루는지 보여주는 좋은 예다.

6기술 스택·의존성

package.json을 열어보면 놀라운 점이 하나 있다 — dependencies 필드가 아예 없다. npm으로 axe-core를 설치해도 딸려오는 런타임 패키지가 0개다. 대신 필요한 라이브러리는 전부 빌드 시점에 최종 산출물(axe.js/axe.min.js) 안으로 번들된다.

이 목록은 lib/core/imports/index.js에 그대로 나열돼 있고, 전부 package.json에는 devDependencies로만 등록돼 있다. 즉 "버전의 진실원"은 이 저장소의 package.json의 version 필드(현재 4.12.1) 하나뿐이며, 이 값이 빌드 스크립트를 통해 axe.js 파일 맨 위 주석(/*! axe v4.12.1 ...*/)과 각 규칙 도움말 URL(dequeuniversity.com/rules/axe/4.12/...)에 그대로 찍힌다.

빌드 도구 — 문서와 실제가 어긋나는 지점

빌드 산출물 — IIFE 하나로 포장

최종 axe.js는 lib/intro.stub(라이선스 헤더 + IIFE 시작)과 lib/outro.stub(IIFE 종료)으로 모든 소스를 감싼 즉시실행함수(IIFE) 한 덩어리다. <script src="axe.js"> 태그 하나만 넣으면 전역에 window.axe가 생기는 이유가 여기 있다 — 모듈 로더가 없던 시절부터 이어진, 어떤 환경에서도 그냥 붙여넣으면 도는 설계다.

기술 스택 요약표

7설치·요구사항

8실제 사용 흐름

가장 흔한 실전 흐름은 "기능 테스트를 짜는 김에 접근성 검사도 같이 돌리는" 방식이다. 아래는 README에 있는 최소 예시를 뼈대로 한 사용 순서다.

1단계 — 검사 실행

axe
  .run()
  .then(results => {
    if (results.violations.length) {
      throw new Error('접근성 문제 발견');    // 위반이 있으면 테스트 실패 처리
    }
  })
  .catch(err => {
    console.error('실행 중 오류:', err.message);
  });

초보자를 위한 한 줄 풀이: "지금 화면에 대고 검사를 돌려서(run), 다 끝나면(then) 위반 목록(violations)이 하나라도 있으면 에러를 던지고, 검사 자체가 실패하면(catch) 그 이유를 콘솔에 찍어라"는 뜻이다. 복사해서 테스트 파일 안에 그대로 붙여도 동작한다.

2단계 — 결과 4묶음을 각각 다르게 다루기

const { violations, incomplete, passes, inapplicable } = results;
console.log('위반(반드시 고쳐야 함):', violations.length);
console.log('불확실(사람이 확인):', incomplete.length);   // 여기를 무시하지 말 것
console.log('통과:', passes.length);
console.log('해당없음:', inapplicable.length);

3단계 — 범위·기준을 옵션으로 좁히기

axe.run(document, {
  runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] }, // WCAG 2 A/AA만
  exclude: [['#legacy-widget']]                            // 낡은 위젯은 검사 제외
});

runOnly에 태그를 넘기면, 그 태그가 붙은 규칙 JSON만 골라 Audit이 구성된다(4번 섹션의 태그 체계가 바로 이렇게 실전에서 쓰인다). 회사 정책이 "베스트 프랙티스는 참고만, 법적 기준(WCAG 2 A/AA)만 강제"라면 이렇게 좁혀 CI를 더 엄격하지 않게 통제할 수 있다.

4단계 — 자동화 프레임워크에서는 래퍼를 통해

Playwright라면 @axe-core/playwright의 AxeBuilder가 "페이지에 axe.js 주입 → runPartial/finishRun으로 프레임까지 처리 → 결과 반환"을 대신 해준다. 이 저장소 자체를 직접 만질 일은, 웹앱을 만드는 대부분의 팀에게는 거의 없다 — 대신 저 래퍼들의 옵션(포함/제외 선택자, 태그 필터)을 다루게 된다.

9함정·오해 방지

오해 ① — "violations가 0이면 우리 사이트는 접근성이 완벽하다"

README가 직접 못박은 숫자가 있다: "axe-core로 평균 WCAG 이슈의 57%를 자동으로 찾을 수 있다." 나머지 43%는 애초에 기계가 판단할 수 없는 영역(문맥적 의미, 실제 사용성, 논리적 읽기 순서의 자연스러움 등)이다. axe-core는 스스로도 "제로 거짓양성(zero false positives)"을 목표로 내세우지만, 동시에 "발견하지 못하는 진짜 문제(false negative)"가 훨씬 많다는 걸 인정하는 셈이다. 자동 검사 통과는 "최소한의 바닥은 다졌다"는 뜻이지 "접근성 인증"이 아니다.

오해 ② — axe.run()을 동시에 두 번 부를 수 있다

lib/core/public/run.js는 axe._running 플래그로 동시 실행을 원천 차단한다. 이미 실행 중일 때 다시 axe.run()을 부르면 "Axe is already running..." 에러가 던져진다. 비동기 테스트 코드에서 await를 빼먹고 두 검사를 동시에 걸면 이 에러를 마주친다 — axe-core 버그가 아니라 의도된 안전장치다.

오해 ③ — 105개 규칙이 전부 항상 실행된다

lib/rules/ 안의 JSON 파일은 105개이지만, 이 중 duplicate-id·duplicate-id-active·audio-caption·aria-roledescription·landmark-complementary-is-top-level 5개는 파일 안에 "enabled": false가 박혀 있는 폐지(deprecated) 규칙이다. 기본 실행에서는 100개만 돈다. 오래된 예제 코드에서 저 규칙 이름을 보고 "지금도 기본으로 도는 규칙이겠지" 오해하면 안 된다 — 하위 호환을 위해 코드만 남겨둔 것이다.

오해 ④ — 색 대비 규칙은 "색상 값"만 보면 계산된다

실제로는 get-foreground-color·get-background-color가 텍스트 그림자, 겹친 레이어(stacking context), 반투명도까지 역추적해야 색이 확정된다. 이 과정에서 값을 확정 지을 수 없으면(예: 배경이 이미지라 실제 픽셀 색을 알 수 없을 때) 이 체크도 incomplete로 떨어진다 — "색 대비 위반이 안 뜨니 통과"가 아니라 "색을 특정 못 해 사람이 봐야 하는" 경우가 섞여 있을 수 있다.

10대안 비교

11정리 / 누가 쓰면 좋은가

axe-core는 "규칙(selector+matches+checks) → 우선순위 산술로 4분류 → 상위 도구가 소비"라는 단순하지만 정교한 파이프라인 하나로, 웹 접근성 자동 검사라는 분야의 사실상 표준 엔진이 됐다. 런타임 의존성 0개로 가볍게 배포되고, 105개 규칙·20개 언어·무한 깊이 iframe 지원까지 갖춘 성숙한 프로젝트다.

이 저장소를 직접 들여다볼 가치가 있는 사람은 다음과 같다.

• 프론트엔드 개발자 — 자신의 테스트 스위트에 접근성 검사를 처음 끼워 넣으려는 사람. README의 axe.run() 최소 예시만으로도 오늘 바로 시작할 수 있다.
• QA·접근성 엔지니어 — runOnly 태그 필터로 회사 정책(WCAG 2.1 AA 등)에 맞춘 CI 게이트를 설계하려는 사람.
• 규칙/판정 로직 자체를 공부하려는 엔지니어 — "선언(JSON)과 실행(JS)을 분리하고, 우선순위 숫자 하나로 복잡한 any/all/none 조합을 판정하는" 설계는 규칙 엔진(rule engine) 일반을 공부하는 좋은 실물 예제다.
• 다른 접근성 도구를 만들거나 비교 평가하는 사람 — Lighthouse가 왜 이 엔진을 가져다 쓰는지, "완전 자동화의 한계(57%)"를 어떻게 설계로 인정하고 있는지 확인할 수 있다.

반대로, 단순히 "우리 사이트 접근성 검사만 한 번 돌려보고 싶다"면 이 저장소 소스를 직접 읽을 필요 없이 @axe-core/playwright 같은 통합 라이브러리나 axe DevTools 브라우저 확장으로 충분하다. 이 문서는 "그 도구들 안에서 실제로 무슨 일이 벌어지는지" 궁금한 사람을 위한 것이다.