Class AccessibilityHelper

java.lang.Object
com.shaft.validation.accessibility.AccessibilityHelper
public class AccessibilityHelper extends Object
Internal helper that drives WCAG-based accessibility analysis using the axe-core engine via AxeBuilder.

The class exposes static methods that run an axe scan against a live WebDriver session, persist the results as JSON and an interactive HTML report, and attach the report to the current Allure test run as an attachment.

Typical usage: 

// Quick fire-and-forget scan with default configuration
AccessibilityHelper.analyzePageAccessibility(driver, "HomePage");

// Scan and obtain a structured result object for in-test assertions
AccessibilityResult result = AccessibilityHelper.analyzePageAccessibilityAndSave(
        driver, "CheckoutPage", true);
System.out.println("Accessibility score: " + result.getAccessibilityScore() + "%");

Thread safety: DATE_FORMAT and DISPLAY_DATE_FORMAT are immutable DateTimeFormatter instances, so formatting operations are safe to call from parallel test threads. However, concurrent scans of the same pageName within the same second may produce file-name collisions in the shared reports directory; use distinct page names or unique report directories when running parallel scans on the same page.

See Also:

  • Method Details

    • analyzePageAccessibility

      public static void analyzePageAccessibility(org.openqa.selenium.WebDriver driver, String pageName)
      Runs a WCAG accessibility scan against the currently loaded page using the default AccessibilityHelper.AccessibilityConfig and writes both a JSON data file and an interactive HTML report to disk. The HTML report is also attached to the current Allure test step automatically. 
      AccessibilityHelper.analyzePageAccessibility(driver, "HomePage");
      Parameters:
      driver - active WebDriver instance pointing at the page to scan; must not be null
      pageName - human-readable label used in the report file name and Allure attachment title; must not be blank

    • analyzePageAccessibility

      public static void analyzePageAccessibility(org.openqa.selenium.WebDriver driver, String pageName, AccessibilityHelper.AccessibilityConfig config)
      Runs a WCAG accessibility scan using the supplied AccessibilityHelper.AccessibilityConfig and writes both a JSON data file and an interactive HTML report to disk. The HTML report is also attached to the current Allure test step automatically.

      The method blocks until document.readyState === "complete" and the DOM has been stable for 1500 ms before invoking axe. 

      AccessibilityConfig config = new AccessibilityConfig()
        .setTags(List.of("wcag21aa"))
        .setReportsDir("target/a11y/");
AccessibilityHelper.analyzePageAccessibility(driver, "CheckoutPage", config);
      Parameters:
      driver - active WebDriver instance pointing at the page to scan; must not be null
      pageName - human-readable label used in the report file name and Allure attachment title; must not be blank
      config - scan configuration; must not be null
      Throws:
      IllegalArgumentException - if driver, pageName, or config fails validation

    • analyzePageAccessibility

      public static void analyzePageAccessibility(org.openqa.selenium.WebDriver driver, String pageName, String context)
      Convenience overload that runs an accessibility scan scoped to a specific CSS context selector using default settings for all other configuration values. 
      AccessibilityHelper.analyzePageAccessibility(driver, "Checkout", "#checkout-form");
      Parameters:
      driver - active WebDriver instance; must not be null
      pageName - label used for the report file name and Allure attachment title
      context - CSS selector restricting the scan scope (e.g. "main, footer")

    • hasCriticalViolations

      public static boolean hasCriticalViolations(org.openqa.selenium.WebDriver driver, String pageName)
      Determines whether the currently loaded page has any axe-detected WCAG violations using the default rule set. 
      if (AccessibilityHelper.hasCriticalViolations(driver, "SearchResults")) {
    throw new AssertionError("Accessibility violations detected");
}
      Parameters:
      driver - active WebDriver instance; must not be null
      pageName - label used for log and error messages
      Returns:
      true if at least one axe violation was found; false otherwise
      Throws:
      RuntimeException - if the axe analysis itself fails

    • getViolationsByType

      public static Map<String,Integer> getViolationsByType(org.openqa.selenium.WebDriver driver)
      Returns a breakdown of axe violations grouped by their WCAG conformance level (e.g. "WCAG 2.1 AA", "Best Practice").

      The map value represents the total number of affected elements (nodes), not the number of distinct rules. 

      Map<String, Integer> counts = AccessibilityHelper.getViolationsByType(driver);
counts.forEach((type, count) ->
        System.out.printf("%s: %d affected element(s)%n", type, count));
      Parameters:
      driver - active WebDriver instance; must not be null
      Returns:
      map of WCAG level label to affected-element count; never null
      Throws:
      RuntimeException - if the axe analysis fails

    • isAccessible

      public static boolean isAccessible(org.openqa.selenium.WebDriver driver)
      Performs a quick axe accessibility check and returns whether the page has zero violations. 
      assertTrue(AccessibilityHelper.isAccessible(driver),
        "Page should have no accessibility violations");
      Parameters:
      driver - active WebDriver instance; must not be null
      Returns:
      true if no axe violations were found; false if at least one violation exists or if the analysis could not be completed

    • analyzePageAccessibilityAndSave

      public static AccessibilityHelper.AccessibilityResult analyzePageAccessibilityAndSave(org.openqa.selenium.WebDriver driver, String pageName, boolean saveReport)
      Runs an accessibility scan with default configuration, optionally persisting reports to disk, and returns a structured AccessibilityHelper.AccessibilityResult. 
      AccessibilityResult result =
        AccessibilityHelper.analyzePageAccessibilityAndSave(driver, "Checkout", true);
