calabash 1.9.9.pre2 → 1.9.9.pre3

data/lib/calabash/android/life_cycle.rb

@@ -1,5 +1,6 @@
 module Calabash
   module Android
+    # @!visibility private
     module LifeCycle
       # Resume an application. If the application is already focused, nothing
       # will happen.
@@ -23,7 +24,7 @@ module Calabash
       end
 
 
-      # !@visibility private
+      # @!visibility private
       def _send_current_app_to_background(for_seconds)
         package = focused_package
         activity = focused_activity
@@ -34,4 +35,4 @@ module Calabash
       end
     end
   end
-end
+end

data/lib/calabash/android/orientation.rb

@@ -1,5 +1,6 @@
 module Calabash
   module Android
+    # @!visibility private
     module Orientation
       # @!visibility private
       def _set_orientation_landscape

data/lib/calabash/android/physical_buttons.rb

@@ -1,7 +1,9 @@
-# @todo: Add not about this class being easily abused
 module Calabash
   module Android
+    # @!visibility private
     module PhysicalButtons
+
+      # @todo: Add note about this class being easily abused
       def press_button(key)
         Device.default.perform_action('press_key', key)
         true

data/lib/calabash/android/screenshot.rb

@@ -1,4 +1,3 @@
-# @!visibility private
 module Calabash
   module Android
     # @!visibility private

data/lib/calabash/android/text.rb

@@ -1,5 +1,6 @@
 module Calabash
   module Android
+    # @!visibility private
     module Text
       def dismiss_keyboard
         Device.default.perform_action('hide_soft_keyboard')

data/lib/calabash/application.rb

@@ -1,22 +1,30 @@
 require 'digest'
 
 module Calabash
-  # A representation of the application that is under test.
+  # A representation of an application that is under test.
   class Application
+    # @!visibility private
     include Calabash::Utility
 
+    # @!visibility private
     @@default = nil
 
+    # @!visibility private
     def self.default
       @@default
     end
 
+    # @!visibility private
     def self.default=(value)
       @@default = value
     end
 
     attr_reader :path
 
+    # Create an application from a path
+    #
+    # @return [Calabash::Android::Application, Calabash::IOS::Application] An
+    #  application for `path`.
     def self.from_path(path)
       extension = File.extname(path)
 
@@ -43,28 +51,39 @@ module Calabash
       ensure_application_path
     end
 
+    # @!visibility private
     def to_s
       "#<Application #{path}>"
     end
 
+    # @!visibility private
     def inspect
       to_s
     end
 
+    # @!visibility private
     def extract_identifier
       abstract_method!
     end
 
+    # The identifier of the app. On iOS this is known as the bundle id, on
+    # Android this is known as the package. If the application has not been
+    # given an identifier in #initialize, this method will try to extract the
+    # identifier of the app.
+    #
+    # @return [String] The identifier if the app
     def identifier
       @identifier ||= extract_identifier
     end
 
+    # @!visibility private
     def md5_checksum
       Digest::MD5.file(path).hexdigest
     end
 
     private
 
+    # @!visibility private
     def ensure_application_path
       unless File.exist?(path)
         raise "The app '#{path}' does not exist."

data/lib/calabash/cli/generate.rb

@@ -47,10 +47,18 @@ module Calabash
         File.open(File.join('features', 'support', 'hooks.rb'), 'w') {|file| file.write(hooks) }
         File.open(File.join('features', 'support', 'env.rb'), 'w') {|file| file.write(env) }
 
-        gemfile = File.read(file(File.join('Gemfile')))
+        gemfile = File.readlines(file(File.join('Gemfile')))
 
         unless File.exist?('Gemfile')
-          File.open('Gemfile', 'w') {|file| file.write(gemfile) }
+          File.open('Gemfile', 'w') do |file|
+            gemfile.each do |skeleton_line|
+              if skeleton_line == "gem 'calabash'\n"
+                file.write("#{skeleton_line.strip}, '#{Calabash::VERSION}'\n")
+              else
+                file.write(skeleton_line)
+              end
+            end
+          end
         end
 
         gitignore = File.read(file(File.join('.gitignore')))

data/lib/calabash/console_helpers.rb

@@ -1,49 +1,129 @@
 require 'clipboard'
 
 module Calabash
