A modular, extensible accessibility testing engine for WCAG compliance. Built as a modern alternative to axe-core with first-class support for Bun.js.

Features

🚀 Fast Performance - Optimized for Bun.js with parallel rule execution
📦 Modular Architecture - Easy to extend with custom rules and rulesets
🎯 WCAG 2.2 Complete - Full coverage of A, AA, and AAA standards (50+ rules)
🔧 Flexible Configuration - Run specific rulesets or individual rules
📊 Detailed Reporting - Comprehensive results with actionable feedback
💬 Plain English Explanations - Every rule includes non-technical explanations
🌐 Browser & Node Compatible - Works in any JavaScript environment
📝 TypeScript Support - Full type definitions included
🖥️ CLI Tool - Command-line interface for easy testing

Installation

bun add @helptheweb/accessibility-engine

Or with npm:

npm install @helptheweb/accessibility-engine

Quick Start

JavaScript API

import createAccessibilityEngine from '@helptheweb/accessibility-engine';

// Create engine instance
const engine = createAccessibilityEngine();

// Run accessibility tests
const results = await engine.run();

// Check for violations
if (results.violations.length > 0) {
  console.log('Accessibility violations found:', results.violations);
}

Command Line Interface

# Test a URL
helptheweb test https://example.com

# Test a local HTML file
helptheweb test index.html

# Output results to a file
helptheweb test https://example.com --output report.html --format html

# Run only Level A tests
helptheweb test https://example.com --ruleset wcag22a

# Show detailed results
helptheweb test https://example.com --verbose

# List all available rules
helptheweb list

# Explain a specific rule
helptheweb explain img-alt

Configuration Options

const engine = createAccessibilityEngine({
  // Run only specific WCAG levels
  runOnly: ['wcag22a', 'wcag22aa'],
  
  // Choose result types to include
  resultTypes: ['violations', 'incomplete'],
  
  // Custom reporter version
  reporter: 'v2'
});

Running Tests on Specific Elements

// Test a specific form
const form = document.querySelector('#signup-form');
const results = await engine.run(form);

// Test with callback
engine.run(document, (error, results) => {
  if (error) {
    console.error('Error:', error);
  } else {
    console.log('Results:', results);
  }
});

Understanding the Results

Every rule includes a plain English explanation to help non-technical users understand accessibility issues:

{
  id: 'img-alt',
  help: 'Images must have an alt attribute',
  explanation: 'Images need text descriptions so screen reader users know what the image shows. Think of it like describing a photo to someone over the phone.',
  // ... rest of the violation details
}

Available Rulesets

wcag22a - WCAG 2.2 Level A rules (essential accessibility)
wcag22aa - WCAG 2.2 Level A and AA rules (recommended standard)
wcag22aaa - All WCAG 2.2 rules (highest standard)

WCAG 2.2 Rules Coverage

Perceivable (Principle 1)

✅ Non-text Content (1.1.1)
✅ Audio & Video Captions (1.2.x)
✅ Info and Relationships (1.3.1)
✅ Meaningful Sequence (1.3.2)
✅ Sensory Characteristics (1.3.3)
✅ Orientation (1.3.4)
✅ Identify Input Purpose (1.3.5)
✅ Use of Color (1.4.1)
✅ Audio Control (1.4.2)
✅ Contrast (1.4.3)
✅ Resize Text (1.4.4)
✅ Images of Text (1.4.5)
✅ Reflow (1.4.10)
✅ Non-text Contrast (1.4.11)
✅ Text Spacing (1.4.12)
✅ Content on Hover/Focus (1.4.13)

Operable (Principle 2)

