# Writing Custom axe-core Rules for Complex Data Tables

Automated accessibility pipelines frequently stall when enterprise data grids bypass default axe-core validators due to virtualized DOM rendering and dynamic ARIA injection. When CI/CD workflows block on false positives or miss critical structural violations, custom rule implementation becomes mandatory. This guide provides exact configuration steps for extending the evaluation engine, resolving false negatives, and integrating custom matchers into automated testing workflows.

Key implementation targets:

• Default td-headers-attr and table-fake-caption checks fail on virtualized DOM structures.
• Custom rules require explicit matches scoping and synchronous evaluate functions.
• False negatives stem from post-mount ARIA injection and async rendering states.

# Root Cause Analysis: Default Rule Limitations

Standard axe-core matchers operate on static DOM hierarchies. Modern enterprise grids rely on aria-rowindex and aria-colindex to manage virtual scrolling, which breaks traditional table traversal logic. When aria-describedby is injected after the initial paint cycle, baseline scanners return false negatives.

Understanding the baseline architecture for extending the evaluation engine is critical before overriding defaults. The foundational patterns for managing context-aware validation states are documented in Custom Rule Development & Context-Aware Testing.

# Exact Configuration & Custom Matcher Implementation

Override default behavior by injecting a scoped rule via axe.configure(). The matches callback isolates target components, while evaluate performs synchronous validation against rendered nodes. Follow strict selector scoping patterns to prevent DOM bleed across unrelated components, as detailed in Component-Specific Rule Writing. If your grid renders inside a custom element with a shadow root, the selector will not pierce the boundary — adapt the traversal patterns in writing axe rules for web components and shadow DOM.

axe.configure({
  rules: [{
    id: 'complex-grid-header-mapping',
    selector: '[role="grid"]',
    tags: ['cat.tables', 'wcag2a'],
    impact: 'serious',
    matches: (node) => node.getAttribute('aria-rowcount') !== null,
    evaluate: function(node) {
      const headers = node.querySelectorAll('[role="columnheader"]');
      if (headers.length === 0) return false;
      const hasValidMapping = Array.from(headers).every(h =>
        h.textContent.trim() !== '' || h.getAttribute('aria-label')
      );
      return hasValidMapping;
    }
  }]
});

Note that axe-core rule evaluate functions must return synchronously — they cannot return a Promise. If you need to wait for async rendering, do so in your test runner (e.g., page.waitForSelector) before calling axe.run().

Disable conflicting default checks during execution to prevent duplicate reporting:

const results = await axe.run(document, {
  rules: { 'table-fake-caption': { enabled: false } }
});

# Validation & False-Positive Resolution

Test rule accuracy by inspecting nodes.any arrays in the violation output. Configure axe.run() to capture both passes and failures for granular debugging:

const results = await axe.run(document, {
  resultTypes: ['violations', 'passes']
});

results.violations.forEach(v => {
  console.log('Violation:', v.id, 'Nodes:', v.nodes.map(n => n.target));
});

Implement conditional guards to skip transient UI states. Loading skeletons and virtualized placeholders should bypass validation until the DOM stabilizes:

axe.configure({
  rules: [{
    id: 'complex-grid-header-mapping',
    selector: '[role="grid"]',
    matches: (node) => node.getAttribute('aria-rowcount') !== null,
    evaluate: function(node) {
      // Skip validation while the grid is loading
      if (node.getAttribute('aria-busy') === 'true') return true;

      const headers = node.querySelectorAll('[role="columnheader"]');
      if (headers.length === 0) return false;
      return Array.from(headers).every(h =>
        h.textContent.trim() !== '' || h.getAttribute('aria-label')
      );
    }
  }]
});

Tune impact severity to align with engineering triage standards. Structural warnings that do not block screen reader navigation should be downgraded from critical to moderate. Verify exclude selectors in your runner configuration to prevent false positives on pagination controls or export buttons.

# Pipeline Impact & CI/CD Integration

Package the custom rule as a module and import it before invoking axe.run() in your Playwright test harness. Configure failure thresholds to prevent minor warnings from blocking pull requests.

# .github/workflows/a11y-check.yml
- name: Run Accessibility Tests
  run: npx playwright test --grep "@a11y"
  env:
    AXE_FAIL_ON_VIOLATION: "critical,serious"

// tests/data-grid.a11y.ts
import { test, expect } from '@playwright/test';
import { AxeBuilder } from '@axe-core/playwright';
import { configureCustomRules } from '../lib/a11y/custom-rules';

test('data grid accessibility @a11y', async ({ page }) => {
  await page.goto('/data-grid-demo');
  await page.waitForSelector('[role="grid"][aria-rowcount]', { state: 'visible' });

  // Inject custom rules via page.evaluate before using AxeBuilder
  await page.evaluate(() => {
    // Custom rules must be configured inside the browser context
    window.axe.configure({
      rules: [{
        id: 'complex-grid-header-mapping',
        selector: '[role="grid"]',
        tags: ['cat.tables'],
        impact: 'serious',
        matches: (node) => node.getAttribute('aria-rowcount') !== null,
        evaluate: (node) => {
          const headers = node.querySelectorAll('[role="columnheader"]');
          return Array.from(headers).every(h => h.textContent.trim() !== '');
        }
      }]
    });
  });

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  const blocking = results.violations.filter(v =>
    v.impact === 'critical' || v.impact === 'serious'
  );
  expect(blocking).toHaveLength(0);
});

# Common Pitfalls to Avoid

• Global DOM Queries: Over-relying on document.querySelectorAll inside evaluate instead of scoping to the provided node parameter causes cross-component interference.
• Async evaluate functions: axe-core evaluate must return a boolean synchronously. Async functions silently return undefined (falsy), causing all nodes to fail the check.
• Virtualization Mismatches: Ignoring aria-owns versus actual DOM hierarchy mismatches in dynamically injected rows breaks traversal logic.
• Impact Misclassification: Setting impact: 'critical' for cosmetic alignment issues causes unnecessary CI/CD pipeline failures and alert fatigue.

# Frequently Asked Questions

How do I prevent custom rules from conflicting with axe-core’s default table checks? Use matches functions to isolate [role="grid"] or custom class names, then explicitly disable default rules via rules: { 'table-fake-caption': { enabled: false } } in the axe.run() configuration object.

Why can’t my evaluate function be async? axe-core’s rule engine calls evaluate synchronously and reads its return value immediately. An async function returns a Promise object, which is truthy, so every node passes silently. Use waitForSelector in your test runner before calling axe.run() to handle any async rendering.

How do I handle false positives in dynamically filtered tables? Add a guard in the evaluate function checking for aria-busy="true" and returning true (pass) until the DOM stabilizes and data is fully rendered.

# Related

• Component-Specific Rule Writing — the parent guide on scoped matchers and synchronous evaluate functions.
• Writing axe Rules for Web Components and Shadow DOM — pierce shadow boundaries when grids live inside custom elements.
• DOM Inspection for Dynamic Content — wait for virtualized rows to render before the table rule runs.
• Automated Remediation & Accessibility Fixing Patterns — fix recurring header-mapping defects across grids systematically.