Class AccessibilityActions

java.lang.Object
com.shaft.validation.accessibility.AccessibilityActions
public class AccessibilityActions extends Object
Provides a fluent API for running automated accessibility audits against web pages using the axe-core engine via AccessibilityHelper.

Typical usage: 

driver.accessibility()
      .analyzePage("Home")
      .assertNoCriticalViolations("Home")
      .backToBrowser();

Analysis results are cached in a ConcurrentHashMap keyed by a composite of page name, AccessibilityConfig identity via config.hashCode(), and the saveReport flag. Successive calls with the same config instance and the same page name will reuse the cached result. Note that two separately constructed AccessibilityConfig objects with identical settings will produce different cache keys because AccessibilityConfig does not override equals/hashCode.

Thread safety: Each AccessibilityActions instance is tied to a single SHAFT.GUI.WebDriver instance and must not be shared across threads. The internal cache (ConcurrentHashMap) is safe for concurrent reads, but the analysis itself (browser interaction) is not.

See Also:

  • Constructor Details

    • AccessibilityActions

      public AccessibilityActions(org.openqa.selenium.WebDriver rawDriver, BrowserActions browserActions)
      Constructs an AccessibilityActions instance backed by the supplied raw WebDriver and the caller's BrowserActions context.

      The raw driver is wrapped in a SHAFT.GUI.WebDriver so that SHAFT's assertion and verification helpers are available internally.

      Parameters:
      rawDriver - the underlying Selenium WebDriver used to run axe-core scripts
      browserActions - the BrowserActions instance to return to when backToBrowser() is called

  • Method Details

    • analyzePage

      public AccessibilityActions analyzePage(String pageName)
      Runs an accessibility audit on the current page, saves the HTML report to disk, and attaches it to the Allure report under the given pageName.

      The result is cached so that subsequent assertion calls for the same page reuse it without triggering another axe run.

      Example: 

      driver.accessibility().analyzePage("Checkout");
      Parameters:
      pageName - a human-readable label used to name the saved report file and the Allure attachment (e.g. "HomePage")
      Returns:
      this AccessibilityActions instance for method chaining

    • analyzePage

      public AccessibilityActions analyzePage(String pageName, AccessibilityHelper.AccessibilityConfig config)
      Runs an accessibility audit on the current page using a custom AccessibilityHelper.AccessibilityConfig, saves the HTML report to disk, and attaches it to the Allure report.

      Use this overload when you need to restrict the audit to specific WCAG tags, rules, or impact levels that differ from the default configuration.

      Example: 

      AccessibilityHelper.AccessibilityConfig config = new AccessibilityHelper.AccessibilityConfig()
        .setTags(List.of("wcag2a", "wcag2aa"));
driver.accessibility().analyzePage("Checkout", config);
      Parameters:
      pageName - a human-readable label used to name the saved report file and Allure attachment
      config - custom axe-core configuration controlling which rules / tags are included
      Returns:
      this AccessibilityActions instance for method chaining

    • analyzeAndReturn

      public AccessibilityHelper.AccessibilityResult analyzeAndReturn(String pageName)
      Analyzes the current page and returns the AccessibilityHelper.AccessibilityResult for programmatic inspection. The report is saved to disk and the result is cached.

      Subsequent calls with the same pageName return the cached result without running the audit again.

      Example: 

      AccessibilityHelper.AccessibilityResult result =
        driver.accessibility().analyzeAndReturn("ProductPage");
int violationCount = result.getViolations().size();
      Parameters:
      pageName - a human-readable label for the page being audited
      Returns:
      the AccessibilityHelper.AccessibilityResult containing violations, passes, and the overall accessibility score

    • analyzeAndReturn

      public AccessibilityHelper.AccessibilityResult analyzeAndReturn(String pageName, boolean saveReport)
      Analyzes the current page, optionally saving the HTML report to disk, and returns the AccessibilityHelper.AccessibilityResult for programmatic inspection.

      Example: 

      // Analyze without persisting a report file
AccessibilityHelper.AccessibilityResult result =
        driver.accessibility().analyzeAndReturn("SearchPage", false);
      Parameters:
      pageName - a human-readable label for the page being audited
      saveReport - true to persist the HTML report file on disk; false to skip file creation (useful for assertion-only checks)
      Returns:
      the AccessibilityHelper.AccessibilityResult for the audited page

    • analyzeAndReturn

      public AccessibilityHelper.AccessibilityResult analyzeAndReturn(String pageName, AccessibilityHelper.AccessibilityConfig config)
      Analyzes the current page using a custom AccessibilityHelper.AccessibilityConfig, saves the report, and returns the result. The result is cached for the given pageName + config combination.

      Example: 

      AccessibilityHelper.AccessibilityConfig config = new AccessibilityHelper.AccessibilityConfig()
        .setTags(List.of("best-practice"));
