unobtainium 0.2.1 → 0.3.0

data/lib/unobtainium/drivers/selenium.rb

@@ -7,9 +7,11 @@
 # All rights reserved.
 #
 
-require_relative './support/util'
+require_relative '../support/util'
 
 module Unobtainium
+  # @api private
+  # Contains driver implementations
   module Drivers
 
     ##
@@ -20,13 +22,12 @@ module Unobtainium
         firefox: [:ff,],
         internet_explorer: [:internetexplorer, :explorer, :ie,],
         safari: [],
-        chrome: [],
-        chromium: [],
+        chrome: [:chromium],
         remote: [],
       }.freeze
 
       class << self
-        include ::Unobtainium::Drivers::Utility
+        include ::Unobtainium::Support::Utility
 
         ##
         # Return true if the given label matches this driver implementation,
@@ -47,7 +48,7 @@ module Unobtainium
 
         ##
         # Selenium really wants symbol keys for the options
-        def sanitize_options(label, options)
+        def resolve_options(label, options)
           new_opts = {}
 
           if not options.nil?

data/lib/unobtainium/pathed_hash.rb

@@ -13,14 +13,25 @@ module Unobtainium
 
   ##
   # The PathedHash class wraps Hash by offering pathed access on top of
-  # regular access, i.e. instead of h["first"]["second"] you can write
-  # h["first.second"]
+  # regular access, i.e. instead of `h["first"]["second"]` you can write
+  # `h["first.second"]`.
+  #
+  # The main benefit is much simpler code for accessing nested structured.
+  # For any given path, PathedHash will return nil from `[]` if *any* of
+  # the path components do not exist.
+  #
+  # Similarly, intermediate nodes will be created when you write a value
+  # for a path.
+  #
+  # PathedHash also includes RecursiveMerge.
   class PathedHash
     include RecursiveMerge
 
     ##
-    # Initializer
-    def initialize(init = {})
+    # Initializer. Accepts `nil`, hashes or pathed hashes.
+    #
+    # @param init [NilClass, Hash] initial values.
+    def initialize(init = nil)
       if init.nil?
         @data = {}
       else
@@ -29,18 +40,23 @@ module Unobtainium
       @separator = '.'
     end
 
-    # The separator is the character or pattern splitting paths
+    # @return [String] the separator is the character or pattern splitting paths.
     attr_accessor :separator
 
+    # @api private
+    # Methods redefined to support pathed read access.
     READ_METHODS = [
       :[], :default, :delete, :fetch, :has_key?, :include?, :key?, :member?,
     ].freeze
+
+    # @api private
+    # Methods redefined to support pathed write access.
     WRITE_METHODS = [
       :[]=, :store,
     ].freeze
 
     ##
-    # Returns the pattern to split paths at
+    # @return [RegExp] the pattern to split paths at; based on `separator`
     def split_pattern
       /(?<!\\)#{Regexp.escape(@separator)}/
     end
@@ -99,14 +115,18 @@ module Unobtainium
       end
     end
 
+    # @return [String] string representation
     def to_s
       @data.to_s
     end
 
+    # @return [PathedHash] duplicate, as `.dup` usually works
     def dup
       PathedHash.new(@data.dup)
     end
 
+    # In place merge, as it usually works for hashes.
+    # @return [PathedHash] self
     def merge!(*args, &block)
       # FIXME: we may need other methods like this. This is used by
       #        RecursiveMerge, so we know it's required.
@@ -114,7 +134,7 @@ module Unobtainium
     end
 
     ##
-    # Map any missing method to the driver implementation
+    # Map any missing method to the Hash implementation
     def respond_to?(meth)
       if not @data.nil? and @data.respond_to?(meth)
         return true
@@ -122,6 +142,8 @@ module Unobtainium
       return super
     end
 
+    ##
+    # Map any missing method to the Hash implementation
     def method_missing(meth, *args, &block)
       if not @data.nil? and @data.respond_to?(meth)
         return @data.send(meth.to_s, *args, &block)

data/lib/unobtainium/recursive_merge.rb

@@ -11,6 +11,18 @@ module Unobtainium
   ##
   # Provides recursive merge functions for hashes. Used in PathedHash.
   module RecursiveMerge
