Package net.fabricmc.fabric.api.client.gametest.v1.screenshot

Interface TestScreenshotComparisonOptions

All Superinterfaces:
TestScreenshotCommonOptions<TestScreenshotComparisonOptions>
@NonExtendable public interface TestScreenshotComparisonOptions extends TestScreenshotCommonOptions<TestScreenshotComparisonOptions>
Options for comparing screenshots.

By default, screenshots are compared with a fuzzy comparison which allows screenshots to be 0.5% different from the template image. See TestScreenshotComparisonAlgorithm.defaultAlgorithm() for details on how this is implemented. To change the threshold for how different the screenshot can be, set the algorithm to TestScreenshotComparisonAlgorithm.meanSquaredDifference(float). To force the screenshot to be exactly the same as your template, use TestScreenshotComparisonAlgorithm.exact(). It is recommended to stick with fuzzy matching unless you specifically require an exact match, because the exact screenshot can vary slightly on different frames and in rare cases other factors such as the GPU/driver version.

Template images must be fully opaque, this API will throw if the template image has any transparent pixels.

Template images loaded from a path are expected to be in the templates directory inside the resources directory of the mod which registered the gametest. If the template image is not found then the screenshot will be saved to the templates directory so that it can be used next time the gametest is run. Your test mod's resources directory is in the fabric.client.gametest.testModResourcesPath system property which is set by Loom by default. You may set this system property to override the location of the test mod resources directory. If this system property is unset and the template image is not found, then the test will fail.

  • Method Details

    • of

      static TestScreenshotComparisonOptions of(String templateImage)
      Load the template image from a path. The template image is expected to be in the templates directory inside the resources directory of the mod which registered the gametest.
      Parameters:
      templateImage - The template image path
      Returns:
      The new screenshot comparison options instance

    • of

      static TestScreenshotComparisonOptions of(NativeImage templateImage)
      Use the given image as the template image.
      Parameters:
      templateImage - The template image
      Returns:
      The new screenshot comparison options instance

    • saveWithFileName

      TestScreenshotComparisonOptions saveWithFileName(String fileName)
      Additionally save the screenshot which was compared against. This method works as if by calling ClientGameTestContext.takeScreenshot(TestScreenshotOptions) with these screenshot options, except that the screenshot saved is from the same render of the game as the one that is compared against in this screenshot comparison.
      Parameters:
      fileName - The name of the screenshot to save
      Returns:
      This screenshot comparison options instance

    • withAlgorithm

      TestScreenshotComparisonOptions withAlgorithm(TestScreenshotComparisonAlgorithm algorithm)
      Changes the algorithm used to compare the template image with the screenshot. See class documentation for details.
      Parameters:
      algorithm - The new algorithm
      Returns:
      This screenshot comparison options instance

    • withGrayscale

      TestScreenshotComparisonOptions withGrayscale()
      Compares images in grayscale rather than in color. Comparing in grayscale is typically faster but has the obvious disadvantage of two colors with different hues but the same brightness being treated as the same.
      Returns:
      This screenshot comparison options instance

    • withRegion

      TestScreenshotComparisonOptions withRegion(int x, int y, int width, int height)
      Only considers a certain region of the screenshot for comparison. When used with assertScreenshotEquals, asserts that the template image is equal to the given region of the screenshot. When used with assertScreenshotContains, asserts that the template image is contained within the given region of the screenshot.
      Parameters:
      x - The minimum X position in the region
      y - The minimum Y position in the region
      width - The width of the region
      height - The height of the region
      Returns:
      This screenshot comparison options instance