AccessibilityHelper.AccessibilityResult result =
        driver.accessibility().analyzeAndReturn("CartPage", config);
      Parameters:
      pageName - a human-readable label for the page being audited
      config - custom axe-core configuration; null uses the default configuration
      Returns:
      the AccessibilityHelper.AccessibilityResult for the audited page

    • analyzeAndReturn

      public AccessibilityHelper.AccessibilityResult analyzeAndReturn(String pageName, AccessibilityHelper.AccessibilityConfig config, boolean saveReport)
      Analyzes the current page using the given configuration and saveReport flag, then returns the AccessibilityHelper.AccessibilityResult.

      This is the canonical overload that all other analyzeAndReturn variants delegate to. Results are memoized: the first call computes and caches the result; subsequent calls with an identical key return the cached value immediately.

      Example: 

      AccessibilityHelper.AccessibilityConfig config = new AccessibilityHelper.AccessibilityConfig()
        .setTags(List.of("wcag2a"));
AccessibilityHelper.AccessibilityResult result =
        driver.accessibility().analyzeAndReturn("LoginPage", config, false);
      Parameters:
      pageName - a human-readable label for the page being audited
      config - custom axe-core configuration; null applies the default configuration
      saveReport - true to persist the HTML report file; false to skip it
      Returns:
      the AccessibilityHelper.AccessibilityResult for the audited page

    • analyzeWithIgnoredRules

      public AccessibilityActions analyzeWithIgnoredRules(String pageName, List<String> ignoredRuleIds)
      Analyzes the current page and attaches a filtered Allure report that excludes the specified rule IDs, without permanently modifying the cached result.

      This is useful when certain known violations should be suppressed from the report for a particular context (e.g. third-party widgets) while keeping the full cached result intact for other callers.

      Example: 

      driver.accessibility()
      .analyzeWithIgnoredRules("Dashboard", List.of("color-contrast", "label"));
      Parameters:
      pageName - a human-readable label for the page being audited; used to retrieve or create the cached result and to name the Allure attachment
      ignoredRuleIds - axe-core rule IDs (e.g. "color-contrast", "label") to exclude from the attached report; the underlying cached violations list is restored after the attachment is created
      Returns:
      this AccessibilityActions instance for method chaining

    • assertNoCriticalViolations

      public AccessibilityActions assertNoCriticalViolations(String pageName)
      Asserts (hard assertion) that the current page has no accessibility violations with an impact level of "critical".

      The audit result is fetched from the cache or computed on demand. Failure causes the test to stop immediately (hard assertion semantics).

      Example: 

      driver.accessibility()
      .analyzePage("PaymentPage")
      .assertNoCriticalViolations("PaymentPage");
      Parameters:
      pageName - a human-readable label identifying the page to assert against; must match the label used in a preceding analyzePage(String) or analyzeAndReturn(String) call so the cache is hit
      Returns:
      this AccessibilityActions instance for method chaining

    • verifyNoCriticalViolations

      public AccessibilityActions verifyNoCriticalViolations(String pageName)
      Verifies (soft assertion) that the current page has no accessibility violations with an impact level of "critical".

      Unlike assertNoCriticalViolations(String), a soft assertion failure is recorded but does not stop test execution immediately; all failures are reported at the end of the test.

      Example: 

      driver.accessibility()
      .analyzePage("CartPage")
      .verifyNoCriticalViolations("CartPage");
      Parameters:
      pageName - a human-readable label identifying the page to verify; must match the label used in a preceding analysis call so the cache is hit
      Returns:
      this AccessibilityActions instance for method chaining

    • assertIsAccessible

      public AccessibilityActions assertIsAccessible()
      Asserts (hard assertion) that the current page is fully accessible according to AccessibilityHelper.isAccessible(WebDriver)'s default criteria (zero violations).

      Example: 

      driver.accessibility().assertIsAccessible();
      Returns:
      this AccessibilityActions instance for method chaining

    • verifyIsAccessible

      public AccessibilityActions verifyIsAccessible()
      Verifies (soft assertion) that the current page is fully accessible according to AccessibilityHelper.isAccessible(WebDriver)'s default criteria (zero violations).

      Unlike assertIsAccessible(), a failure is recorded but does not halt the test.

      Example: 

      driver.accessibility().verifyIsAccessible();
      Returns:
      this AccessibilityActions instance for method chaining

    • assertNoViolationsByImpact

      public AccessibilityActions assertNoViolationsByImpact(String pageName, String... impactLevels)
      Asserts (hard assertion) that the current page has no accessibility violations matching any of the supplied impact levels.

      A filtered Allure attachment is generated showing only the violations that matched the requested impact levels, making failures easier to triage.

      Example: 

      driver.accessibility()
      .assertNoViolationsByImpact("ProfilePage", "critical", "serious");
      Parameters:
      pageName - a human-readable label for the page being checked; used for caching and the assertion failure message
      impactLevels - one or more axe-core impact levels to check (case-insensitive): "minor", "moderate", "serious", "critical"
      Returns:
      this AccessibilityActions instance for method chaining

    • failIfViolationsExist

      public AccessibilityActions failIfViolationsExist(String pageName)
      Attaches a filtered Allure report for the given page and throws an AssertionError if any accessibility violations exist.

      This method is a strict gate: any violation — regardless of impact level — causes an immediate hard failure. Use assertNoViolationsByImpact(String, String...) when you need to filter by severity.

      Example: 

      driver.accessibility()
      .analyzePage("LandingPage")
      .failIfViolationsExist("LandingPage");
      Parameters:
      pageName - a human-readable label for the page being checked; must match a previously analyzed page so the cached result is reused
      Returns:
      this AccessibilityActions instance for method chaining
      Throws:
      AssertionError - if one or more accessibility violations are present on the page

    • assertAccessibilityScoreAtLeast

      public AccessibilityActions assertAccessibilityScoreAtLeast(String pageName, double minimumPercentage)
      Asserts that the accessibility score for the given page is at least minimumPercentage. The report is saved to disk.

      The score is computed by AccessibilityHelper.AccessibilityResult.getAccessibilityScore() and represents the ratio of passing rules to total rules as a percentage (0–100).

      Example: 

      driver.accessibility()
      .assertAccessibilityScoreAtLeast("HomePage", 90.0);
      Parameters:
      pageName - a human-readable label for the page being checked
      minimumPercentage - the minimum acceptable accessibility score (inclusive), in the range 0.0–100.0
      Returns:
      this AccessibilityActions instance for method chaining
      Throws:
      IllegalArgumentException - if minimumPercentage is outside [0, 100]
      AssertionError - if the computed score is below minimumPercentage

    • assertAccessibilityScoreAtLeast

      public AccessibilityActions assertAccessibilityScoreAtLeast(String pageName, double minimumPercentage, boolean saveReport)
      Asserts that the accessibility score for the given page is at least minimumPercentage, with control over whether the HTML report is saved to disk.

      Example: 

      // Assert score without persisting a report file
