Module org.testfx

Package org.testfx.util

Class DebugUtils

java.lang.Object

org.testfx.util.DebugUtils

public final class DebugUtils
extends Object

Utility class for displaying additional info, running code, or capturing an image of a test whenever a test fails using FxAssert.verifyThat(Node, Matcher) or its related methods.

It is possible to create completely customized error messages by chaining functions together using compose(Function[]) or one can use the standard provided handlers such as informedErrorMessage(FxRobot), informedErrorMessage(FxRobot, String), etc. All indent parameters in methods are used to specify the spacing to insert in order to offset values. The default indent value is three spaces (e.g. " ").

When a test fails, an image of the screen at the time of failure can be captured and saved to a PNG file. DebugUtils provides support for a number of image sizes: the full screen, a window, an area of the screen (i.e. bounds), or an individual node. Use the convenience methods prefixed by "save" (e.g. saveScreenshot(String)) to capture and save images. The image path will be printed using insertContent(String, Object) and will appear in the error message. For your own custom handler, use saveTestImage(Function, Supplier, String), one of the "capture"-prefixed methods, and a Supplier<Path> that determines where to save the image to.

This class uses the concept of combining functions together in order to add additional information to the error message of an AssertionError thrown by a failing test.

Example:

 // Template:
 compose(
      // insert a header for the section of error information
      insertHeader(headerText),
      // insert the specific content that falls under this header
      insertContent(contentHeading, content),
      insertContent(contentHeading2, contentIterable),
      insertContent(contentHeading3, contentArray),
      insertContent(contentHeading4, contentStream),

      // insert a header for the section of error information
      insertHeader(headerText),
      // insert the specific content that falls under this header
      insertContent(contentHeading5, contentStream2),
      insertContent(contentHeading6, contentStream3));

 // Example:
 compose(
      insertHeader("Context:"),
      showKeysPressedAtTestFailure(this),
      showMouseButtonsPressedAtTestFailure(this),
      showFiredEvents(),
      saveScreenshot());

 // is equivalent to:

 informedErrorMessage(this);

 // as it uses all of the default arguments.
 

Method Summary

