Package com.oorian.testing

Class SnapshotTester

java.lang.Object
com.oorian.testing.SnapshotTester
public class SnapshotTester extends Object
Snapshot testing utility for comparing component HTML output against saved baselines.

SnapshotTester captures the rendered HTML of Oorian Element objects and compares it against previously saved snapshots. This detects unintended changes in component rendering and makes it easy to review intentional changes.

Snapshot files are stored as .snap files in a configurable directory. On first run, the snapshot is automatically created. On subsequent runs, the current output is compared against the saved file.

Update mode: When enabled, mismatched snapshots are automatically overwritten with the current output instead of failing. Use this when you've made intentional changes and want to update all baselines.

Usage:


 // Create tester with snapshot directory
 SnapshotTester snapshots = new SnapshotTester("test/snapshots");

 // Compare element output against saved snapshot
 Div card = new Div();
 card.addClass("card");
 card.addElement(new H1("Title"));
 snapshots.assertMatchesSnapshot("user-card", card);

 // Compare raw HTML string
 snapshots.assertMatchesSnapshot("header-html", someHtmlString);

 // Update mode: overwrite all snapshots
 snapshots.setUpdateMode(true);
 snapshots.assertMatchesSnapshot("user-card", card); // saves instead of comparing
Since:
2.1
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

    • SnapshotTester

      public SnapshotTester(String snapshotDirectory)
      Constructs a new SnapshotTester with the specified snapshot directory.

      The directory will be created if it does not exist when snapshots are saved.

      Parameters:
      snapshotDirectory - the path to the directory for storing snapshot files

    • SnapshotTester

      public SnapshotTester(Path snapshotDirectory)
      Constructs a new SnapshotTester with the specified snapshot directory path.
      Parameters:
      snapshotDirectory - the path to the directory for storing snapshot files

  • Method Details

    • setUpdateMode

      public void setUpdateMode(boolean updateMode)
      Sets whether update mode is enabled.

      When update mode is true, mismatched snapshots are automatically overwritten with the current output instead of throwing SnapshotMismatchException. This is useful when intentional changes have been made and all baselines need updating.

      Parameters:
      updateMode - true to enable update mode

    • isUpdateMode

      public boolean isUpdateMode()
      Returns whether update mode is enabled.
      Returns:
      true if update mode is enabled

    • assertMatchesSnapshot

      public SnapshotResult assertMatchesSnapshot(String name, Element element)
      Asserts that an element's rendered HTML matches the saved snapshot.

      If no snapshot exists, the current output is saved as the new baseline and the result is SnapshotResult.NEW_SNAPSHOT. If a snapshot exists and matches, the result is SnapshotResult.MATCH. If it doesn't match and update mode is disabled, a SnapshotMismatchException is thrown.

      Parameters:
      name - the snapshot name (used as the filename without extension)
      element - the element to render and compare
      Returns:
      the result of the snapshot comparison
      Throws:
      SnapshotMismatchException - if the output doesn't match and update mode is off

    • assertMatchesSnapshot

      public SnapshotResult assertMatchesSnapshot(String name, String content)
      Asserts that a string matches the saved snapshot.

      If no snapshot exists, the content is saved as the new baseline. If a snapshot exists and matches, the result is SnapshotResult.MATCH. If it doesn't match and update mode is disabled, a SnapshotMismatchException is thrown.

      Parameters:
      name - the snapshot name (used as the filename without extension)
      content - the content to compare
      Returns:
      the result of the snapshot comparison
      Throws:
      SnapshotMismatchException - if the content doesn't match and update mode is off

    • updateSnapshot

      public void updateSnapshot(String name, Element element)
      Saves an element's rendered HTML as a snapshot without comparing.

      This overwrites any existing snapshot with the same name.

      Parameters:
      name - the snapshot name
      element - the element to render and save

    • updateSnapshot

      public void updateSnapshot(String name, String content)
      Saves a string as a snapshot without comparing.

      This overwrites any existing snapshot with the same name.

      Parameters:
      name - the snapshot name
      content - the content to save

    • snapshotExists

      public boolean snapshotExists(String name)
      Checks whether a snapshot file exists for the given name.
      Parameters:
      name - the snapshot name
      Returns:
      true if a snapshot file exists

    • deleteSnapshot

      public boolean deleteSnapshot(String name)
      Deletes a snapshot file.
      Parameters:
      name - the snapshot name to delete
      Returns:
      true if the file was deleted, false if it didn't exist

    • getSnapshotDirectory

      public Path getSnapshotDirectory()
      Returns the path to the snapshot directory.
      Returns:
      the snapshot directory path