Add support for screenshots

This change adds support, tests, and documentation for the screenshot
helper.

If taking screenshots is supported by the driver (for example Rack Test
doesn't support screenshots) then a screenshot will be taken if the test
fails.

6 files changed, 81 insertions, 2 deletions

diff --git a/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb b/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb
index 84941a9929..e40088970a 100644
--- a/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb
+++ b/actionpack/lib/system_testing/driver_adapters/capybara_driver.rb
@@ -52,6 +52,10 @@ module SystemTesting
       def call
         Capybara.default_driver = @name
       end
+
+      def supports_screenshots?
+        @name != :rack_test
+      end
     end
   end
 end
diff --git a/actionpack/lib/system_testing/driver_adapters/rails_selenium_driver.rb b/actionpack/lib/system_testing/driver_adapters/rails_selenium_driver.rb
index 77533bf39b..723de3de48 100644
--- a/actionpack/lib/system_testing/driver_adapters/rails_selenium_driver.rb
+++ b/actionpack/lib/system_testing/driver_adapters/rails_selenium_driver.rb
@@ -65,6 +65,10 @@ module SystemTesting
         setup
       end
 
+      def supports_screenshots?
+        true
+      end
+
       private
         def registration
           register_browser_driver
diff --git a/actionpack/lib/system_testing/test_helper.rb b/actionpack/lib/system_testing/test_helper.rb
index 2027a55d90..0ca4f792cb 100644
--- a/actionpack/lib/system_testing/test_helper.rb
+++ b/actionpack/lib/system_testing/test_helper.rb
@@ -3,8 +3,9 @@ require 'system_testing/test_helpers'
 
 module SystemTesting
   module TestHelper # :nodoc:
-    include TestHelpers::FormHelper
     include TestHelpers::Assertions
+    include TestHelpers::FormHelper
+    include TestHelpers::ScreenshotHelper
     include Capybara::DSL
 
     Capybara.app = Rack::Builder.new do
@@ -14,6 +15,7 @@ module SystemTesting
     end
 
     def after_teardown
+      take_screenshot if supported?
       Capybara.reset_sessions!
       super
     end
diff --git a/actionpack/lib/system_testing/test_helpers.rb b/actionpack/lib/system_testing/test_helpers.rb
index 074a45d5c8..3c528a6953 100644
--- a/actionpack/lib/system_testing/test_helpers.rb
+++ b/actionpack/lib/system_testing/test_helpers.rb
@@ -2,7 +2,8 @@ module SystemTesting
   module TestHelpers
     extend ActiveSupport::Autoload
 
-    autoload :FormHelper
     autoload :Assertions
+    autoload :FormHelper
+    autoload :ScreenshotHelper
   end
 end
diff --git a/actionpack/lib/system_testing/test_helpers/screenshot_helper.rb b/actionpack/lib/system_testing/test_helpers/screenshot_helper.rb
new file mode 100644
index 0000000000..a74ebb8cae
--- /dev/null
+++ b/actionpack/lib/system_testing/test_helpers/screenshot_helper.rb
@@ -0,0 +1,48 @@
+module SystemTesting
+  module TestHelpers
+    # Screenshot helper for system testing
+    module ScreenshotHelper
+      # Takes a screenshot of the current page in the browser if the system
+      # test driver supports screenshots and the test failed.
+      #
+      # Additionally +take_screenshot+ can be used within your tests at points
+      # you want to take a screenshot if the driver supports screenshots. The
+      # Rack Test driver does not support screenshots.
+      #
+      # You can check of the driver supports screenshots by running
+      #
+      #   Rails::SystemTestCase.driver.supports_screenshots?
+      #   => true
+      def take_screenshot
+        puts "[Screenshot]: #{image_path}"
+        puts find_image
+      end
+
+      private
+        def supported?
+          Rails::SystemTestCase.driver.supports_screenshots? && !passed?
+        end
+
+        def image_path
+          path = "tmp/screenshots/failures_#{method_name}.png"
+          page.save_screenshot(Rails.root.join(path))
+          path
+        end
+
+        def find_image
+          if ENV['CAPYBARA_INLINE_SCREENSHOT'] == 'artifact'
+            "\e]1338;url=artifact://#{image_path}\a"
+          else
+            name = inline_base64(File.basename(image_path))
+            image = inline_base64(File.read(image_path))
+            "\e]1337;File=name=#{name};height=400px;inline=1:#{image}\a"
+          end
+        end
+
+        def inline_base64(path)
+          Base64.encode64(path).gsub("\n",'')
+        end
+    end
+  end
+end
+
diff --git a/actionpack/test/system_testing/screenshot_helper_test.rb b/actionpack/test/system_testing/screenshot_helper_test.rb
new file mode 100644
index 0000000000..8bf2d0c8d0
--- /dev/null
+++ b/actionpack/test/system_testing/screenshot_helper_test.rb
@@ -0,0 +1,20 @@
+require 'abstract_unit'
+
+class ScreenshotHelperTest < ActiveSupport::TestCase
+  def test_driver_support_for_screenshots
+    Rails::SystemTestCase.driver = :rails_selenium_driver
+    assert Rails::SystemTestCase.driver.supports_screenshots?
+
+    Rails::SystemTestCase.driver = :rack_test
+    assert_not Rails::SystemTestCase.driver.supports_screenshots?
+
+    Rails::SystemTestCase.driver = :selenium
+    assert Rails::SystemTestCase.driver.supports_screenshots?
+
+    Rails::SystemTestCase.driver = :webkit
+    assert Rails::SystemTestCase.driver.supports_screenshots?
+
+    Rails::SystemTestCase.driver = :poltergeist
+    assert Rails::SystemTestCase.driver.supports_screenshots?
+  end
+end