Add code to save the HTML of the page being screenshotted during the `take_screenshot` method

that is enabled by a new environment variable - RAILS_SYSTEM_TESTING_SCREENSHOT_HTML=1

Add the ability to call `take_screenshot` more than once in a single test by prefixing the name of
the image file with a counter that is incremented on every `take_screenshot` call.  This allows a
developer to see their pages in sequence when trying to debug test errors.  This does not affect
the failure case where the prefix remains 'failures'

1 files changed, 46 insertions, 6 deletions

diff --git a/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb b/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb
index 056ce51a61..cba053ee4c 100644
--- a/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb
+++ b/actionpack/lib/action_dispatch/system_testing/test_helpers/screenshot_helper.rb
@@ -9,10 +9,16 @@ module ActionDispatch
         #
         # +take_screenshot+ can be used at any point in your system tests to take
         # a screenshot of the current state. This can be useful for debugging or
-        # automating visual testing.
+        # automating visual testing. You can take multiple screenshots per test
+        # to investigate changes at different points during your test. These will be
+        # named with a sequential prefix (or 'failed' for failing tests)
         #
         # The screenshot will be displayed in your console, if supported.
         #
+        # You can set the +RAILS_SYSTEM_TESTING_SCREENSHOT_HTML+ environment variable to
+        # save the HTML from the page that is being screenhoted so you can investigate the
+        # elements on the page at the time of the screenshot
+        #
         # You can set the +RAILS_SYSTEM_TESTING_SCREENSHOT+ environment variable to
         # control the output. Possible values are:
         # * [+simple+ (default)]    Only displays the screenshot path.
@@ -22,6 +28,8 @@ module ActionDispatch
         # * [+artifact+]            Display the screenshot in the terminal, using the terminal
         #                           artifact format (https://buildkite.github.io/terminal-to-html/inline-images/).
         def take_screenshot
+          increment_unique
+          save_html if save_html?
           save_image
           puts display_image
         end
@@ -38,17 +46,48 @@ module ActionDispatch
         end
 
         private
+          attr_accessor :_screenshot_counter
+
+          def save_html?
+            ENV["RAILS_SYSTEM_TESTING_SCREENSHOT_HTML"] == "1"
+          end
+
+          def increment_unique
+            @_screenshot_counter ||= 0
+            @_screenshot_counter += 1
+          end
+
+          def unique
+            failed? ? "failures" : (_screenshot_counter || 0).to_s
+          end
+
           def image_name
-            name = method_name[0...225]
-            failed? ? "failures_#{name}" : name
+            name = "#{unique}_#{method_name}"
+            name[0...225]
           end
 
           def image_path
-            @image_path ||= absolute_image_path.to_s
+            absolute_image_path.to_s
+          end
+
+          def html_path
+            absolute_html_path.to_s
+          end
+
+          def absolute_path
+            Rails.root.join("tmp/screenshots/#{image_name}")
           end
 
           def absolute_image_path
-            Rails.root.join("tmp/screenshots/#{image_name}.png")
+            "#{absolute_path}.png"
+          end
+
+          def absolute_html_path
+            "#{absolute_path}.html"
+          end
+
+          def save_html
+            page.save_page(absolute_html_path)
           end
 
           def save_image
@@ -66,7 +105,8 @@ module ActionDispatch
           end
 
           def display_image
-            message = +"[Screenshot]: #{image_path}\n"
+            message = +"[Screenshot Image]: #{image_path}\n"
+            message << +"[Screenshot HTML]: #{html_path}\n" if save_html?
 
             case output_type
             when "artifact"