! F add ReportByOpeningFiles and deprecate FileLauncherReporter

Co-Authored-By: Trillium Smith <[email protected]>
Co-Authored-By: 4dsherwood <[email protected]>
Co-Authored-By: Llewellyn Falco <[email protected]>

Author: 4 people

approvaltests/src/main/java/org/approvaltests/reporters/FileLauncherReporter.java

@@ -1,28 +1,9 @@
 package org.approvaltests.reporters;
 
-import com.spun.util.io.FileUtils;
-import com.spun.util.logger.SimpleLogger;
-import com.spun.util.tests.TestUtils;
-import org.approvaltests.core.ApprovalFailureReporter;
-
-public class FileLauncherReporter implements ApprovalFailureReporter
+/**
+ * @deprecated use ReportByOpeningFiles
+ */
+@Deprecated
+public class FileLauncherReporter extends ReportByOpeningFiles
 {
-  @Override
-  public boolean report(String received, String approved)
-  {
-    try
-    {
-      if (FileUtils.isNonEmptyFile(approved))
-      {
-        TestUtils.displayFile(approved);
-      }
-      TestUtils.displayFile(received);
-      return true;
-    }
-    catch (Exception e)
-    {
-      SimpleLogger.warning("Error launching file.", e);
-      return false;
-    }
-  }
 }

approvaltests/src/main/java/org/approvaltests/reporters/ReportByOpeningFiles.java

@@ -0,0 +1,28 @@
+package org.approvaltests.reporters;
+
+import com.spun.util.io.FileUtils;
+import com.spun.util.logger.SimpleLogger;
+import com.spun.util.tests.TestUtils;
+import org.approvaltests.core.ApprovalFailureReporter;
+
+public class ReportByOpeningFiles implements ApprovalFailureReporter
+{
+  @Override
+  public boolean report(String received, String approved)
+  {
+    try
+    {
+      if (FileUtils.isNonEmptyFile(approved))
+      {
+        TestUtils.displayFile(approved);
+      }
+      TestUtils.displayFile(received);
+      return true;
+    }
+    catch (Exception e)
+    {
+      SimpleLogger.warning("Error launching file.", e);
+      return false;
+    }
+  }
+}

internal_documentation/micro_features/ReportByOpeningFiles.md

@@ -0,0 +1,23 @@
+# `ReportByOpeningFiles` reporter
+
+The `ReportByOpeningFiles` class provides a simple mechanism to open approved and received files using the system's default application for their file type.
+
+## Purpose
+Allows users to visually inspect the received and approved files by automatically launching them on failure. This is useful when the file type corresponds to a tool that provides a good viewing or diffing experience, or as a fallback reporter.
+
+## Features
+- **Automatic File Launching**: Opens files using the default system application associated with the file extension.
+- **Conditional Approved File Launch**: Only attempts to open the approved file if it exists and is non-empty.
+- **Robust Error Handling**: Catches exceptions during launch and logs a warning instead of failing the test execution flow.
+
+## Behavior
+1. **report(received, approved)**: The main entry point for the reporter.
+2. **Checks Approved File**: Verifies if the `approved` file is a non-empty file.
+3. **Launches Approved File**: If the approved file exists and has content, it is opened using `TestUtils.displayFile(approved)`.
+4. **Launches Received File**: The `received` file is always opened using `TestUtils.displayFile(received)`.
+5. **Error Handling**: If any exception occurs during the process (e.g., file not found, no associated application), it is caught, logged as a warning, and the method returns `false`.
+6. **Success**: Returns `true` if the operation completes without exception.
+
+
+## Integration
+- Implements the `ApprovalFailureReporter` interface.