Modifier and Type	Method	Description
static Function<CaptureSupport,javafx.scene.image.Image>	captureBounds(javafx.geometry.Bounds bounds)
static Function<CaptureSupport,javafx.scene.image.Image>	captureBounds(javafx.geometry.Rectangle2D bounds)
static Function<CaptureSupport,javafx.scene.image.Image>	captureNode(javafx.scene.Node node)
static Function<CaptureSupport,javafx.scene.image.Image>	captureScreenshot()
static Function<CaptureSupport,javafx.scene.image.Image>	captureScreenshot(int screenIndex)
static Function<CaptureSupport,javafx.scene.image.Image>	captureScreenshot(javafx.stage.Screen screen)
static Function<CaptureSupport,javafx.scene.image.Image>	captureWindow()	Captures the registered stage.
static Function<CaptureSupport,javafx.scene.image.Image>	captureWindow(javafx.stage.Window window)
static Function<StringBuilder,StringBuilder>	compose(Function<StringBuilder,StringBuilder>... functions)	Composes multiple functions together into one.
static Supplier<Path>	defaultImagePath()	Returns defaultImagePath(String, int) with "testfx-test" as the test name and gets and increments the next photo number.
static Supplier<Path>	defaultImagePath(String testName)	Returns () -> Paths.get(testName + " - 0.png");
static Supplier<Path>	defaultImagePath(String testName, int photoNumber)	Returns () -> Paths.get(testName + " - " photoNumber + ".png");
static Function<StringBuilder,StringBuilder>	informedErrorMessage(String headerText, boolean takeScreenshot, boolean showFiredEvents, FxRobot robot, boolean showKeysPressed, boolean showMouseButtonsPressed)	Convenience method for insertHeader(String) using "Context:" as the header text and then, via insertContent(String, Object), composes showKeysPressedAtTestFailure(FxRobot), showMouseButtonsPressedAtTestFailure(FxRobot), and showFiredEvents() together in their given order, depending on what the booleans are.
static Function<StringBuilder,StringBuilder>	informedErrorMessage(FxRobot robot)	Convenience method for informedErrorMessage(String, boolean, boolean, FxRobot, boolean, boolean) with all booleans set to true and the header text set to "Context:".
static Function<StringBuilder,StringBuilder>	informedErrorMessage(FxRobot robot, String headerText)	Convenience method for informedErrorMessage(String, boolean, boolean, FxRobot, boolean, boolean) with all booleans set to true.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Iterable<?> contentIter)	Inserts the heading on a newline followed by two default indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Iterable<?> contentIter, String indent)	Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Object content)	Inserts the heading on a newline followed by two default indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Object[] contentArray)	Inserts the heading on a newline followed by two default indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Object[] contentArray, String indent)	Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Object content, String indent)	Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Stream<?> contentStream)	Inserts the heading on a newline followed by two default indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertContent(String contentHeading, Stream<?> contentStream, String indent)	Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading.
static Function<StringBuilder,StringBuilder>	insertHeader(String headerText)	Inserts a header on a newline followed by the default indent; useful for specifying a section in the error message.
static Function<StringBuilder,StringBuilder>	insertHeader(String headerText, String indent)	Inserts a header on a newline followed by the given indent; useful for specifying a section in the error message.
static Function<StringBuilder,StringBuilder>	runCode(Runnable runnable)	Ignores the given StringBuilder and just runs the given code block.
static Function<StringBuilder,StringBuilder>	saveBounds(javafx.geometry.Bounds bounds)	Saves the captured image based on the given bounds using defaultImagePath() and the DEFAULT_INDENT.
static Function<StringBuilder,StringBuilder>	saveBounds(javafx.geometry.Bounds bounds, String testName, int photoNumber)	Saves the captured image based on the given bounds to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveBounds(javafx.geometry.Bounds bounds, Supplier<Path> capturedImagePath, String indent)	Saves the captured image based on the given bounds to the supplied path.
static Function<StringBuilder,StringBuilder>	saveBounds(javafx.geometry.Rectangle2D bounds)	Saves the captured image based on the given bounds using defaultImagePath() and the DEFAULT_INDENT.
static Function<StringBuilder,StringBuilder>	saveBounds(javafx.geometry.Rectangle2D bounds, String testName, int photoNumber)	Saves the captured image based on the given bounds to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveBounds(javafx.geometry.Rectangle2D bounds, Supplier<Path> capturedImagePath, String indent)	Saves the captured image based on the given bounds to the supplied path.
static Function<StringBuilder,StringBuilder>	saveNode(javafx.scene.Node node)	Saves the captured node using defaultImagePath() and the DEFAULT_INDENT.
static Function<StringBuilder,StringBuilder>	saveNode(javafx.scene.Node node, String testName, int photoNumber)	Saves the captured node image to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveNode(javafx.scene.Node node, Supplier<Path> capturedImagePath, String indent)	Saves the captured node to the supplied path.
static Function<StringBuilder,StringBuilder>	saveScreenshot()	Saves the captured primary screen image using defaultImagePath() and the DEFAULT_INDENT.
static Function<StringBuilder,StringBuilder>	saveScreenshot(int screenIndex, String testName, int photoNumber)	Saves the captured screenshot of the screen at the given index in Screen.getScreens()} to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveScreenshot(int screenIndex, Supplier<Path> capturedImagePath, String indent)	Saves the captured screenshot of the screen at the given index in Screen.getScreens()} to the supplied path.
static Function<StringBuilder,StringBuilder>	saveScreenshot(String testName)	Saves the captured screenshot of the primary screen to "testName - 0.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveScreenshot(String testName, int photoNumber)	Saves the captured screenshot of the primary screen to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveScreenshot(Supplier<Path> capturedImagePath, String indent)	Saves the captured screenshot of the primary screen to the supplied path.
static Function<StringBuilder,StringBuilder>	saveScreenshot(javafx.stage.Screen screen, String testName, int photoNumber)	Saves the captured screenshot of the screen to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveScreenshot(javafx.stage.Screen screen, Supplier<Path> capturedImagePath, String indent)	Saves the captured screenshot of the screen to the supplied path.
static Function<StringBuilder,StringBuilder>	saveTestImage(Function<CaptureSupport,javafx.scene.image.Image> captureImage, Supplier<Path> capturedImagePath, String indent)	Saves the captured image to the supplied path.
static Function<StringBuilder,StringBuilder>	saveWindow()	Saves the captured registered stage image using defaultImagePath() and the DEFAULT_INDENT.
static Function<StringBuilder,StringBuilder>	saveWindow(String testName, int photoNumber)	Saves the captured registered stage "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveWindow(Supplier<Path> capturedImagePath, String indent)	Saves the captured registered stage to the supplied path.
static Function<StringBuilder,StringBuilder>	saveWindow(javafx.stage.Window window, String testName, int photoNumber)	Saves the captured window to "testName - photoNumber.png" (e.g.
static Function<StringBuilder,StringBuilder>	saveWindow(javafx.stage.Window window, Supplier<Path> capturedImagePath, String indent)	Saves the captured window to the supplied path.
static Function<StringBuilder,StringBuilder>	showFiredEvents()	Via insertContent(String, Object): shows all events that were fired since the start of the test.
static Function<StringBuilder,StringBuilder>	showFiredEvents(String indent)
static Function<StringBuilder,StringBuilder>	showFiredEvents(List<javafx.event.Event> events)
static Function<StringBuilder,StringBuilder>	showFiredEvents(List<javafx.event.Event> events, String indent)
static Function<StringBuilder,StringBuilder>	showFiredEvents(FiredEvents events)	Via insertContent(String, Object): shows all events that were fired since the start of the test.
static Function<StringBuilder,StringBuilder>	showFiredEvents(FiredEvents events, String indent)
static Function<StringBuilder,StringBuilder>	showKeysPressedAtTestFailure(FxRobot robot)	Via insertContent(String, Object): shows the keys that were pressed when the test failed.
static Function<StringBuilder,StringBuilder>	showKeysPressedAtTestFailure(FxRobot robot, String indent)
static Function<StringBuilder,StringBuilder>	showMouseButtonsPressedAtTestFailure(FxRobot robot)	Via insertContent(String, Object): shows the MouseButtons that were pressed when the test failed.
static Function<StringBuilder,StringBuilder>	showMouseButtonsPressedAtTestFailure(FxRobot robot, String indent)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

compose

@SafeVarargs
public static Function<StringBuilder,StringBuilder> compose(Function<StringBuilder,StringBuilder>... functions)

Composes multiple functions together into one. The functions are called in the order that they appear in the array. That is, functions[0] is run first, functions[1] is run second, etc.

runCode

public static Function<StringBuilder,StringBuilder> runCode(Runnable runnable)

Ignores the given StringBuilder and just runs the given code block.

insertHeader

public static Function<StringBuilder,StringBuilder> insertHeader(String headerText)

Inserts a header on a newline followed by the default indent; useful for specifying a section in the error message.

insertHeader

public static Function<StringBuilder,StringBuilder> insertHeader(String headerText,
                                                                       String indent)

Inserts a header on a newline followed by the given indent; useful for specifying a section in the error message.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Object content)