+    ##
+    # Recursively merge `:other` into this Hash.
+    #
+    # This starts by merging the leaf-most Hash entries. Arrays are merged
+    # by addition.
+    #
+    # For everything that's neither Hash or Array, if the `:overwrite`
+    # parameter is true, the entry from `:other` is used. Otherwise the entry
+    # from `:self` is used.
+    #
+    # @param other [Hash] the hash to merge into `:self`
+    # @param overwrite [Boolean] see method description.
     def recursive_merge!(other, overwrite = true)
       if other.nil?
         return self
@@ -33,6 +45,9 @@ module Unobtainium
       merge!(other, &merger)
     end
 
+    ##
+    # Same as `dup.recursive_merge!`
+    # @param (see #recursive_merge!)
     def recursive_merge(other, overwrite = true)
       dup.recursive_merge!(other, overwrite)
     end

data/lib/unobtainium/runtime.rb

@@ -34,13 +34,14 @@ module Unobtainium
     end
 
     ##
-    # Number of objects stored in the object map
+    # @return [Integer] number of objects stored in the object map
     def length
       return @objects.length
     end
 
     ##
-    # Does an object with the given name exist?
+    # @param name [String, Symbol] name or label for an object
+    # @return [Boolean] does an object with the given name exist?
     def has?(name)
       return @objects.key?(name)
     end
@@ -51,8 +52,14 @@ module Unobtainium
     # is stored.
     #
     # If a destructor is passed, it is used to destroy the *new* object only.
-    # If no destructor is passed and the object responds to a :destroy method, that
-    # method is called.
+    # If no destructor is passed and the object responds to a `#destroy` method,
+    # that method is called.
+    #
+    # @param name [String, Symbol] name or label for the object to store
+    # @param object [Object] the object to store
+    # @param destructor [Func] a custom destructor accepting the object as its
+    #   parameter.
+    # @return [Object] the stored object
     def store(name, object, destructor = nil)
       delete(name)
 
@@ -65,7 +72,13 @@ module Unobtainium
     # Store the object returned by the block, if any. If no object is returned
     # or no block is given, this function does nothing.
     #
-    # Otherwise it works much like :store above.
+    # Otherwise it works much like `#store`.
+    #
+    # @param name [String, Symbol] name or label for the object to store
+    # @param destructor [Func] a custom destructor accepting the object as its
+    #   parameter.
+    # @param block [Func] a block returning the created object.
+    # @return [Object] the stored object
     def store_with(name, destructor = nil, &block)
       object = nil
       if not block.nil?
@@ -80,7 +93,8 @@ module Unobtainium
     end
 
     ##
-    # Like :store, but only stores the object if none exists for that key yet.
+    # (see #store)
+    # Like `#store`, but only stores the object if none exists for that key yet.
     def store_if(name, object, destructor = nil)
       if has?(name)
         return self[name]
@@ -89,7 +103,8 @@ module Unobtainium
     end
 
     ##
-    # Like :store_if, but as a block version similar to :store_with.
+    # (see #store_with)
+    # Like `#store_if`, but as a block version similar to `#store_with`.
     def store_with_if(name, destructor = nil, &block)
       if has?(name)
         return self[name]
@@ -99,6 +114,8 @@ module Unobtainium
 
     ##
     # Deletes (and destroys) any object found under the given name.
+    #
+    # @param name [String, Symbol] name or label for the object to store
     def delete(name)
       if not @objects.key?(name)
         return
@@ -112,6 +129,11 @@ module Unobtainium
     ##
     # Returns the object with the given name, or the default value if no such
     # object exists.
+    #
+    # @param name [String, Symbol] name or label for the object to retrieve
+    # @param default [Object] default value to return if no object is found for
+    #   name or label.
+    # @return [Object] the object matching the name/label, or the default value.
     def fetch(name, default = nil)
       return @objects.fetch(name)[0]
     rescue KeyError
@@ -122,8 +144,11 @@ module Unobtainium
     end
 
     ##
-    # Similar to :fetch, but always returns nil for an object that could not
+    # Similar to `#fetch`, but always returns nil for an object that could not
     # be found.
+    #
+    # @param name [String, Symbol] name or label for the object to retrieve
+    # @return [Object] the object matching the name/label, or the default value.
     def [](name)
       val = @objects[name]
       if val.nil?

data/lib/unobtainium/support/port_scanner.rb

