<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Alberto Vilano Reyna</title>
    <description>The latest articles on DEV Community by Alberto Vilano Reyna (@avilano).</description>
    <link>https://dev.to/avilano</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4243196%2Fbde6f56c-0d89-428a-ab82-ae93b327edc7.png</url>
      <title>DEV Community: Alberto Vilano Reyna</title>
      <link>https://dev.to/avilano</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/avilano"/>
    <language>en</language>
    <item>
      <title>How I Stopped Cursor from Writing Flaky Playwright Tests</title>
      <dc:creator>Alberto Vilano Reyna</dc:creator>
      <pubDate>Thu, 19 Nov 2026 22:45:43 +0000</pubDate>
      <link>https://dev.to/avilano/how-i-stopped-cursor-from-writing-flaky-playwright-tests-23k0</link>
      <guid>https://dev.to/avilano/how-i-stopped-cursor-from-writing-flaky-playwright-tests-23k0</guid>
      <description>&lt;p&gt;AI coding assistants like &lt;strong&gt;Cursor&lt;/strong&gt; and &lt;strong&gt;Claude&lt;/strong&gt; have radically accelerated initial feature development. But when developers prompt an LLM with &lt;em&gt;"Write an end-to-end test for our checkout flow"&lt;/em&gt;, the AI almost universally outputs &lt;strong&gt;test automation anti-patterns&lt;/strong&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Brittle CSS hierarchy selectors: &lt;code&gt;page.locator('div.container &amp;gt; form &amp;gt; div:nth-child(2) &amp;gt; input')&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Non-deterministic sleep statements: &lt;code&gt;await page.waitForTimeout(5000)&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Fragile XPath locators that break the second a UI style changes.&lt;/li&gt;
&lt;li&gt;Monolithic 200-line test scripts with zero Page Object Model encapsulation.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The result? The team ships 50 tests in an afternoon, and spends the next six months debugging CI failures.&lt;/p&gt;