Inserts the heading on a newline followed by two default indents followed by the given contentHeading. Then, inserts a newline followed by three default indents followed by the content itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Object content,
                                                                        String indent)

Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading. Then, inserts a newline followed by three of the given indents followed by the content itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Iterable<?> contentIter)

Inserts the heading on a newline followed by two default indents followed by the given contentHeading. Then, for each item in the given iterable, inserts a newline followed by three default indents followed by the list item itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Iterable<?> contentIter,
                                                                        String indent)

Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading. Then, for each item in the given iterable, inserts a newline followed by three of the given indents followed by the list item itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Object[] contentArray)

Inserts the heading on a newline followed by two default indents followed by the given contentHeading. Then, for each item in the given array, inserts a newline followed by three default indents followed by the array item itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Object[] contentArray,
                                                                        String indent)

Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading. Then, for each item in the given array, inserts a newline followed by three of the given indents followed by the array item itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Stream<?> contentStream)

Inserts the heading on a newline followed by two default indents followed by the given contentHeading. Then, for each item in the given stream, inserts a newline followed by three default indents followed by the item itself.

insertContent

public static Function<StringBuilder,StringBuilder> insertContent(String contentHeading,
                                                                        Stream<?> contentStream,
                                                                        String indent)

Inserts the heading on a newline followed by two of the given indents followed by the given contentHeading. Then, for each item in the given stream, inserts a newline followed by three of the given indents followed by the item itself.

showKeysPressedAtTestFailure

public static Function<StringBuilder,StringBuilder> showKeysPressedAtTestFailure(FxRobot robot)

Via insertContent(String, Object): shows the keys that were pressed when the test failed.

