{"canonical_url":"https://engineer.company/glossary/axe/","content_markdown":"# axe\n\n## What it is\n\naxe, published as the open-source JavaScript library axe-core, is a set of automated accessibility\nrules that runs inside a web page, inspects what the browser has rendered, and reports each element\nthat breaks one of those rules. Deque Systems, an accessibility company, maintains it under the\nMozilla Public License 2.0. Other tools build on it: the accessibility category in Chrome's\nLighthouse weights its audits by axe's impact ratings, and Playwright's own guide to accessibility\ntesting runs axe through a small companion package.\n\nThe engine is a single script. A test runner or a browser extension loads it into the page under\ntest and calls `axe.run`, and the engine walks the document, including nested frames and shadow DOM,\napplying every rule whose conditions match. Because it reads the page after the browser has laid it\nout, it can check things the source alone does not show: whether text is visible, which colour it\nsits on, whether an element is hidden. That is also why some rules need a real browser. The project\nsays that its colour-contrast rule does not work in JSDOM, the simulated document that many\nunit-test setups use.\n\nEach rule carries tags. One of them says which WCAG version and level the rule belongs to, such as\n`wcag2a`, `wcag2aa`, `wcag21aa` or `wcag22aa`, or marks it `best-practice` when no success criterion\nrequires it. Other tags tie rules to EN 301 549, Section 508 or the W3C's conformance testing rules.\nThe tags are how a team decides what a run checks.\n\nWhat comes back is not a single pass or fail but four lists:\n\n- `violations`: elements that failed a rule, each with an impact rated minor, moderate, serious or\n  critical, a short summary of how to fix it, and a link to a longer explanation.\n- `passes`: elements that passed, which is how a team can see that a rule actually ran.\n- `incomplete`, which the documentation also calls “needs review”: elements the engine could neither\n  pass nor fail with certainty, and which a person has to look at.\n- `inapplicable`: rules that had nothing to test, such as the video rules on a page without video.\n\n## Why it matters\n\nThe decision axe serves is which parts of accessibility a team hands to a machine, and whether a\nfailure should stop a release. Two properties make it suited to that job. It is cheap to run, so it\ncan check every build instead of one audit a year. And its makers' stated aim is zero false\npositives, bugs aside: anything the engine is unsure of goes to the review list rather than the\nviolations list. A check that cries wolf gets switched off; one that only reports what it can prove\ncan fail a build without anyone resenting it.\n\nThe limit is coverage. Deque says axe-core finds on average 57 percent of WCAG issues automatically and returns uncertain results for manual review. The figure describes issues found, not the share of success criteria a machine can assess.\n\nWhat stays out of reach is mostly judgement. axe can confirm that an image has alternative text,\nthat a button has a name and that a form field has a label. It cannot tell whether the text\ndescribes the image, whether the name says what the button does, or whether the page makes sense\nwhen it is read aloud in order. Those questions need a person with a screen reader and a keyboard,\nand the time a machine saves on the mechanical checks is time that person can spend on them.\n\nThe choice of tags is a trade-off of its own. Running only the WCAG-tagged rules gives a result that\nmaps cleanly to a conformance claim, and to nothing else. Adding the best-practice rules catches\nproblems that WCAG does not name but users still meet, such as content sitting outside every\nlandmark or a page with no top-level heading. The cost is a few failures that no conformance audit\nwould cite.\n\n## What it looks like in practice\n\nTwo pages on this site show what the engine is trusted with.\n\nIn one platform's test suite it sits beside four layers of tests, and\n[an axe-core gate asserts zero WCAG 2.0 and 2.1 A and AA violations](/portfolio/built-a-test-suite-across-go-sql-and-browser/),\nwhich turns accessibility into a build failure rather than an audit finding months later. The point\nis timing: a defect that fails the build is fixed by the person who just wrote it, while the change\nis still open.\n\nOn this site, the [credits page](/credits/) describes the engine auditing a set of representative\npages, one per template in every language, against WCAG 2.2 A and AA in both colour schemes, as part\nof the gate rather than as a report beside it. Running in both colour schemes means a contrast\nfailure that appears only in the dark scheme can still stop the build. Sampling one page per\ntemplate relies on pages built from the same template sharing their structure, which is what let 38\npages stand in for a site of 2,268 in October 2026. Automated rules do not cover every judgement WCAG requires, which is why the site keeps its record per success criterion rather than as a pass mark.\n\n## Where it goes wrong\n\nMost axe failures are failures of trust: a run that checked less than it seemed to, or a result read\nas more than it says.\n\n**A tag list leaves rules out.** Tags are not cumulative. `wcag2aa` holds only the rules for level\nAA criteria in WCAG 2.0, so a run limited to it skips every level A rule, and the API documentation\nsays outright that both `wcag2a` and `wcag2aa` are needed. In the same way, `wcag21aa` holds only\nrules for criteria that 2.1 added, and a run limited to WCAG tags never executes a `best-practice`\nrule. The rule descriptions list the WCAG 2.2 rules as disabled by default, so a run given no tags\nleaves them out; naming their tag turns them on. Name every tag the run should cover, and keep the\nlist beside the claim it supports:\n\n```js\nconst results = await axe.run(document, {\n    runOnly: {\n        type: \"tag\",\n        values: [\"wcag2a\", \"wcag2aa\", \"wcag21a\", \"wcag21aa\", \"wcag22aa\"],\n    },\n});\n```\n\nA rule that appears in none of the four lists did not run at all, so read the lists once whenever\nthe configuration changes.\n\n**A clean run is read as an accessible page.** Zero violations means that the rules which ran could\nprove no failure. It says nothing about whether the alternative text is right, whether focus moves\nin a sensible order, or whether someone using a screen reader can finish the task. Treat the run as\nthe floor, and schedule the checks it cannot make.\n\n**The review list is dropped.** A gate that fails on violations alone lets the `incomplete` results\nthrough without anyone seeing them. Those are the elements the engine looked at and left undecided,\nwhich makes them the cases most in need of a person. Send them to someone who will read them, or\nfail the build on them too.\n\n**The page is tested in one state.** The engine checks what is rendered at the moment it runs. A\nclosed menu, an unopened dialog, an error message that appears only after a bad submission, and the\nother colour scheme are all outside a run against the page as it first loads. Drive the page into\neach state that matters, and run the engine again in each one.\n\n**The engine runs where nothing is drawn.** A simulated document has no layout and no computed\ncolour, and the project lists colour contrast as a rule that does not work there. Unit tests with\naxe still catch structural problems; contrast and anything else visual belong in a real browser.\n\n**A rule is switched off to get a release out.** Disabling a rule for the whole run because one\ncomponent trips it hides that rule's failures everywhere else, including in pages written later.\nExclude the one element instead, with a note saying why and when the exclusion should go.\n\n## Further reading\n\n- [axe-core](https://github.com/dequelabs/axe-core) — the engine's source, its stated principles and\n  the list of supported browsers.\n- [Rule Descriptions](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) —\n  every rule with its impact and tags, grouped by WCAG version, best practice, AAA, experimental and\n  deprecated.\n- [axe-core API](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md) — the tags, the\n  `runOnly` option, how to include or exclude parts of a page, and the shape of the four result\n  lists.\n- [Accessibility testing](https://playwright.dev/docs/accessibility-testing) — Playwright's guide to\n  running axe inside browser tests, including scanning a page after interacting with it.\n\n\u003chttps://engineer.company/glossary/axe/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How the axe rule engine tests a rendered page, what its four lists of results mean, and why a clean run is a floor rather than a verdict.","formats":{"gemtext":"https://engineer.company/glossary/axe/index.gmi","gopher":"https://engineer.company/glossary/axe/gophermap","html":"https://engineer.company/glossary/axe/","json":"https://engineer.company/glossary/axe/index.json","markdown":"https://engineer.company/glossary/axe/index.md","pdf":"https://engineer.company/glossary/axe/index.pdf"},"kind":"page","language":"en","title":"What is axe?","url":"https://engineer.company/glossary/axe/","version":1}