Aria-Ease - Aria-Ease is an accessibility engineering infrastructure

The Problem Static accessibility tools can detect missing ARIA attributes. But they cannot verify whether interactive components actually behave correctly. A combobox can have the correct roles and attributes and still be unusable with a keyboard. That gap forced me to rethink how accessibility interaction testing should work. A Personal Journey I had just finished refactoring the header navigation on the Aria-Ease documentation website. New layout, cleaner marker, better CSS. I rewrote the search component as a combobox with autosuggestions, powered by the Aria-Ease combobox utility. On the surface, it worked. You could tab into it, type a keyword, receive real-time suggestions, and select from a list of options. It looked like a textbook header search component. Then came the hardest part: how do I verify, yet again, that a component that implements a WAI-ARIA pattern actually behaves like that pattern under real user interaction? To understand why that was a dilemma, here is a little backstory. Aria-Ease started as a component library after I took part in a hackathon and saw firsthand why developers and teams push accessibility, especially interaction accessibility, to the back burner. Let’s face it, building custom WAI-ARIA patterns is not an easy task. It requires reading the WAI-ARIA APG specs thoroughly, interpreting ambiguous sections, and translating those requirements into robust utilities. This is how every Aria-Ease utility is engineered. First I implement the utility. Then I write unit tests to ensure the utility works. Once those pass, I build a real component with it. But that’s only half the job. I still needed a way to verify that the component works in a real browser environment with real DOM structure, CSS that might hide elements, event bubbling and capturing, dynamic content loading, and actual browser focus behaviour. That quickly became a treadmill: component utility → unit test → real component → integration test → rewrite integration test whenever DOM structure changed. The Epiphany “Can I test WAI-ARIA APG specifications automatically and independent of DOM structure?”. That question led to the birth of component contract testing. I realized the WAI-ARIA APG isn't just a document; it's a machine-readable specification waiting to be parsed. Every 'When X happens, Y should occur' statement is an executable test waiting to be written. The next step was the answer to these questions: 1. What if I encode APG behavior into machine-readable JSON contracts? 2. What if contracts stay agnostic to DOM structure and implementation details? 3. What if a robust runner reads the contracts, executes actions, and validates expected outcomes? The result: - Refactor DOM? Tests still pass - Change CSS classes? Tests still pass - Switch frameworks? Tests still pass To put that in perspective, here’s a comparison of what shifted in the way I now test: - Traditional Integration Test: Find .search-button, click it, check if .dropdown has class .is-active. - Aria-Ease Contract Test: Find the element with role="combobox", send ArrowDown event, verify that the element with role="listbox" is visible. Contract testing validates that your implementation conforms to an external specification (the "contract"). In ARIA, the contract is the WAI-ARIA Authoring Practices Guide.