showKeysPressedAtTestFailure

public static Function<StringBuilder,StringBuilder> showKeysPressedAtTestFailure(FxRobot robot,
                                                                                       String indent)

showMouseButtonsPressedAtTestFailure

public static Function<StringBuilder,StringBuilder> showMouseButtonsPressedAtTestFailure(FxRobot robot)

Via insertContent(String, Object): shows the MouseButtons that were pressed when the test failed.

showMouseButtonsPressedAtTestFailure

public static Function<StringBuilder,StringBuilder> showMouseButtonsPressedAtTestFailure(FxRobot robot,
                                                                                               String indent)

showFiredEvents

public static Function<StringBuilder,StringBuilder> showFiredEvents()

Via insertContent(String, Object): shows all events that were fired since the start of the test. Note: only events stored in FxToolkitContext.getFiredEvents() will be shown.

showFiredEvents

public static Function<StringBuilder,StringBuilder> showFiredEvents(String indent)

showFiredEvents

public static Function<StringBuilder,StringBuilder> showFiredEvents(FiredEvents events)

Via insertContent(String, Object): shows all events that were fired since the start of the test.

showFiredEvents

public static Function<StringBuilder,StringBuilder> showFiredEvents(FiredEvents events,
                                                                          String indent)

showFiredEvents

public static Function<StringBuilder,StringBuilder> showFiredEvents(List<javafx.event.Event> events)

showFiredEvents

public static Function<StringBuilder,StringBuilder> showFiredEvents(List<javafx.event.Event> events,
                                                                          String indent)

captureScreenshot

public static Function<CaptureSupport,javafx.scene.image.Image> captureScreenshot()

captureScreenshot

public static Function<CaptureSupport,javafx.scene.image.Image> captureScreenshot(int screenIndex)

captureScreenshot

public static Function<CaptureSupport,javafx.scene.image.Image> captureScreenshot(javafx.stage.Screen screen)

captureWindow

public static Function<CaptureSupport,javafx.scene.image.Image> captureWindow()

Captures the registered stage.

captureWindow

public static Function<CaptureSupport,javafx.scene.image.Image> captureWindow(javafx.stage.Window window)

captureBounds

public static Function<CaptureSupport,javafx.scene.image.Image> captureBounds(javafx.geometry.Bounds bounds)

captureBounds

public static Function<CaptureSupport,javafx.scene.image.Image> captureBounds(javafx.geometry.Rectangle2D bounds)

captureNode

public static Function<CaptureSupport,javafx.scene.image.Image> captureNode(javafx.scene.Node node)

defaultImagePath

public static Supplier<Path> defaultImagePath()

Returns defaultImagePath(String, int) with "testfx-test" as the test name and gets and increments the next photo number.

defaultImagePath

public static Supplier<Path> defaultImagePath(String testName)

Returns () -> Paths.get(testName + " - 0.png");

defaultImagePath

public static Supplier<Path> defaultImagePath(String testName,
                                              int photoNumber)

Returns () -> Paths.get(testName + " - " photoNumber + ".png");

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot()

Saves the captured primary screen image using defaultImagePath() and the DEFAULT_INDENT.

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(String testName)

Saves the captured screenshot of the primary screen to "testName - 0.png" (e.g. "button_has_label - 0.png").

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(String testName,
                                                                         int photoNumber)

Saves the captured screenshot of the primary screen to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(Supplier<Path> capturedImagePath,
                                                                         String indent)

Saves the captured screenshot of the primary screen to the supplied path.

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(javafx.stage.Screen screen,
                                                                         String testName,
                                                                         int photoNumber)

Saves the captured screenshot of the screen to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(javafx.stage.Screen screen,
                                                                         Supplier<Path> capturedImagePath,
                                                                         String indent)

Saves the captured screenshot of the screen to the supplied path.

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(int screenIndex,
                                                                         String testName,
                                                                         int photoNumber)

Saves the captured screenshot of the screen at the given index in Screen.getScreens()} to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveScreenshot

public static Function<StringBuilder,StringBuilder> saveScreenshot(int screenIndex,
                                                                         Supplier<Path> capturedImagePath,
                                                                         String indent)

Saves the captured screenshot of the screen at the given index in Screen.getScreens()} to the supplied path.

saveWindow

public static Function<StringBuilder,StringBuilder> saveWindow()