✅ Keyboard Accessible (2.1.1)
✅ No Keyboard Trap (2.1.2)
✅ Character Key Shortcuts (2.1.4)
✅ Timing Adjustable (2.2.1)
✅ Pause, Stop, Hide (2.2.2)
✅ Three Flashes (2.3.1)
✅ Bypass Blocks (2.4.1)
✅ Page Titled (2.4.2)
✅ Focus Order (2.4.3)
✅ Link Purpose (2.4.4)
✅ Multiple Ways (2.4.5)
✅ Headings and Labels (2.4.6)
✅ Focus Visible (2.4.7)
✅ Focus Not Obscured (2.4.11) New in 2.2
✅ Pointer Gestures (2.5.1)
✅ Pointer Cancellation (2.5.2)
✅ Label in Name (2.5.3)
✅ Motion Actuation (2.5.4)
✅ Dragging Movements (2.5.7) New in 2.2
✅ Target Size (2.5.8) New in 2.2

Understandable (Principle 3)

✅ Language of Page (3.1.1)
✅ Language of Parts (3.1.2)
✅ On Focus (3.2.1)
✅ On Input (3.2.2)
✅ Consistent Navigation (3.2.3)
✅ Consistent Identification (3.2.4)
✅ Consistent Help (3.2.6) New in 2.2
✅ Error Identification (3.3.1)
✅ Labels or Instructions (3.3.2)
✅ Error Suggestion (3.3.3)
✅ Error Prevention (3.3.4)
✅ Redundant Entry (3.3.7) New in 2.2
✅ Accessible Authentication (3.3.8) New in 2.2

Robust (Principle 4)

✅ Parsing (4.1.1)
✅ Name, Role, Value (4.1.2)
✅ Status Messages (4.1.3)

TypeScript Support

Full TypeScript definitions are included:

import createAccessibilityEngine, { 
  AccessibilityEngine, 
  Report, 
  Rule, 
  EngineOptions 
} from '@helptheweb/accessibility-engine';

const engine: AccessibilityEngine = createAccessibilityEngine({
  runOnly: ['wcag22a']
});

const results: Report = await engine.run();

Extending the Engine

Adding Custom Rules

const customRule = {
  id: 'custom-rule',
  selector: '.my-component',
  tags: ['custom'],
  impact: 'moderate',
  description: 'Custom components must follow guidelines',
  help: 'Ensure custom components are accessible',
  explanation: 'Your custom widgets need to work for everyone, including people using screen readers or keyboards.',
  helpUrl: 'https://example.com/docs/custom-rule',
  evaluate: (element) => {
    // Your test logic here
    return {
      passed: true,
      message: null
    };
  }
};

engine.registerRule(customRule);

Creating Custom Rulesets

engine.registerRuleset('custom-rules', ['custom-rule', 'another-rule']);

// Run only custom rules
const results = await engine.run(document, {
  runOnly: 'custom-rules'
});

CLI Output Formats

Text (default)

Colored terminal output with summaries and details

JSON

Machine-readable format for CI/CD pipelines

HTML

Beautiful report with charts and detailed findings

CSV

Spreadsheet-compatible format for tracking

API Endpoint Integration

The engine is designed to work seamlessly with API endpoints:

// Example API endpoint
app.post('/api/accessibility/test', async (req, res) => {
  const { html, options } = req.body;
  
  // Create DOM from HTML string
  const dom = new JSDOM(html);
  const document = dom.window.document;
  
  const engine = createAccessibilityEngine(options);
  const results = await engine.run(document);
  
  res.json(results);
});

Development

# Install dependencies
bun install

# Run tests
bun test

# Build for production
bun run build

# Lint code
bun run lint

# Test CLI locally
bun run cli test https://example.com

Performance

The engine is optimized for speed:

Parallel rule execution
Efficient DOM traversal
Minimal dependencies
Bun.js optimizations

Typical performance:

Small page (<100 elements): ~50ms
Medium page (~1000 elements): ~200ms
Large page (>5000 elements): ~1s

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT License - see LICENSE file for details.

Roadmap

Credits

Built with ❤️ for the HelpTheWeb.org project.

Support

📧 Email: support@helptheweb.org
💬 Discord: Join our community
📚 Docs: Full documentation
🐛 Issues: GitHub Issues

Keywords

FAQs

What is @helptheweb/accessibility-engine?

Is @helptheweb/accessibility-engine well maintained?

Package last updated on 25 Jun 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@helptheweb/accessibility-engine