&lt;p&gt;Here is the exact &lt;strong&gt;Cursor Rules (&lt;code&gt;.cursor/rules/*.mdc&lt;/code&gt;)&lt;/strong&gt; architecture we enforce to make AI assistants generate rock-solid, deterministic Playwright suites on the first prompt.&lt;/p&gt;




&lt;h2&gt;
  
  
  1. The Core Problem: LLMs Default to Visual DOM Scraping
&lt;/h2&gt;

&lt;p&gt;LLMs trained on public GitHub repositories have ingested a decade of legacy Selenium and Puppeteer scripts. Unless you constrain them with deterministic system rules, they will default to 2018 testing practices.&lt;/p&gt;

&lt;p&gt;To produce maintainable test suites, an AI assistant must be strictly instructed to interact with the application &lt;strong&gt;through the browser's Accessibility Tree&lt;/strong&gt;, exactly like a real user or assistive screen reader.&lt;/p&gt;




&lt;h2&gt;
  
  
  2. The Production Cursor Rule (&lt;code&gt;.cursor/rules/playwright-standards.mdc&lt;/code&gt;)
&lt;/h2&gt;

&lt;p&gt;Create this file in your project repository under &lt;code&gt;.cursor/rules/playwright-standards.mdc&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;---
description: Enforces deterministic Playwright standards, POM architecture, and WCAG accessibility
globs: tests/&lt;span class="gs"&gt;**/*.ts, src/pages/**&lt;/span&gt;/*.page.ts
alwaysApply: false
---

&lt;span class="gu"&gt;# Playwright Test Standards &amp;amp; Architecture
&lt;/span&gt;
You are a Senior SDET and AI Quality Engineer. When writing or refactoring Playwright tests, you MUST strictly adhere to the following rules:

&lt;span class="gu"&gt;## 1. Locator Priority Hierarchy (Accessibility First)
&lt;/span&gt;Never use XPath or brittle CSS selectors (&lt;span class="sb"&gt;`div &amp;gt; span`&lt;/span&gt;, classes, or IDs). Always query through user-facing accessibility semantics in this exact priority:
1. &lt;span class="sb"&gt;`page.getByRole('button', { name: /save changes/i })`&lt;/span&gt;
2. &lt;span class="sb"&gt;`page.getByLabel('Work Email')`&lt;/span&gt;
3. &lt;span class="sb"&gt;`page.getByPlaceholder('name@company.com')`&lt;/span&gt;
4. &lt;span class="sb"&gt;`page.getByText('Success')`&lt;/span&gt;
5. &lt;span class="sb"&gt;`page.getByTestId('checkout-summary')`&lt;/span&gt; (ONLY when semantic roles cannot apply)

&lt;span class="gu"&gt;## 2. Zero-Tolerance for Arbitrary Sleeps
&lt;/span&gt;&lt;span class="k"&gt;- &lt;/span&gt;BANNED: &lt;span class="sb"&gt;`page.waitForTimeout()`&lt;/span&gt; or &lt;span class="sb"&gt;`setTimeout()`&lt;/span&gt;.
&lt;span class="k"&gt;- &lt;/span&gt;REQUIRED: Use Playwright's built-in web-first assertions (&lt;span class="sb"&gt;`expect(locator).toBeVisible()`&lt;/span&gt;, &lt;span class="sb"&gt;`expect(locator).toHaveText()`&lt;/span&gt;). Let Playwright's auto-retrying mechanism handle microtask reconciliation.

&lt;span class="gu"&gt;## 3. Strict Page Object Model (POM)
&lt;/span&gt;&lt;span class="k"&gt;- &lt;/span&gt;Tests (&lt;span class="sb"&gt;`tests/**/*.spec.ts`&lt;/span&gt;) must NEVER invoke raw locators directly.
&lt;span class="k"&gt;- &lt;/span&gt;All DOM queries and UI interactions must be encapsulated inside Page Objects (&lt;span class="sb"&gt;`src/pages/*.page.ts`&lt;/span&gt;).
&lt;span class="k"&gt;- &lt;/span&gt;Method names must represent user intent (&lt;span class="sb"&gt;`checkoutPage.submitPayment()`&lt;/span&gt;), not implementation details.

&lt;span class="gu"&gt;## 4. Accessibility Testing Integration
&lt;/span&gt;&lt;span class="k"&gt;- &lt;/span&gt;Every critical user flow must execute &lt;span class="sb"&gt;`@axe-core/playwright`&lt;/span&gt; validation with &lt;span class="sb"&gt;`axe.include()`&lt;/span&gt;.
&lt;span class="k"&gt;- &lt;/span&gt;Keyboard navigation must verify focus trapping on modals and &lt;span class="sb"&gt;`Escape`&lt;/span&gt; key restoration.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  3. The Before and After
&lt;/h2&gt;

&lt;h3&gt;
  
  
  ❌ What Cursor Generates Without Rules:
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'user logs in'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;goto&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'https://app.com/login'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;locator&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'#email_input_field'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fill&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'user@test.com'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;locator&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'input[type="password"]'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fill&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'secret'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;click&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'.btn-primary-blue'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;waitForTimeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;4000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;locator&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'.dashboard-title'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;innerText&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'Dashboard'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  ✅ What Cursor Generates With the Rule Enabled:
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;test&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;expect&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'../fixtures/base.fixture'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;LoginPage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'../pages/login.page'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;DashboardPage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'../pages/dashboard.page'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'user authenticates and arrives at dashboard'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;loginPage&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;LoginPage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;dashboardPage&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;DashboardPage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;loginPage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;navigate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;loginPage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;login&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'user@test.com'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'secret'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dashboardPage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;heading&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBeVisible&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;loginPage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;checkAccessibility&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  4. Takeaway
&lt;/h2&gt;

&lt;p&gt;AI isn't bad at writing tests; it is bad at &lt;strong&gt;guessing your architectural standards&lt;/strong&gt;. &lt;/p&gt;

&lt;p&gt;By pinning your AI coding assistant to explicit rules, your team can generate high-velocity tests that actually run green in CI for years.&lt;/p&gt;




&lt;p&gt;&lt;strong&gt;Quick question for the comments:&lt;/strong&gt; What is the worst AI-generated selector or sleep anti-pattern you have caught in a PR recently?&lt;/p&gt;




&lt;h3&gt;
  
  
  Ready-to-Use Toolkit: Deterministic Playwright AI Rules &amp;amp; Guardrails ($29)
&lt;/h3&gt;

&lt;p&gt;Skip the boilerplate and grab the production-ready kit (PDF guide, templates, and CI guardrails):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://buy.polar.sh/polar_cl_D8E10dvjjzbuFgwdN5NwnuTyEeYCGJkI1PJX71HNeAE" rel="noopener noreferrer"&gt;Get Deterministic Playwright AI Rules &amp;amp; Guardrails ($29)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://avilano.dev/products" rel="noopener noreferrer"&gt;Browse all 5 QA, A11y &amp;amp; AI Kits ($69 Bundle)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://avilano.dev/blog/cursor-rules-for-deterministic-playwright-tests" rel="noopener noreferrer"&gt;avilano.dev&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>playwright</category>
      <category>ai</category>
      <category>testing</category>
      <category>webdev</category>
    </item>
    <item>
      <title>The 2026 ADA Title II &amp; HHS 504 Deadline: An Engineer's Guide to Automated WCAG 2.1 AA in CI</title>
      <dc:creator>Alberto Vilano Reyna</dc:creator>
      <pubDate>Fri, 13 Nov 2026 16:28:10 +0000</pubDate>
      <link>https://dev.to/avilano/the-2026-ada-title-ii-hhs-504-deadline-an-engineers-guide-to-automated-wcag-21-aa-in-ci-1lph</link>
      <guid>https://dev.to/avilano/the-2026-ada-title-ii-hhs-504-deadline-an-engineers-guide-to-automated-wcag-21-aa-in-ci-1lph</guid>
      <description>&lt;p&gt;If your engineering organization builds digital platforms for public entities, healthcare (HHS Section 504), higher education, or government contractors, the regulatory window has officially closed.&lt;/p&gt;

&lt;p&gt;The U.S. Department of Justice (DOJ) under ADA Title II and the Department of Health and Human Services (HHS) have codified &lt;strong&gt;WCAG 2.1 Level AA&lt;/strong&gt; as the legally enforceable standard for web and mobile applications, with strict deadlines landing in &lt;strong&gt;2026&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Most engineering leaders mistakenly believe installing an axe linter or a third-party overlay widget makes them compliant. &lt;/p&gt;

&lt;p&gt;&lt;strong&gt;It does not.&lt;/strong&gt; In fact, digital accessibility lawsuits reached record highs over the past two years, with hundreds of lawsuits specifically naming websites using third-party overlay widgets.&lt;/p&gt;

&lt;p&gt;Here is the technical reality of true WCAG 2.1 AA compliance and how modern engineering teams automate it continuously in CI.&lt;/p&gt;




&lt;h2&gt;
  
  
  1. The 35% Trap: Why Axe-Core Isn't Enough
&lt;/h2&gt;

&lt;p&gt;Tools like &lt;code&gt;@axe-core/playwright&lt;/code&gt; or Lighthouse are essential baseline scanners. They immediately catch:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Missing image &lt;code&gt;alt&lt;/code&gt; attributes.&lt;/li&gt;
&lt;li&gt;Low color contrast ratios (under 4.5:1 for normal text).&lt;/li&gt;
&lt;li&gt;Duplicate IDs and missing form labels.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;However, &lt;strong&gt;automated static analysis can only detect roughly 30% to 40% of WCAG criteria&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The remaining 60%+ of accessibility barriers are &lt;strong&gt;dynamic interaction bugs&lt;/strong&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Can a motor-impaired user navigate the checkout funnel using only the &lt;code&gt;Tab&lt;/code&gt; and &lt;code&gt;Enter&lt;/code&gt; keys?&lt;/li&gt;
&lt;li&gt;When a modal opens, is keyboard focus trapped inside the dialog, or does it bleed into the background?&lt;/li&gt;
&lt;li&gt;When an async toast appears ("Card declined"), does an assistive screen reader announce it to a visually impaired user?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Axe-core will return zero violations on a modal that completely traps blind users with no way to exit.&lt;/p&gt;




&lt;h2&gt;
  
  
  2. Automating Keyboard Focus &amp;amp; W3C APG in Playwright
&lt;/h2&gt;

&lt;p&gt;To achieve defensible compliance, you must verify the &lt;strong&gt;W3C WAI-ARIA Authoring Practices Guide (APG)&lt;/strong&gt; keyboard design patterns.&lt;/p&gt;

&lt;p&gt;Here is an automated keyboard fixture that verifies focus trapping and modal escape restoration:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// tests/a11y/modal-focus-trap.spec.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;test&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;expect&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'@playwright/test'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'dialog strictly traps focus and restores focus on Escape'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;goto&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/pricing'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;triggerBtn&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByRole&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'button'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt; &lt;span class="n"&gt;enterprise&lt;/span&gt; &lt;span class="n"&gt;quote&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;triggerBtn&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;click&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;dialog&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByRole&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'dialog'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;enterprise&lt;/span&gt; &lt;span class="n"&gt;quote&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dialog&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBeVisible&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Verify initial focus landed on first interactive element or close button&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dialog&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByRole&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'button'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;close&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBeFocused&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Tab through dialog elements&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;keyboard&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;press&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'Tab'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dialog&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByLabel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;company&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBeFocused&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Press Escape to dismiss&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;keyboard&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;press&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'Escape'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dialog&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBeHidden&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// CRUCIAL: Focus must return to the original trigger element (WCAG 2.4.3)&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;triggerBtn&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toBeFocused&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  3. Screen Reader Assertion with VoiceOver / Guidepup
&lt;/h2&gt;

&lt;p&gt;For critical user flows (e.g., checkout payments, emergency alert banners), relying on visual state assertions (&lt;code&gt;toBeVisible()&lt;/code&gt;) leaves you blind to screen reader output.&lt;/p&gt;

&lt;p&gt;Using &lt;code&gt;@guidepup/playwright&lt;/code&gt;, you can assert against the actual speech synthesizer of Apple VoiceOver:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;voiceOverTest&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;test&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'@guidepup/playwright'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'VoiceOver announces live cart updates via ARIA live region'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;voiceOver&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;goto&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'/shop'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;voiceOver&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Add item to cart&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getByRole&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'button'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;add&lt;/span&gt; &lt;span class="n"&gt;to&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;click&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// Assert VoiceOver announced the status message&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;lastSpoken&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;voiceOver&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;lastSpokenPhrase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;expect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;lastSpoken&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toContain&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'Item added to cart. Subtotal updated.'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;voiceOver&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stop&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  4. The 3-Tier CI Gate Strategy
&lt;/h2&gt;

&lt;p&gt;To keep PR velocity high without letting accessibility regressions slip into production:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Pull Request Smoke (Fast):&lt;/strong&gt; Run &lt;code&gt;@axe-core/playwright&lt;/code&gt; across key routes (&amp;lt;15 seconds).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Interactive Component Gates:&lt;/strong&gt; Run keyboard navigation &amp;amp; focus-trap spec suites.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Weekly Compliance Audit:&lt;/strong&gt; Run comprehensive screen-reader and color contrast passes against all authenticated routes, exporting an auditable VPAT / ACR readiness report.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;By embedding these checks into your standard GitHub Actions workflow, compliance stops being a panicked annual legal scramble and becomes standard engineering hygiene.&lt;/p&gt;




&lt;h3&gt;
  
  
  Ready-to-Use Toolkit: ADA Title II &amp;amp; WCAG 2.1 AA Triage Playbook ($25)
&lt;/h3&gt;

&lt;p&gt;Skip the boilerplate and grab the production-ready kit (PDF guide, templates, and CI guardrails):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://buy.polar.sh/polar_cl_4WRvn1tdquxFPldQ5wuMxUnArbKqQLA1kkk1o4K1Hl6" rel="noopener noreferrer"&gt;Get ADA Title II &amp;amp; WCAG 2.1 AA Triage Playbook ($25)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://avilano.dev/products" rel="noopener noreferrer"&gt;Browse all 5 QA, A11y &amp;amp; AI Kits ($69 Bundle)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://avilano.dev/blog/ada-title-ii-wcag-2026-compliance-guide" rel="noopener noreferrer"&gt;avilano.dev&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>a11y</category>
      <category>wcag</category>
      <category>compliance</category>
    </item>
  </channel>
</rss>
