Interface VisualProcessingProvider

public interface VisualProcessingProvider
SHAFT-owned contract for optional visual-processing implementations.

Implementations may use optional computer-vision libraries, while engine callers interact only with SHAFT and JDK types. Providers are discovered through ServiceLoader.

  • Method Details

    • findImageWithinCurrentPage

      List<Integer> findImageWithinCurrentPage(String referenceImagePath, byte[] currentPageScreenshot)
      Finds a reference image within a page screenshot.
      Parameters:
      referenceImagePath - path to the reference image
      currentPageScreenshot - encoded current-page screenshot
      Returns:
      the matched x/y coordinates, or an empty list when no match is found

    • compareAgainstBaseline

      Boolean compareAgainstBaseline(org.openqa.selenium.WebDriver driver, org.openqa.selenium.By elementLocator, byte[] elementScreenshot, ImageProcessingActions.VisualValidationEngine visualValidationEngine, String referenceImagePath, String differencesImagePath)
      Compares an element screenshot against its visual baseline using the requested optional engine.
      Parameters:
      driver - active WebDriver instance
      elementLocator - locator of the element being compared
      elementScreenshot - encoded screenshot of the element
      visualValidationEngine - requested visual validation engine
      referenceImagePath - path to the saved reference image
      differencesImagePath - path prefix for a generated differences image
      Returns:
      true when the comparison passes or creates a new baseline

    • compareAgainstBaseline

      default Boolean compareAgainstBaseline(String elementLocatorName, byte[] elementScreenshot, ImageProcessingActions.VisualValidationEngine visualValidationEngine, String referenceImagePath, String differencesImagePath)
      Compares screenshot bytes against a visual baseline without requiring a Selenium WebDriver.

      This path is used by non-WebDriver backends such as Playwright. Providers that cannot compare raw screenshots may keep the default implementation, preserving compatibility with existing implementations.

      Parameters:
      elementLocatorName - stable element locator description used for diagnostics
      elementScreenshot - encoded screenshot of the element or page
      visualValidationEngine - requested visual validation engine
      referenceImagePath - path to the saved reference image
      differencesImagePath - path prefix for a generated differences image
      Returns:
      true when the comparison passes or creates a new baseline
      Throws:
      UnsupportedOperationException - when the provider does not support raw screenshot comparison

    • load

      void load()
      Loads any native libraries required by this provider.

    • compareScreenshotAgainstBaseline

      default VisualProcessingProvider.ScreenshotComparisonResult compareScreenshotAgainstBaseline(byte[] baselineImage, byte[] actualImage, List<int[]> maskRects, Integer maxDiffPixels, Double maxDiffPixelRatio)
      Compares raw screenshot bytes against a baseline image using a pixel-level diff, honoring optional mask rectangles and diff budgets. Used by the matchesScreenshot() visual-regression assertion.

      Providers that cannot perform a pixel diff may keep the default implementation.

      Parameters:
      baselineImage - encoded baseline (reference) image bytes
      actualImage - encoded actual (current) screenshot bytes
      maskRects - pixel-space [x, y, width, height] regions to exclude from comparison, or null
      maxDiffPixels - maximum allowed differing pixel count, or null to ignore this budget
      maxDiffPixelRatio - maximum allowed differing pixel ratio (0.0-1.0), or null to ignore this budget
      Returns:
      the comparison result
      Throws:
      UnsupportedOperationException - when the provider does not support pixel-diff screenshot comparison