driver.accessibility()
      .assertAccessibilityScoreAtLeast("ResultsPage", 85.0, false);
      Parameters:
      pageName - a human-readable label for the page being checked
      minimumPercentage - the minimum acceptable accessibility score (inclusive), in the range 0.0–100.0
      saveReport - true to persist the HTML report file; false to skip it
      Returns:
      this AccessibilityActions instance for method chaining
      Throws:
      IllegalArgumentException - if minimumPercentage is outside [0, 100]
      AssertionError - if the computed score is below minimumPercentage

    • assertAccessibilityScoreAtLeast

      public AccessibilityActions assertAccessibilityScoreAtLeast(String pageName, double minimumPercentage, AccessibilityHelper.AccessibilityConfig config)
      Asserts that the accessibility score for the given page is at least minimumPercentage, using a custom AccessibilityHelper.AccessibilityConfig. The report is saved to disk.

      Example: 

      AccessibilityHelper.AccessibilityConfig config = new AccessibilityHelper.AccessibilityConfig()
        .setTags(List.of("wcag2a"));
driver.accessibility()
      .assertAccessibilityScoreAtLeast("ProfilePage", 95.0, config);
      Parameters:
      pageName - a human-readable label for the page being checked
      minimumPercentage - the minimum acceptable accessibility score (inclusive), in the range 0.0–100.0
      config - custom axe-core configuration applied during the audit
      Returns:
      this AccessibilityActions instance for method chaining
      Throws:
      IllegalArgumentException - if minimumPercentage is outside [0, 100]
      AssertionError - if the computed score is below minimumPercentage

    • assertAccessibilityScoreAtLeast

      public AccessibilityActions assertAccessibilityScoreAtLeast(String pageName, double minimumPercentage, AccessibilityHelper.AccessibilityConfig config, boolean saveReport)
      Asserts that the accessibility score for the given page is at least minimumPercentage, using a custom AccessibilityHelper.AccessibilityConfig and explicit control over report persistence.

      This is the most flexible overload and is the one all other assertAccessibilityScoreAtLeast variants ultimately delegate to.

      Example: 

      AccessibilityHelper.AccessibilityConfig config = new AccessibilityHelper.AccessibilityConfig()
        .setTags(List.of("wcag2aa"));
driver.accessibility()
      .assertAccessibilityScoreAtLeast("SettingsPage", 80.0, config, true);
      Parameters:
      pageName - a human-readable label for the page being checked
      minimumPercentage - the minimum acceptable accessibility score (inclusive), in the range 0.0–100.0
      config - custom axe-core configuration applied during the audit; null uses the default configuration
      saveReport - true to persist the HTML report file; false to skip it
      Returns:
      this AccessibilityActions instance for method chaining
      Throws:
      IllegalArgumentException - if minimumPercentage is outside [0, 100]
      AssertionError - if the computed score is below minimumPercentage

    • backToBrowser

      public BrowserActions backToBrowser()
      Returns the BrowserActions instance that was used to create this AccessibilityActions, enabling fluent chaining back into browser-level operations.

      Example: 

      driver.accessibility()
      .analyzePage("Home")
      .assertNoCriticalViolations("Home")
      .backToBrowser()
      .navigateToURL("https://example.com/about");
      Returns:
      the originating BrowserActions instance