@@ -0,0 +1,160 @@
+# coding: utf-8
+#
+# unobtainium
+# https://github.com/jfinkhaeuser/unobtainium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other unobtainium contributors.
+# All rights reserved.
+#
+
+require 'socket'
+
+module Unobtainium
+  # @api private
+  # Contains support code
+  module Support
+    ##
+    # A bit of metaprogramming hackery to make a constant with possible domains
+    # from Socket::Constants.
+    if not constants.include?('DOMAINS')
+      domains = []
+      Socket::Constants.constants.each do |name|
+        if name.to_s.start_with?("AF_")
+          domains << name.to_s.gsub(/^AF_/, '').to_sym
+        end
+      end
+      const_set('DOMAINS', domains.freeze)
+    end
+
+    ##
+    # A port scanner for finding a free port for running e.g. a selenium
+    # or appium server.
+    module PortScanner
+      ##
+      # Returns true if the port is open on the host, false otherwise.
+      # @param host [String] host name or IP address
+      # @param port [Integer] port number (1..65535)
+      # @param domains [Array/Symbol] :INET, :INET6, etc. or an Array of
+      #     these. Any from Socket::Constants::AF_* work. Defaults to
+      #     [:INET, :INET6].
+      def port_open?(host, port, domains = [:INET, :INET6])
+        if port < 1 or port > 65535
+          raise ArgumentError, "Port must be in range 1..65535!"
+        end
+
+        test_domains = nil
+        if domains.is_a? Array
+          test_domains = domains.dup
+        else
+          test_domains = [domains]
+        end
+
+        test_domains.each do |domain|
+          if not DOMAINS.include?(domain)
+            raise ArgumentError, "Domains must be one of #{DOMAINS}, or an Array "\
+              "of them, but #{domain} isn't!"
+          end
+        end
+
+        # Test a socket for each domain
+        addr = Socket.sockaddr_in(port, host)
+
+        test_domains.each do |domain|
+          begin
+            sock = Socket.new(domain, :STREAM)
+            return 0 == sock.connect(addr)
+          rescue Errno::EAFNOSUPPORT
+            next # try next domain
+          rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT
+            return false
+          ensure
+            if not sock.nil?
+              sock.close
+            end
+          end
+        end
+      end
+
+      ##
+      # Scan a mixture of ranges and arrays of ports for a given host.
+      # Return those that are open or closed, depending on the options
+      # given.
+      def scan(host, *args)
+        # Argument checks
+        if args.empty?
+          raise ArgumentError, "Need at least one port to scan!"
+        end
+
+        args.each do |item|
+          if not item.respond_to?(:each) and not item.respond_to?(:to_i)
+            raise ArgumentError, "The argument '#{item}' to #scan is not a "\
+              "Range, Array or convertible to Integer, aborting!"
+          end
+        end
+
+        # If the last argument is a Hash, treat it as options.
+        opts = {}
+        if args.last.is_a? Hash
+          opts = args.pop
+        end
+        opts = { for: :open, amount: :all }.merge(opts)
+
+        if not [:all, :first].include?(opts[:amount])
+          raise ArgumentError, ":amount must be one of :all, :first!"
+        end
+        if not [:open, :closed, :available].include?(opts[:for])
+          raise ArgumentError, ":for must beone of :open, :closed, :available!"
+        end
+
+        return run_scan(host, opts, *args)
+      end
+
+      private
+
+      def run_scan(host, opts, *args)
+        results = []
+
+        # Iteratively scan all arguments
+        args.each do |item|
+          if item.respond_to?(:to_i)
+            item_i = item.to_i
+            if test_port(host, item_i, opts[:for])
+              results << item_i
+              if opts[:amount] == :first
+                return results
+              end
+            end
+            next
+          end
+
+          item.each do |port|
+            if not test_port(host, port, opts[:for])
+              next
+            end
+
+            results << port
+            if opts[:amount] == :first
+              return results
+            end
+          end
+        end
+
+        return results
+      end
+
+      def test_port(host, port, test_for)
+        open = port_open?(host, port)
+
+        if open and :open == test_for
+          return true
+        end
+
+        if not open and [:closed, :available].include?(test_for)
+          return true
+        end
+
+        return false
+      end
+    end # module PortScanner
+  end # module Support
+end # module Unobtainium

data/lib/unobtainium/support/runner.rb

