HTML CodeSniffer — Complete Guide

In this tutorial, you will learn about HTML CodeSniffer. We cover key concepts, practical examples, and best practices to help you master this topic.

HTML_CodeSniffer is a JavaScript-based Accessibility auditor that runs as a bookmarklet or included script, checking pages against WCAG standards and Section 508 with color-coded issue summaries and detailed explanations.

What You'll Learn

You will use HTML_CodeSniffer as a bookmarklet for on-demand scanning, as a JavaScript library for custom integration, and interpret its color-coded results for WCAG A, AA, and AAA Compliance.

Why It Matters

HTML_CodeSniffer requires no installation -- just a bookmarklet click. It runs entirely in the browser without server requests, making it ideal for quick checks on any page including localhost and file:// URLs.

Real-World Use

A developer working on a local HTML file wants to check accessibility before committing. They click the HTML_CodeSniffer bookmarklet, review the 5 issues found, fix them, and commit with confidence that no obvious issues remain.

CodeSniffer Workflow

flowchart TD
  A[Load Page] --> B[Click Bookmarklet]
  B --> C[CodeSniffer Panel Opens]
  C --> D[Select Standard]
  D --> E[Run Audit]
  E --> F[Review Issues]
  F --> G[Click Issue to Highlight]
  G --> H[Fix in Code]
  H --> I[Re-run Audit]

Using HTML_CodeSniffer

Add the bookmarklet from the HTML_CodeSniffer website to your browser bookmarks bar. Click it on any page to open the audit panel.

<!-- Including HTML_CodeSniffer in a page -->
<script src="HTMLCS.js"></script>
<script>
  HTMLCS_RUNNER.run('WCAG2AA');
</script>

// Using HTML_CodeSniffer programmatically
HTMLCS_RUNNER.run('WCAG2AA');

// After audit completes, results are available via callback
HTMLCS.on('audit-complete', function(results) {
  console.log('Errors:', HTMLCS.getMessages().filter(m => m.type === HTMLCS.ERROR));
  console.log('Warnings:', HTMLCS.getMessages().filter(m => m.type === HTMLCS.WARNING));
});

<!-- HTML_CodeSniffer checks these patterns -->
<a href="#" onclick="return false;">Link without href</a>
<button>Submit</button>
<label>Name <input type="text"></label>

The bookmarklet panel shows messages grouped by severity: red for errors, yellow for warnings, blue for notices.

Common Mistakes

• Forgetting to select the correct WCAG standard before running
• Not scrolling to reveal all content before scanning
• Using the bookmarklet on pages with strict CSP headers
• Ignoring warnings and only fixing errors
• Not re-running after fixing issues
• Using only HTML_CodeSniffer without other automated tools
• Not reading the detailed description for each issue

Practice and Challenge

Practice 1: Add the HTML_CodeSniffer bookmarklet and scan a page. Practice 2: Filter results to show only errors (not warnings). Practice 3: Fix one error found and re-scan to confirm. Practice 4: Run with WCAG2A and WCAG2AA and compare results. Practice 5: Use the programmatic API to log results to console.

Challenge: Write a userscript that automatically runs HTML_CodeSniffer on every page load during development and logs the error count to the browser console with a timestamp.

FAQ

Mini Project

Create a browser bookmarklet collection with HTML_CodeSniffer, axe-core, and WAVE. For each tool, document which types of issues it catches best. Test all three on the same page and create a Venn diagram of overlapping and unique issues.

What's Next

Manual Testing covers the manual testing Process for accessibility validation.