lib/calabash/screenshot.rb in calabash-1.9.9.pre3 vs lib/calabash/screenshot.rb in calabash-2.0.0.pre1

@@ -2,18 +2,18 @@
 require 'pathname'
 
 module Calabash
 
   # A public API for taking screenshots.
-  # @!visibility private
   module Screenshot
     # @!visibility private
     def self.screenshot_directory_prefix
       @@screenshot_directory_prefix
     end
 
     # Set the screenshot directory prefix.
+    # @!visibility private
     def self.screenshot_directory_prefix=(value)
       if class_variable_defined?(:@@screenshots_taken) &&
           @@screenshots_taken != 0
         raise 'Cannot change the screenshot directory prefix after a screenshot has been taken'
       end
@@ -22,26 +22,40 @@
     end
 
     # @!visibility private
     self.screenshot_directory_prefix = 'test_run_'
 
-    # Takes a screenshot and saves it. The file is stored in the directory
-    # given by the ENV variable $CAL_SCREENSHOT_DIR, or by default in
-    # the relative directory 'screenshots'. The files are saved in a
+    # Takes a screenshot and saves it.
+    #
+    # If `name` is a relative path or a file name, then the file is stored in
+    # the directory specified by the ENV variable CAL_SCREENSHOT_DIR, or by
+    # default in the relative directory 'screenshots'. The files are saved in a
     # sub directory named test_run_n, where n is unique and incrementing for
     # each new test run. The filename of the screenshot will be `name`.
     # If `name` is not given (nil), the screenshot will be saved as
     # screenshot_N, where N is the total amount of screenshots taken for the
     # test run.
     #
+    # If the name given is an absolute path, then Calabash will save the
+    # screenshot to the absolute directory given.
+    #
+    # If the name given starts with ./ (e.g. `screenshot('./foo.png')`) then
+    # the filename will be saved relative to the current working directory.
+    #
+    # If the file specified by `name` has no extension then the filename will
+    # default to name + '.png'.
+    #
+    # If the directories specified do not exist, Calabash will create them.
+    #
     # @param [String] name Name of the screenshot.
     # @return [String] Path to the screenshot
     def screenshot(name=nil)
       Device.default.screenshot(name)
     end
 
-    # Takes a screenshot and embeds it in the test report.
+    # Takes a screenshot and embeds it in the test report. This method is only
+    # available/useful when running in the context of cucumber.
     # @see Screenshot#screenshot
     def screenshot_embed(name=nil)
       path = screenshot(name)
       embed(path, 'image/png', name || File.basename(path))
     end
@@ -56,14 +70,20 @@
 
       name = "#{name}.png" if File.extname(name).empty?
 
       @@screenshots_taken += 1
 
-      unless Dir.exist?(File.expand_path(screenshot_directory))
-        FileUtils.mkdir_p(File.expand_path(screenshot_directory))
+      if name.start_with?('./')
+        name = File.join(Dir.pwd, "#{name[2..-1]}")
       end
 
-      File.join(screenshot_directory, name)
+      file_name = File.expand_path(name, screenshot_directory)
+
+      unless Dir.exist?(File.dirname(file_name))
+        FileUtils.mkdir_p(File.dirname(file_name))
+      end
+
+      file_name
     end
 
     # @!visibility private
     def self.screenshot_directory
       @@screenshot_directory ||= new_screenshot_sub_directory