Skip to content

docs: add accessibility testing guide for plugin-e2e - #2835

Open
fastfrwrd wants to merge 2 commits into
mainfrom
fastfrwrd/a11y-testing-docs
Open

docs: add accessibility testing guide for plugin-e2e#2835
fastfrwrd wants to merge 2 commits into
mainfrom
fastfrwrd/a11y-testing-docs

Conversation

@fastfrwrd

Copy link
Copy Markdown
Contributor

What this PR does / why we need it:

Adds a dedicated "Accessibility testing" guide to the E2E testing docs, covering the scanForA11yViolations fixture and the toHaveNoA11yViolations matcher. Until now these APIs were only mentioned as a bullet in the @grafana/plugin-e2e README, so there was nowhere to point plugin authors.

The guide covers everything listed in the issue:

  • Installing the optional @axe-core/playwright peer dependency.
  • Scanning a full page, including the reminder to wait for content and where to find the axe JSON attachments in the Playwright report.
  • Scanning a subtree with include / exclude, plus a note that they take CSS selectors rather than Playwright locators or Grafana end-to-end selectors, and a helper for converting the latter.
  • The default Grafana rule set (DEFAULT_A11Y_TAGS).
  • Running custom rules through options, with a warning that options replaces the default WCAG tags, since AxeBuilder.options() overwrites what withTags() set.
  • Excluding a rule, both at scan time (options.rules) and at assertion time (ignoredRules), and why you'd pick one over the other.
  • Using threshold to hold the line on a plugin with existing violations.

Which issue(s) this PR fixes:

Fixes #2484

Special notes for your reviewer:

  • Every code sample was type checked against the real plugin-e2e types, and the Docusaurus production build passes with no broken links.
  • The toCssSelector helper in the "Scan part of a page" section exists because resolveGrafanaSelector isn't part of the public API. If we'd rather export it, I'm happy to do that in a follow-up and simplify this section.

Document the scanForA11yViolations fixture and the toHaveNoA11yViolations
matcher: installing the optional axe peer dependency, scanning full pages
and subtrees, the default WCAG rule set, custom rules, and the two ways to
exclude a rule.

Closes #2484
@fastfrwrd
fastfrwrd requested a review from a team as a code owner August 19, 2026 20:05
@fastfrwrd
fastfrwrd requested review from eledobleefe and joshhunt and removed request for a team August 19, 2026 20:05
@fastfrwrd fastfrwrd added the type/docs Changes only affect the documentation label Aug 19, 2026
Comment thread docusaurus/docs/e2e-test-a-plugin/accessibility-testing.md Outdated
@fastfrwrd fastfrwrd changed the title Docs: Add accessibility testing guide for plugin-e2e docs: Add accessibility testing guide for plugin-e2e Aug 19, 2026
@fastfrwrd fastfrwrd changed the title docs: Add accessibility testing guide for plugin-e2e docs: add accessibility testing guide for plugin-e2e Aug 19, 2026
@grafana-catalog-project-bot grafana-catalog-project-bot Bot moved this from 📬 Triage to 🔬 In review in Grafana Catalog Team Aug 19, 2026
@sunker
sunker self-requested a review August 21, 2026 07:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type/docs Changes only affect the documentation

Projects

Status: 🔬 In review

Development

Successfully merging this pull request may close these issues.

Docs: A11y testing with plugin-tools

1 participant