assertFalse(result.hasViolations(), "No accessibility violations expected");
      Parameters:
      driver - active WebDriver instance; must not be null
      pageName - label for the report and Allure attachment; must not be blank
      saveReport - true to write JSON/HTML reports and attach them to Allure
      Returns:
      an AccessibilityHelper.AccessibilityResult containing violation details and score
      Throws:
      RuntimeException - if the axe analysis fails

    • analyzePageAccessibilityAndSave

      public static AccessibilityHelper.AccessibilityResult analyzePageAccessibilityAndSave(org.openqa.selenium.WebDriver driver, String pageName, AccessibilityHelper.AccessibilityConfig config, boolean saveReport)
      Full-control overload: runs an accessibility scan with the supplied AccessibilityHelper.AccessibilityConfig, optionally saves reports, and returns a structured AccessibilityHelper.AccessibilityResult suitable for programmatic assertions.

      The accessibility score is calculated as: 

      score = (passesCount / (passesCount + violationsCount)) * 100
      Incomplete checks are excluded from the score calculation. 
      AccessibilityConfig config = new AccessibilityConfig()
        .setTags(List.of("wcag21aa"))
        .setContext("#content");
AccessibilityResult result =
        AccessibilityHelper.analyzePageAccessibilityAndSave(driver, "Home", config, true);
System.out.printf("Score: %.1f%% (%d violation(s))%n",
        result.getAccessibilityScore(), result.getViolationsCount());
      Parameters:
      driver - active WebDriver instance; must not be null
      pageName - label for the report and Allure attachment; must not be blank
      config - scan configuration; a default instance is used when null
      saveReport - true to write JSON/HTML reports and attach them to Allure
      Returns:
      an AccessibilityHelper.AccessibilityResult containing violation details and score
      Throws:
      IllegalArgumentException - if the supplied context selector matches no elements on the page
      RuntimeException - if the axe analysis fails for any other reason

    • attachReportToAllure

      public static void attachReportToAllure(String pageName)
      Attaches the most recently generated HTML accessibility report for the given page to the current Allure test step.

      The method looks for the latest report file matching AccessibilityReport_<pageName>* inside the default "accessibility-reports/" directory. 

      AccessibilityHelper.attachReportToAllure("HomePage");
      Parameters:
      pageName - label used to locate the report file; must match the value passed when the report was originally generated

    • attachFilteredReportToAllure

      public static void attachFilteredReportToAllure(String pageName, AccessibilityHelper.AccessibilityResult result, org.openqa.selenium.WebDriver driver)
      Generates a filtered HTML report containing only the violations present in the supplied AccessibilityHelper.AccessibilityResult and attaches it to the current Allure test step.

      This is useful when a full report already exists but you want a focused attachment highlighting only the failing rules. 

      AccessibilityResult result =
        AccessibilityHelper.analyzePageAccessibilityAndSave(driver, "Cart", true);
if (result.hasViolations()) {
    AccessibilityHelper.attachFilteredReportToAllure("Cart", result, driver);
}
      Parameters:
      pageName - label used in the Allure attachment title and report file name
      result - AccessibilityHelper.AccessibilityResult whose violations will be rendered
      driver - active WebDriver instance used to read browser metadata for the report header

    • generateFilteredHTMLReport

      public static void generateFilteredHTMLReport(AccessibilityHelper.AccessibilityResult result, String pageName, String reportPath, org.openqa.selenium.WebDriver driver) throws IOException, org.json.JSONException
      Generates a minimal HTML accessibility report that lists only the violations contained in the supplied AccessibilityHelper.AccessibilityResult and writes it to the given file path.

      The output is suitable for attaching directly to an Allure report via attachFilteredReportToAllure(String, AccessibilityResult, WebDriver). 

      AccessibilityHelper.generateFilteredHTMLReport(
        result, "Checkout", "target/a11y/filtered.html", driver);
      Parameters:
      result - AccessibilityHelper.AccessibilityResult providing the violation data
      pageName - page label rendered in the report heading
      reportPath - file-system path where the HTML file will be written
      driver - active WebDriver used to read browser metadata for the report header
      Throws:
      IOException - if the report file cannot be created or written
      org.json.JSONException - if serialising the violation data fails

    • getLatestReportPath

      public static Path getLatestReportPath(String pageName) throws IOException
      Finds the most recently modified HTML report file for the given page inside the "accessibility-reports/" directory. 
      Path latestReport = AccessibilityHelper.getLatestReportPath("HomePage");
if (latestReport != null) {
    System.out.println("Latest report: " + latestReport);
}
      Parameters:
      pageName - label used to filter report files by their name prefix
      Returns:
      the Path of the newest matching report, or null if the reports directory does not exist or contains no matching files
      Throws:
      IOException - if reading the directory listing fails