+
+  # Methods you can use in the Calabash console to help you
+  # interact with your app.
+  # @!visibility private
   module ConsoleHelpers
-    # Outputs all visible elements as a tree
+
+    # Outputs all visible elements as a tree.
     def tree
       ConsoleHelpers.dump(Device.default.dump)
       true
     end
 
-    def self.save_old_readline_history
-      file_name = IRB.conf[:HISTORY_FILE]
-
-      if File.exist?(file_name)
-        @@start_readline_history = File.readlines(file_name).map(&:chomp)
-      end
-    end
-
-    def self.extended(base)
-      save_old_readline_history
-    end
-
+    # List the visible element classes.
     def classes
       query("*").map{|e| e['class']}.uniq
     end
 
+    # List the visible element ids.
     def ids
       query("*").map{|e| e['id']}.compact
     end
 
+    # Copy all the commands entered in the current console session into the OS
+    # Clipboard.
     def copy
       ConsoleHelpers.copy
       true
     end
 
+    # Clear the console.
     def clear
       ConsoleHelpers.clear
       true
     end
 
+    # Puts a message of the day.
+    def message_of_the_day
+      messages = [
+            "Let's get this done!",
+            'Ready to rumble.',
+            'Enjoy.',
+            'Remember to breathe.',
+            'Take a deep breath.',
+            "Isn't it time for a break?",
+            'Can I get you a coffee?',
+            'What is a calabash anyway?',
+            'Smile! You are on camera!',
+            'Let op! Wild Rooster!',
+            "Don't touch that button!",
+            "I'm gonna take this to 11.",
+            'Console. Engaged.',
+            'Your wish is my command.',
+            'This console session was created just for you.',
+            'Den som jager to harer, får ingen.',
+            'Uti, non abuti.',
+            'Non Satis Scire',
+            'Nullius in verba',
+            'Det ka æn jå væer ei jált'
+      ]
+
+      puts Color.green("Calabash #{Calabash::VERSION} says: '#{messages.shuffle.first}'")
+    end
+
+    # Turn on debug logging.
+    def verbose
+      if Calabash::Logger.log_levels.include?(:debug)
+        puts Color.blue('Debug logging is already turned on.')
+      else
+        Calabash::Logger.log_levels << :debug
+        puts Color.blue('Turned on debug logging.')
+      end
+
+      true
+    end
+
+    # Turn off debug logging.
+    def quiet
+      if Calabash::Logger.log_levels.include?(:debug)
+        puts Color.blue('Turned off debug logging.')
+        Calabash::Logger.log_levels.delete(:debug)
+      else
+        puts Color.blue('Debug logging is already turned off.')
+      end
+
+      true
+    end
+
+    # @!visibility private
+    def puts_console_details
+      puts ''
+      puts Color.blue('#             =>  Useful Methods  <=              #')
+      puts Color.cyan('>     ids => List all the visible ids.')
+      puts Color.cyan('> classes => List all the visible classes.')
+      puts Color.cyan(">    tree => The app's visible view hierarchy.")
+      puts Color.cyan('>    copy => Copy console commands to the Clipboard.')
+      puts Color.cyan('>   clear => Clear the console.')
+      puts Color.cyan('> verbose => Turn debug logging on.')
+      puts Color.cyan('>   quiet => Turn debug logging off.')
+      puts ''
+    end
+
+    # @!visibility private
+    def self.save_old_readline_history
+      file_name = IRB.conf[:HISTORY_FILE]
+
+      if File.exist?(file_name)
+        @@start_readline_history = File.readlines(file_name).map(&:chomp)
+      end
+    end
+
+    # @!visibility private
+    def self.extended(base)
+      save_old_readline_history
+    end
+
+    # @!visibility private
     def self.copy
       commands = filter_commands(current_console_history)
       string = commands.join($INPUT_RECORD_SEPARATOR)
       Clipboard.copy(string)
     end
 
+    # @!visibility private
     def self.clear
       if Gem.win_platform?
         system('cls')
@@ -54,6 +134,7 @@ module Calabash
       @@start_readline_history = readline_history
     end
 
+    # @!visibility private
     def self.current_console_history
       length = readline_history.length - @@start_readline_history.length
 
