val-a11y/val-a11y.d.ts

Cypress plugin to perform configurable accessibility tests using AXE. It provides a list of violations and detailed information in the Cypress log, and generates an HTML document that includes screenshots of each violation on the page. The plugin leverage

/// <reference types="cypress" />
/// <reference types="axe-core" />
/// <reference types="cypress-axe" />

declare namespace Cypress {
  interface Chainable {
    /**
     * Check accessibility of the current page or a specific context using Axe.
     * This command uses the axe-core engine to analyze the DOM and report any accessibility violations.
     *
     * @param context - Optional context for accessibility analysis. Specifies the portion of the DOM to analyze.
     *                  If no context is specified, the full document is analyzed.
     *
     *                  Supported values:
     *                  - A **CSS selector** (e.g., '.main-container') to analyze a specific part of the page.
     *                  - A **DOM element** (e.g., using `cy.get()` or native elements).
     *                  - A **NodeList** (multiple DOM elements).
     *                  - An object for advanced configuration with:
     *                      - `include` - Array of CSS selectors to include in the analysis.
     *                      - `exclude` - Array of CSS selectors to exclude from the analysis.
     *                      - `fromFrames` - Frame elements that should be tested.
     *                      - `fromShadowDom` - Shadow DOM elements to include in analysis.
     *
     * @param options - Optional configuration object for accessibility checks.
     *                  Allows customization of the analysis, styling, and reporting.
     *
     *                  Supported options:
     *                  - `generateReport` (boolean) - Whether to generate an accessibility report. Default: `true`.
     *                  - `impactStyling` (object) - Custom styles for highlighting issues based on impact levels.
     *                      Example:
     *                      {
     *                          critical: { icon: '🟥', style: 'stroke: #DE071B;' },
     *                          serious:  { icon: '🟧', style: 'stroke: #FFA66A;' }
     *                      }
     *                  - `includedImpacts` (array) - Array of impact levels to include. E.g., `['critical', 'serious']`.
     *                      Possible values: `'minor'`, `'moderate'`, `'serious'`, `'critical'`.
     *                  - `retries` (number) - Number of retries for the accessibility check. Default: `0`.
     *                  - `interval` (number) - Interval in milliseconds between retries. Default: `1000`.
     *                  - `skipFailures` (boolean) - Allow tests to pass even with accessibility violations. Default: `false`.
     *                  - `runOnly` (array) - Specific rules or tags to run. Example: `['wcag2a', 'best-practice']`.
     *                  - `rules` (object) - Enable or disable specific Axe rules. Example:
     *                      { rules: { 'color-contrast': { enabled: false } } }.
     *                  - `reporter` (string) - Custom reporter for results.
     *                  - `resultTypes` (array) - Types of results to include, e.g., `['violations', 'incomplete']`.
     *                  - `selectors` (boolean) - Return CSS selectors for elements. Default: `true`.
     *                  - `ancestry` (boolean) - Include ancestor selectors. Default: `false`.
     *                  - `iframes` (boolean) - Analyze iframes. Default: `true`.
     *                  - `frameWaitTime` (number) - Timeout for iframe responses. Default: `60000`.
     *                  - `preload` (boolean) - Preload additional assets before running rules. Default: `true`.
     *
     * @example
     * // Check accessibility of the full page
     * cy.checkAccessibility();
     *
     * @example
     * // Check accessibility of a specific DOM element using a CSS selector
     * cy.checkAccessibility('.main-container');
     *
     * @example
     * // Exclude elements from accessibility checks
     * cy.checkAccessibility({ exclude: ['button.skip-this'] });
     *
     * @example
     * // Analyze specific parts of the page
     * cy.checkAccessibility({ include: ['header', 'footer'] });
     *
     * @example
     * // Customize options for the accessibility check
     * cy.checkAccessibility('.content', {
     *   generateReport: true,
     *   includedImpacts: ['critical', 'serious'],
     *   retries: 2,
     *   runOnly: ['wcag2aa', 'best-practice'],
     *   skipFailures: true
     * });
     *
     * @example
     * // Override default styles for accessibility violations
     * cy.checkAccessibility(null, {
     *   impactStyling: {
     *     critical: { icon: '🟥', style: 'stroke: red; stroke-width: 5;' },
     *     serious: { icon: '🟧', style: 'stroke: orange; stroke-width: 5;' }
     *   }
     * });
     */
    checkAccessibility(
      context?:
        | string
        | Element
        | NodeList
        | Object
        | {
            /** Elements to exclude from accessibility check */
            exclude?: string[] | { exclude: string[] }
            /** Elements to specifically include in accessibility check */
            include?: string[] | { include: string[] }
            /** Check accessibility within iframes */
            fromFrames?: boolean
            /** Check accessibility within Shadow DOM */
            fromShadowDom?: boolean
          }
        | null,
      options?: {
        /** Generate an accessibility violation report */
        generateReport?: boolean
        /** Custom styling for different impact levels of accessibility violations */
        impactStyling?: {
          critical?: {
            /** Icon to represent critical issues */
            icon?: string
            /** CSS styling for critical issue highlighting */
            style?: string
          }
          serious?: {
            icon?: string
            style?: string
          }
          moderate?: {
            icon?: string
            style?: string
          }
          minor?: {
            icon?: string
            style?: string
          }
          fixme?: {
            /** Icon to represent fixable issues */
            icon?: string
          }
        }
        /** Impact levels to include in accessibility checks */
        includedImpacts?: ('minor' | 'moderate' | 'serious' | 'critical')[]
        /** Number of times to retry the accessibility check */
        retries?: number
        /** Interval between retries */
        interval?: number
        /** Whether to continue test execution despite accessibility violations */
        skipFailures?: boolean
        /** Specify only certain rules to run */
        runOnly?: string[]
        /** Enable or disable specific accessibility rules */
        rules?: Record<string, { enabled: boolean }>
        /** Specify the reporting mechanism */
        reporter?: string
        /** Types of results to include in the report */
        resultTypes?: string[]
        /** Include CSS selector information in the report */
        selectors?: boolean
        /** Include element ancestry information */
        ancestry?: boolean
        /** Generate XPath for elements with violations */
        xpath?: boolean
        /** Use absolute paths in reporting */
        absolutePaths?: boolean
        /** Check accessibility in iframes */
        iframes?: boolean
        /** Include references to specific elements */
        elementRef?: boolean
        /** Wait time for loading iframes */
        frameWaitTime?: number
        /** Preload resources before accessibility check */
        preload?: boolean
        /** Enable performance timing */
        performanceTimer?: boolean
        /** Wait time for ping responses */
        pingWaitTime?: number
      }
    ): Chainable<void>
  }
}