Gathering detailed insights and metrics for kayle
Gathering detailed insights and metrics for kayle
Installations
npm install kayleDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Releases
9
Languages
4
TypeScript
Rust
JavaScript
HTML
TypeScript (93.47%)
Rust (6.19%)
JavaScript (0.33%)
HTML (0.02%)
Developer
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
32 Stars
331 Commits
6 Forks
4 Watchers
2 Branches
1 Contributors
Updated on Jun 25, 2025
Maintainers
1
Package Meta Information
Latest Version
0.8.64
Package Id
kayle@0.8.64
Unpacked Size
7.76 MB
Size
1.22 MB
File Count
423
Published on
Mar 21, 2025
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
kayle
A fast and accurate web accessibility engine.
- Leading in performance
- Asynchronous design
- Tested and correct
- Extensive production use
- Jampacked with features for accessibility testing
- Works with headless browsers like (playwright and puppeteer) or raw markup
Getting Started
Install your browser automation lib playwright or puppeteer.
1# npm i puppeteer or npm i playwright 2npm install kayle --save
1import { kayle } from "kayle"; 2 3// Playwright 🎭 or Puppeteer 🤖 4const page = await browser.newPage(); 5 6// audit with a url or raw html 7const results = await kayle({ 8 page, 9 browser, 10 runners: ["htmlcs"] // options are "htmlcs" and "axe". The order is from fastest to slowest. Defaults to htmlcs. 11 origin: "https://a11ywatch.com", 12 // html: "<html>...</html>" 13});
It is recommended to use htmlcs as the runner or simply not declare a runner for the default.
We did a massive rewrite on htmlcs and it is extremely fast and stable.
When passing raw html try to also include the origin or the url, this sets window.origin and helps scripts that rely on it to work correctly or else relatives scripts will not work since the relative path does not exist on the local machine.
If you need to run a full site-wide crawl import autoKayle which uses Rust/Wasm to gather the links fast.
1import { autoKayle, setLogging } from "kayle"; 2import { chromium } from "playwright"; 3 4// enable kayle log output 5setLogging(true); 6 7const browser = await chromium.launch({ headless: true }); 8const page = await browser.newPage(); 9 10// crawls are continued to the next page automatically fast! 11const results = await autoKayle({ 12 page, 13 browser, 14 includeWarnings: true, 15 origin: "https://a11ywatch.com", 16 waitUntil: "domcontentloaded", 17 cb: function callback(result) { 18 console.log(result); 19 }, 20});
1# Output of time between runners with a realistic run - Rust/WASM is in the making and not yet ready. 2# Measurement is only calculated from the runner and not the extra latency to get the page initially. View the `innate` test to see more detals. 3 4# puppeteer - speed is stable across most versions 5# Rust/WASM 10.863582968711853 6# FAST_HTMLCS 29.915208011865616 7# FAST_AXE 162.87204200029373 8 9# playwright - the speed depends on the version 10# Rust/WASM TIME 10.163457989692688 11# FAST_HTMLCS TIME 33.50962498784065 12# FAST_AXE TIME 203.2565419971943
CLI
If you need to use kayle in the CI or shell use kayle CLI.
1npm install kayle_cli 2# configure the engine defaults. 3kayle_cli --automation-lib puppeteer --standard wcag2aa configure 4# install the deps for the runner. 5kayle_cli install 6# audit a website url. 7kayle_cli https://www.somewebsite.com
Clips
You can include base64 images with the audits to get a visual of the exact location of the issue.
1const results = await kayle({ 2 page, 3 browser, 4 includeWarnings: true, 5 origin: "https://www.drake.com", 6 waitUntil: "domcontentloaded", 7 allowImages: true, 8 clip: true, // get the clip cords to display in browser. Use clipDir or clip2Base64 to convert to image. 9 clipDir: "./_data/drake.com", // optional: directory to store the clip as an image. 10 clip2Base64: true, // optional: attach a base64 property of the clip 11});
Runners
kayle supports multiple test runners which return different results. The built-in test runners are:
fast_axecore: run tests using fork of axe-core.fast_htmlcs: run tests using fork of HTML CodeSniffer.kayle: run tests using the incomplete Rust/wasm Kayle Innate.custom: custom runners usinginjectRunnerutil - library authors.
Linting
Straight forward linting without a browser. You can pass a url or valid html. Linting is handled on the same machine not sandboxed. You also need to install jsdom before hand ex: yarn add jsdom.
1import { kayleLint } from "kayle/build/lint"; 2 3await kayleLint("https://a11ywatch.com");
Configuration
The extraConfigs object has the following:
1type RunnerConfig = { 2 browser: Partial<Browser>; 3 page: Partial<Page>; 4 // a custom cdp session. Useful for playwright persisting sessions. 5 cdpSession?: Partial<CDPSession>; 6 // configure if you know how the page will operate headless. 7 waitUntil?: LifeCycleEvent; 8 // actions to perform. 9 actions?: string[]; 10 // ignore list of elements using css selectors. 11 hideElements?: string; 12 // ignore test cases WCAG. 13 ignore?: string[]; 14 // include notices in results. 15 includeNotices?: boolean; 16 // include warnings in results. 17 includeWarnings?: boolean; 18 // the root element to test. 19 rootElement?: string; 20 // only allow WCAG RULES. 21 rules?: string[]; 22 // axe or htmlcs - the forks. 23 runners?: ("axe" | "htmlcs")[]; 24 // the accessibility standard. 25 standard?: Standard; 26 // stop test that go beyond time. 27 timeout?: number; 28 // allow capturing the image visually to base64 29 clip?: boolean; 30 // store clips to a directory must have allowImages set or CDP reset of intercepts 31 clipDir?: string; 32 // store a clip to base64 on the issue 33 clip2Base64?: boolean; 34 // allow images to render. 35 allowImages?: boolean; 36 // the website url: include this even with static html to fetch assets correct. 37 origin?: string; 38 // the langauge to use. 39 language?: string; 40};
Optional Features
- adblock - You can enable Brave's adblock engine with adblock-rs by installing
npm i adblock-rsto the project. This module needs to be manually installed and the env variableKAYLE_ADBLOCKneeds to be set totrue.
Localization
Locales supported by the runner using pre-compilition. In order to pre-compile the locales run yarn build. Some locales are only available in certain runners.
- da ("Danish")
- de ("German")
- es ("Spanish")
- ja ("Japanese")
- eu ("Basque")
- fr ("French")
- ar ("Arabic")
- ko ("Korean")
- he ("Hebrew")
- nl ("Dutch")
- no-NB ("Norwegian")
- pl ("Polish Poland")
- pt-BR ("Portuguese Brazil")
- zh-CN ("Chinese-Simplified")
- zh-TW ("Chinese-Traditional")
Browser Extension
If you want to compile a chrome extension for preloading scripts without needing to worry about bandwidth cost use the following to generate a custom extension to use.
First build the extension with the command:
yarn build:extension
Copy the contents into your directory to load using chromes --load-extension and enable the flag --extensions-on-chrome-urls.
View the extension-test for an example on how to setup chrome with the generated extension.
Currently we only have english support for extensions. We can add different locales for the generated scripts by manually adjusting the targets.
If you want to test the extension use yarn test:puppeteer:extension.
The kayle function also expects a field called browserExtension with the option set to true. Currently the extension handling is experimental reason for the name.
Extend Runner
Extending a runner and adding new rules can be done with the following at runtime.
1import { extendRunner, kayle } from "kayle"
2
3// pure javascript required. No typescript!
4 extendRunner(
5 MainRunner.htmlcs,
6 `
7 // store the prior sniff in a variable to re-use the logic
8 const prevHeadSniffCase = HTMLCS_WCAG2AAA_Sniffs_Principle2_Guideline2_4_2_4_2.process;
9
10 HTMLCS_WCAG2AAA_Sniffs_Principle2_Guideline2_4_2_4_2.process = (element, _) => {
11 // re-run the logic for the case
12 prevHeadSniffCase(element, _);
13 // we can write a test here that should pass some logic. For now we just add a new error
14 HTMLCS.addMessage(
15 HTMLCS.ERROR,
16 element,
17 HTMLCS.getTranslation("2_4_2_H25.1.NoHeadEl"),
18 "H25.1.NoHeadEl"
19 );
20 }
21
22 // Add a new rule example - 4_1_4_1_4
23
24 window["HTMLCS_WCAG2AAA_Sniffs_Principle4_Guideline4_1_4_1_4"] = {
25 register: () => ["html"],
26 process: (element, _) => {
27 console.log("NEW Rule run!");
28 HTMLCS.addMessage(
29 HTMLCS.ERROR,
30 element,
31 "This is some new rule for something.",
32 "H55.1.NoItem"
33 );
34 },
35 };
36
37 // push the new sniff to the list
38 HTMLCS_WCAG2AAA.sniffs.push("Principle4.Guideline4_1.4_1_4");
39 // register the new sniff rule to run
40 HTMLCS.registerSniff("WCAG2AAA", "Principle4.Guideline4_1.4_1_4");
41 `.trimStart());
42
43const results = await kayle({
44 page,
45 browser,
46 runners: ["htmlcs", "htmlcs_extended"]
47 origin: "https://a11ywatch.com",
48});Custom Runner (library authors)
Below is an example on adding a new custom runner. Take a look at HTMLCS and HTMLCS_Runner setup for an example of how to setup the scripts, it could take a bit of time to get familiar. You can also overwride the base runners by taking the runnersJavascript object and appending to the script.
1import { injectRunner, kayle } from "kayle" 2 3// example of the custom script 4injectRunner("htmlcs_extended", "./custom_htmlcs_script", "en") 5 6const results = await kayle({ 7 page, 8 browser, 9 runners: ["htmlcs", "htmlcs_extended"] 10 origin: "https://a11ywatch.com", 11});
Testing
For the comparison between using fast_htmlcs, fast_axecore, and the metrics for the 3rd party @axe-core/playwright.
yarn build:test
Checkout the playwright-example or puppeteer-example for more information.
Benchmarks
fast_htmlcsruns up to 110x base faster than HTML_CodeSniffer.fast_axecoreruns up to 2.5x - 15x base faster than the original axe by default and scales the larger the website.
Currently fast_htmlcs runs around 50x faster than axe-core and has several differences of handling the way issues are found. They both capture different cases and is best to used together which this library handles efficiently.
If you use @playwright/axe-core you can swap it out with the following playwright-axe-example and get an increase in issues found and major performance boost of at least 100%. You can also include multiple runners to extend the issues beyond the basics in folds.
Performance Tips
As we set the foundation to mark test cases that can pass and increase our target on automating accessibility we have a couple of layers that can make a major difference to the project. The following will save drastic time and money if done.
- Use a fast concurrent crawler to gather all of the html to send to a web accessibility service that can perform audits like pagemind over CDP.
- Use the pre-compiled browser extensions to avoid over the wire latency
yarn build:extension.
Developing
In order to develop you need yarn v2 installed for the workspace.
Run the following to install on ^node@18
corepack enable && corepack prepare yarn@stable --activate and reload shell after.
Use the command yarn build to compile all the scripts for each locale.
Discord
If you want to chat about the project checkout our Discord.
About
This project took Axecore and HTMLCS from versions that were complete and semi-stable. We patched and fixed a lot of bugs that increased the accuracy of tests passing and issues being found. One of the main goals was to have the audit run quickly since we noticed some of the tests would take several seconds to complete. Right now, the project is moving forward based on performance and accuracy for ensuring minimal false positives.
LICENSE
Check the license file in the root of each project.
No vulnerabilities found.
No security vulnerabilities found.