Add configurable mismatch template path

Author: mortenvp

NEWS.rst

@@ -6,7 +6,9 @@ every change, see the Git log.
 
 Latest
 ------
-* tbd
+* Minor: Added ``set_mismatch_template()`` to configure the mismatch HTML template path.
+* Minor: Custom mismatch template paths now fail if they cannot be resolved.
+* Minor: Added template format validation for ``oldText`` and ``newText`` markers.
 
 2.0.0
 -----

README.rst

@@ -8,6 +8,48 @@ Overview
 datarecorder is a simple C++ library that is meant to provide simple helper
 functions to ease sometimes tedious testing tasks.
 
+Build and test
+==============
+
+Configure::
+
+    ./waf configure
+
+Build::
+
+    ./waf build
+
+Run tests::
+
+    ./waf build --run_tests
+
+Mismatch template
+=================
+
+By default, datarecorder will try to find this template:
+
+- ``visualizer/recording_diff.html``
+
+You can override this with::
+
+    recorder.set_mismatch_template("path/to/recording_diff.html");
+
+If the provided path is relative, datarecorder resolves it by searching
+backwards from the current working directory.
+
+If you provide a custom mismatch template path and it cannot be found,
+recording will fail.
+
+Template requirements
+---------------------
+
+The template must contain both of these JavaScript markers (using backticks)::
+
+    const oldText = `...`;
+    const newText = `...`;
+
+These placeholders are replaced with recording data and mismatch data.
+
 License
 -------
 The stub library is released under the BSD license, see the LICENSE.rst file.

src/datarecorder/datarecorder.hpp

@@ -119,6 +119,20 @@ class datarecorder
         m_recording_filename = filename;
     }
 
+    /// Set the mismatch template used for mismatch HTML output.
+    ///
+    /// If this path is relative, it will be resolved by searching backwards
+    /// from the current working directory.
+    ///
+    /// If this path is provided and cannot be found, recording will fail.
+    void set_mismatch_template(std::filesystem::path mismatch_template)
+    {
+        VERIFY(!mismatch_template.empty(),
+               "Mismatch template path must not be empty", mismatch_template);
+
+        m_mismatch_template = mismatch_template;
+    }
+
     /// Set the callback that will be called when a mismatch is found.
     ///
     /// If no mismatch handler is set, a default mismatch handler will be used.
@@ -237,33 +251,43 @@ class datarecorder
 
     void determine_mismatch_handler()
     {
-        auto visualizer = find_relative_path("visualizer/recording_diff.html");
+        tl::expected<std::filesystem::path, poke::error> mismatch_template =
+            find_relative_path(
+                m_mismatch_template.value_or("visualizer/recording_diff.html"));
 
-        if (visualizer)
+        if (mismatch_template)
         {
             m_monitor.log(poke::log_level::debug,
-                          poke::log::str{"message", "Using diff visualizer"},
-                          poke::log::str{"path", visualizer->string()});
+                          poke::log::str{"message", "Using mismatch template"},
+                          poke::log::str{"path", mismatch_template->string()});
 
-            m_on_mismatch = [this, visualizer](mismatch_info mismatch)
+            m_on_mismatch = [this, mismatch_template = *mismatch_template](
+                                mismatch_info mismatch)
             {
                 // Call the diff handler
-                return diff_mismatch_handler(*visualizer, mismatch);
+                return diff_mismatch_handler(mismatch_template, mismatch);
             };
+            return;
         }
-        else
-        {
-            m_monitor.log(
-                poke::log_level::debug,
-                poke::log::str{"message", "Using default mismatch handler"},
-                poke::log::str{"path", visualizer.error().message()});
 
-            m_on_mismatch = [this](mismatch_info mismatch)
-            {
-                // Call the default handler
-                return default_mismatch_handler(mismatch);
-            };
+        if (m_mismatch_template)
+        {
+            VERIFY(mismatch_template,
+                   "Could not find configured mismatch template",
+                   m_mismatch_template.value(),
+                   mismatch_template.error().message());
         }
+
+        m_monitor.log(
+            poke::log_level::debug,
+            poke::log::str{"message", "Using default mismatch handler"},
+            poke::log::str{"path", mismatch_template.error().message()});
+
+        m_on_mismatch = [this](mismatch_info mismatch)
+        {
+            // Call the default handler
+            return default_mismatch_handler(mismatch);
+        };
     }
 
     auto determine_mismatch_path() -> std::filesystem::path
@@ -435,6 +459,18 @@ class datarecorder
         std::regex oldTextPattern(R"((const\s+oldText\s*=\s*`)([^`]*)(`;))");
         std::regex newTextPattern(R"((const\s+newText\s*=\s*`)([^`]*)(`;))");
 
+        if (!std::regex_search(file_content, oldTextPattern) ||
+            !std::regex_search(file_content, newTextPattern))
+        {
+            return poke::make_error(
+                std::make_error_code(std::errc::invalid_argument),
+                poke::log::str{"message",
+                               "Mismatch template must contain both `const "
+                               "oldText = `...`;` "
+                               "and `const newText = `...`;` markers"},
+                poke::log::str{"template_path", recording_diff_html.string()});
+        }
+
         file_content = std::regex_replace(file_content, oldTextPattern,
                                           "$1" + escaped_recording_data + "$3");
         file_content = std::regex_replace(file_content, newTextPattern,
@@ -479,6 +515,7 @@ class datarecorder
 
     std::optional<std::string> m_recording_filename;
     std::optional<std::filesystem::path> m_recording_dir;
+    std::optional<std::filesystem::path> m_mismatch_template;
     std::optional<std::function<poke::error(mismatch_info)>> m_on_mismatch;
 };