Saves the captured registered stage image using defaultImagePath() and the DEFAULT_INDENT.

saveWindow

public static Function<StringBuilder,StringBuilder> saveWindow(String testName,
                                                                     int photoNumber)

Saves the captured registered stage "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveWindow

public static Function<StringBuilder,StringBuilder> saveWindow(Supplier<Path> capturedImagePath,
                                                                     String indent)

Saves the captured registered stage to the supplied path.

saveWindow

public static Function<StringBuilder,StringBuilder> saveWindow(javafx.stage.Window window,
                                                                     String testName,
                                                                     int photoNumber)

Saves the captured window to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveWindow

public static Function<StringBuilder,StringBuilder> saveWindow(javafx.stage.Window window,
                                                                     Supplier<Path> capturedImagePath,
                                                                     String indent)

Saves the captured window to the supplied path.

saveBounds

public static Function<StringBuilder,StringBuilder> saveBounds(javafx.geometry.Bounds bounds)

Saves the captured image based on the given bounds using defaultImagePath() and the DEFAULT_INDENT.

saveBounds

public static Function<StringBuilder,StringBuilder> saveBounds(javafx.geometry.Bounds bounds,
                                                                     String testName,
                                                                     int photoNumber)

Saves the captured image based on the given bounds to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveBounds

public static Function<StringBuilder,StringBuilder> saveBounds(javafx.geometry.Bounds bounds,
                                                                     Supplier<Path> capturedImagePath,
                                                                     String indent)

Saves the captured image based on the given bounds to the supplied path.

saveBounds

public static Function<StringBuilder,StringBuilder> saveBounds(javafx.geometry.Rectangle2D bounds)

Saves the captured image based on the given bounds using defaultImagePath() and the DEFAULT_INDENT.

saveBounds

public static Function<StringBuilder,StringBuilder> saveBounds(javafx.geometry.Rectangle2D bounds,
                                                                     String testName,
                                                                     int photoNumber)

Saves the captured image based on the given bounds to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveBounds

public static Function<StringBuilder,StringBuilder> saveBounds(javafx.geometry.Rectangle2D bounds,
                                                                     Supplier<Path> capturedImagePath,
                                                                     String indent)

Saves the captured image based on the given bounds to the supplied path.

saveNode

public static Function<StringBuilder,StringBuilder> saveNode(javafx.scene.Node node)

Saves the captured node using defaultImagePath() and the DEFAULT_INDENT.

saveNode

public static Function<StringBuilder,StringBuilder> saveNode(javafx.scene.Node node,
                                                                   String testName,
                                                                   int photoNumber)

Saves the captured node image to "testName - photoNumber.png" (e.g. "button_has_label - 2.png").

saveNode

public static Function<StringBuilder,StringBuilder> saveNode(javafx.scene.Node node,
                                                                   Supplier<Path> capturedImagePath,
                                                                   String indent)

Saves the captured node to the supplied path.

saveTestImage

public static Function<StringBuilder,StringBuilder> saveTestImage(Function<CaptureSupport,javafx.scene.image.Image> captureImage,
                                                                        Supplier<Path> capturedImagePath,
                                                                        String indent)

Saves the captured image to the supplied path.

informedErrorMessage

public static Function<StringBuilder,StringBuilder> informedErrorMessage(FxRobot robot)

Convenience method for informedErrorMessage(String, boolean, boolean, FxRobot, boolean, boolean) with all booleans set to true and the header text set to "Context:".

informedErrorMessage

public static Function<StringBuilder,StringBuilder> informedErrorMessage(FxRobot robot,
                                                                               String headerText)

Convenience method for informedErrorMessage(String, boolean, boolean, FxRobot, boolean, boolean) with all booleans set to true.

informedErrorMessage

public static Function<StringBuilder,StringBuilder> informedErrorMessage(String headerText,
                                                                               boolean takeScreenshot,
                                                                               boolean showFiredEvents,
                                                                               FxRobot robot,
                                                                               boolean showKeysPressed,
                                                                               boolean showMouseButtonsPressed)

Convenience method for insertHeader(String) using "Context:" as the header text and then, via insertContent(String, Object), composes showKeysPressedAtTestFailure(FxRobot), showMouseButtonsPressedAtTestFailure(FxRobot), and showFiredEvents() together in their given order, depending on what the booleans are.