@@ -69,18 +150,22 @@ module Calabash
                                 /\s*clear_app(\(|\z)/,
                                 /\s*stop_app(\(|\z)/)
 
+    # @!visibility private
     def self.filter_commands(commands)
       commands.reject {|command| command =~ FILTER_REGEX}
     end
 
+    # @!visibility private
     def self.readline_history
       Readline::HISTORY.to_a
     end
 
+    # @!visibility private
     def self.dump(json_data)
       json_data['children'].each {|child| write_child(child)}
     end
 
+    # @!visibility private
     def self.write_child(data, indentation=0)
       render(data, indentation)
 
@@ -89,15 +174,18 @@ module Calabash
       end
     end
 
+    # @!visibility private
     def self.render(data, indentation)
       raise AbstractMethodError
     end
 
+    # @!visibility private
     def self.output(string, indentation)
       (indentation*2).times {print " "}
       print "#{string}"
     end
 
+    # @!visibility private
     def self.visible?(data)
       raise AbstractMethodError
     end

data/lib/calabash/defaults.rb

@@ -11,7 +11,7 @@ module Calabash
 
     # Set the default device.
     #
-    # @see #Calabash::Defaults#default_device
+    # @see Calabash::Defaults#default_device
     def default_device=(device)
       Device.default = device
     end
@@ -28,7 +28,7 @@ module Calabash
 
     # Set the default application.
     #
-    # @see #Calabash::Defaults.default_application
+    # @see Calabash::Defaults#default_application
     def default_application=(application)
       Application.default = application
     end
@@ -36,6 +36,39 @@ module Calabash
     # Get the default server. The default server is the test-server
     # of the `#default_device`.
     #
+    # @example
+    #  # Setup the two apps we are going to test
+    #  app1 = Calabash::Android::Application.new(app1_path, app1_test_server_path)
+    #  app2 = Calabash::Android::Application.new(app2_path, app2_test_server_path)
+    #
+    #  # Ensure they are installed
+    #  ensure_app_installed(app1)
+    #  ensure_app_installed(app2)
+    #
+    #  # Set up the servers of the apps. Notice that the second app has to use a
+    #  # different port for them to be able to run at the same time.
+    #  app1_server = Calabash.default_server
+    #  app2_server = Calabash::Server.new(app1_server.endpoint, app1_server.test_server_port + 1)
+    #
+    #  # Start the first app
+    #  start_app(app1)
+    #  # Interact with the first app
+    #  tap("something on app 1")
+    #
+    #  # Start the second app
+    #  Calabash.default_server = app2_server
+    #  start_app(app2)
+    #
+    #  # Interact with the second app
+    #  tap("something on app 2")
+    #
+    #  # Resume the first app
+    #  Calabash.default_server = app1_server
+    #  resume_app(app1)
+    #
+    #  # Interact with the first app again
+    #  tap("something on app 1")
+    #
     # @raise [RuntimeError] If default device is not set
     def default_server
       if default_device.nil?
@@ -47,7 +80,7 @@ module Calabash
 
     # Set the default server.
     #
-    # @see #Calabash::Defaults.default_server
+    # @see Calabash::Defaults#default_server
     # @raise [RuntimeError] If default device is not set
     def default_server=(server)
       default_device.change_server(server)

data/lib/calabash/device.rb

@@ -2,17 +2,22 @@ module Calabash
   class Device
     include Utility
 
+    # @!visibility private
     @@default = nil
 
+    # @!visibility private
     def self.default
       @@default
     end
 
+    # @!visibility private
     def self.default=(value)
       @@default = value
     end
 
-    attr_reader :identifier, :server, :http_client, :logger
+    attr_reader :identifier
+    # @!visibility private
+    attr_reader :server, :http_client, :logger
 
     # Create a new device.
     # @param [String] identifier A token that uniquely identifies the device.
@@ -20,9 +25,10 @@ module Calabash
     #   `$ xcrun instruments -s devices`.
     #   On Android, this is the serial of the device, emulator or simulator
     #   returned by `$ adb devices`.
-    # @param [Server] server A server object.
+    # @param [Calabash::Server] server A server object.
     #
-    # @return [Device] A device.
+    # @return [Calabash::Device] A device.
+    # @!visibility public
     def initialize(identifier, server, options={})
       @identifier = identifier
       @server = server
@@ -30,12 +36,14 @@ module Calabash
       @http_client = HTTP::RetriableClient.new(server, options.fetch(:http_options, {}))
     end
 
+    # @!visibility private
     def change_server(new_server)
       @server = new_server
       @http_client.change_server(new_server)
     end
 
     # Start the application and the test server
+    # @!visibility private
     def start_app(path_or_application, options={})
       application = parse_path_or_app_parameters(path_or_application)
 
@@ -43,45 +51,53 @@ module Calabash
     end
 
     # Shutdown the application and the test server
+    # @!visibility private
     def stop_app
       _stop_app
     end
 
     # @see Screenshot#screenshot
+    # @!visibility private
     def screenshot(name=nil)
       path = Screenshot.obtain_screenshot_path!(name)
 
       _screenshot(path)
     end
 
+    # @!visibility private
     def install_app(path_or_application)
       application = parse_path_or_app_parameters(path_or_application)
 
       _install_app(application)
     end
 
+    # @!visibility private
     def ensure_app_installed(path_or_application)
       application = parse_path_or_app_parameters(path_or_application)
 
       _ensure_app_installed(application)
     end
 
+    # @!visibility private
     def uninstall_app(path_or_application)
       application = parse_path_or_app_parameters(path_or_application)
 
       _uninstall_app(application)
     end
 
+    # @!visibility private
     def clear_app_data(path_or_application)
       application = parse_path_or_app_parameters(path_or_application)
 
       _clear_app_data(application)
     end
 
+    # @!visibility private
     def set_location(location)
       abstract_method!
     end
 
+    # @!visibility private
     def dump
       request = HTTP::Request.new('/dump')
 
@@ -94,6 +110,7 @@ module Calabash
     # Ensures the test server is ready
     #
     # @raise [RuntimeError] Raises error when the server does not respond
+    # @!visibility private
     def ensure_test_server_ready(options={})
       begin
         Timeout.timeout(options.fetch(:timeout, 30), EnsureTestServerReadyTimeoutError) do
@@ -113,6 +130,7 @@ module Calabash
 
     # Performs a `tap` on the (first) view that matches `query`.
     # @see Calabash::Gestures#tap
+    # @!visibility private
     def tap(query, options={})
       Query.ensure_valid_query(query)
 
@@ -130,6 +148,7 @@ module Calabash
 
     # Performs a `double_tap` on the (first) view that matches `query`.
     # @see Calabash::Gestures#double_tap
+    # @!visibility private
     def double_tap(query, options={})
       Query.ensure_valid_query(query)
 
@@ -147,6 +166,7 @@ module Calabash
 
     # Performs a `long_press` on the (first) view that matches `query`.
     # @see Calabash::Gestures#long_press
+    # @!visibility private
     def long_press(query, options={})
       Query.ensure_valid_query(query)
 
@@ -165,6 +185,7 @@ module Calabash
 
     # Performs a `pan` on the (first) view that matches `query`.
     # @see Calabash::Gestures#pan
+    # @!visibility private
     def pan(query, from, to, options={})
       Query.ensure_valid_query(query)
 
@@ -179,6 +200,7 @@ module Calabash
 
     # Performs a `pan` between two elements.
     # @see Calabash::Gestures#pan_between
+    # @!visibility private
     def pan_between(query_from, query_to, options={})
       Query.ensure_valid_query(query_from)
       Query.ensure_valid_query(query_to)
@@ -192,6 +214,7 @@ module Calabash
 
     # Performs a `flick` on the (first) view that matches `query`.
     # @see Calabash::Gestures#flick
+    # @!visibility private
     def flick(query, from, to, options={})
       Query.ensure_valid_query(query)
 
@@ -205,6 +228,7 @@ module Calabash
     end
 
     # @see Calabash::Gestures#pinch
+    # @!visibility private
     def pinch(direction, query, options={})
       Query.ensure_valid_query(query)
 
@@ -220,6 +244,7 @@ module Calabash
 
     # Enter `text` into the currently focused view.
     # @see Calabash::Text#enter_text
+    # @!visibility private
     def enter_text(text)
       abstract_method!
     end