@@ -0,0 +1,180 @@
+# coding: utf-8
+#
+# unobtainium
+# https://github.com/jfinkhaeuser/unobtainium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other unobtainium contributors.
+# All rights reserved.
+#
+require 'sys-proctable'
+
+module Unobtainium
+  # @api private
+  # Contains support code
+  module Support
+    ##
+    # Runs a shell command and detaches. Offers methods for managing the process
+    # lifetime. Implements #destroy, so you can use it with the Runtime class to
+    # kill the shell command upon script end.
+    class Runner
+      # @return [String] the ID passed to the constructor
+      attr_reader :id
+
+      # @return [Array] the command passed to the constructor
+      attr_reader :command
+
+      # @return [Integer] if the command is started, the pid of the process,
+      #     or nil otherwise.
+      attr_reader :pid
+
+      # @return [IO] if the command is started, an IO object to read the
+      #     commands output from, or nil otherwise.
+      attr_reader :stdout
+
+      # @return [IO] if the command is started, an IO object to read the
+      #     commands error output from, or nil otherwise.
+      attr_reader :stderr
+
+      ##
+      # Initialize with a shell command, but do not run yet.
+      #
+      # @param id [String] a unique ID for the command. This is to differentiate
+      #     multiple similar commands from each other.
+      # @param command [Array] the remaining parameters are the command and its
+      #     arguments.
+      def initialize(id, *command)
+        if command.empty?
+          raise ArgumentError, "Command may not be empty!"
+        end
+
+        @id = id
+        @command = command
+        @pid = nil
+        @stdout = nil
+        @stderr = nil
+        @wout = nil
+        @werr = nil
+      end
+
+      ##
+      # Start the command. Afterwards, #pid, #stdout, and #stderr should be
+      # non-nil.
+      # @return [Integer] the pid of the command process
+      def start
+        if not @pid.nil?
+          raise "Command already running!"
+        end
+
+        # Capture options; pipes for stdout and stderr
+        @stdout, @wout = IO.pipe
+        @stderr, @werr = IO.pipe
+        opts = {
+          out: @wout,
+          err: @werr,
+        }
+
+        @pid = spawn({}, *@command, opts)
+        return @pid
+      end
+
+      ##
+      # Wait for the command to exit.
+      # @return [Process::Status] exit status of the command.
+      def wait
+        _, status = Process.wait2(@pid)
+        cleanup
+        return status
+      end
+
+      ##
+      # Send the "KILL" signal to the command process and all its children
+      def kill
+        signal("KILL", scope: :all)
+        cleanup
+      end
+
+      ##
+      # Send the given signal to the process, and/or it's children.
+      # @param signal [String] the signal to send
+      # @param scope [Symbol] one of :self (the command process),
+      #     :children (it's children *only) or :all (the process and its
+      #     children.
+      def signal(signal, scope: :self)
+        if @pid.nil?
+          raise "No command is running!"
+        end
+
+        if not [:self, :children, :all].include?(scope)
+          raise ArgumentError, "The :scope argument must be one of :self, "\
+              ":children or :all!"
+        end
+
+        # Figure out which pids to send the signal to. That is usually @pid,
+        # but possibly its children.
+        to_send = []
+        if [:self, :all].include?(scope)
+          to_send << @pid
+        end
+
+        if [:children, :all].include?(scope)
+          children = ::Sys::ProcTable.ps.select { |p| p.ppid == @pid }
+          to_send += children.collect(&:pid)
+        end
+
+        if to_send.empty?
+          raise "This should not happen. I have no pids to send a signal to!"
+        end
+
+        # Alright, send the signal!
+        to_send.each do |pid|
+          # rubocop:disable Lint/HandleExceptions
+          begin
+            Process.kill(signal, pid)
+          rescue
+            # If the kill didn't work, we don't really care.
+          end
+          # rubocop:enable Lint/HandleExceptions
+        end
+
+        # Clean up everything
+        cleanup(true)
+      end
+
+      ##
+      # (see #kill)
+      # Use together with Runtime class to clean up any commands at exit.
+      def destroy
+        kill
+      end
+
+      private
+
+      def cleanup(all = false)
+        @pid = nil
+        # rubocop:disable Style/GuardClause
+        if not @wout.nil?
+          @wout.close
+          @wout = nil
+        end
+        if not @werr.nil?
+          @werr.close
+          @werr = nil
+        end
+
+        if not all
+          return
+        end
+
+        if not @stdout.nil?
+          @stdout.close
+          @stdout = nil
+        end
+        if not @stderr.nil?
+          @stderr.close
+          @stderr = nil
+        end
+        # rubocop:enable Style/GuardClause
+      end
+    end # class Runner
+  end # module Support
+end # module Unobtainium