site_prism 3.0.3 → 3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a04739bded9cabec9711ba25ac5167f69b7d17e532d106060aab7c03c0c0ff1d
-  data.tar.gz: 1da22d259b1dc8490d1a185fd273df0b7a10b9e15baf72a91fecd82daa07844c
+  metadata.gz: 5ccf39fa12f16a3de0a020f5cc51bd0e8809424392120c490b5735c7bddf8eb8
+  data.tar.gz: bd6daa8edb638af906e6582388aca9fb2185af9b71ac1bd27cddf8a7b0f1a78c
 SHA512:
-  metadata.gz: efce339158f4d932f118d162a1284d8237a5e20daf89610f90bb71427fdaaf049dca5b65b22dbad471405f9d3d06dda24274e1dd2ba580fb82e4aa8bca3a817a
-  data.tar.gz: 312d3a77862f801b81ad92c5d304a7f2ade43b5ce9300f4e422970a9917189a62f291c4888efcb1f617fafc5b674607e83cc9aab7f136840ae250830e2f28bb0
+  metadata.gz: 0c84412248c810e5539053376619abe431912f33cdc903ed8455444d2b866b6287cdec771f8045d365660c28a5f9eaac4222059172b0f4b8e42424ab0c9f884a
+  data.tar.gz: a385856b1c97a688d42a58e6ef36c4ca7e9f71a004065e505b58e0797f47c54b7ecb41a8721353b6f9625274f266768ba1492265665f4ecbd12230eff09ceae7

data/README.md

@@ -1,12 +1,14 @@
 # SitePrism
+[![Gem Version](https://badge.fury.io/rb/site_prism.svg)](https://badge.fury.io/rb/site_prism)
+[![Build Status](https://travis-ci.org/natritmeyer/site_prism.png)](https://travis-ci.org/natritmeyer/site_prism)
+
 _A Page Object Model DSL for Capybara_
 
-SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page Object Model pattern, for use with Capybara in automated acceptance testing.
+SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page Object Model pattern,
+for use with Capybara in automated acceptance testing.
 
 Find the pretty documentation here: http://rdoc.info/gems/site_prism/frames
 
-[![Build Status](https://travis-ci.org/natritmeyer/site_prism.png)](https://travis-ci.org/natritmeyer/site_prism)
-
 Make sure to add your project/company to https://github.com/natritmeyer/site_prism/wiki/Who-is-using-SitePrism
 
 ## Developing / Contributing to SitePrism
@@ -17,11 +19,14 @@ We have a brief set of setup docs [HERE](https://github.com/natritmeyer/site_pri
 
 ## Supported Rubies / Browsers
 
-SitePrism is built and tested to work on Ruby 2.3 - 2.6. There is also some limited support for the Ruby 2.2 series.
+SitePrism is built and tested to work on Ruby 2.4 - 2.6. Ruby 2.3 (Now EOL), is supported but not tested against.
+If you are using SitePrism with Ruby 2.3 it is highly advisable to upgrade to a more modern Ruby
+such as 2.5 or 2.6, if for any other reason, to get a noticeable speed boost!
 
 SitePrism should run on all major browsers. The gem's integration tests are ran on Chrome and Firefox.
 
-If you find your browser doesn't integrate nicely with SitePrism, please open an [issue request](https://github.com/natritmeyer/site_prism/issues/new)
+If you find you cannot integrate nicely with SitePrism, please open an
+[issue request](https://github.com/natritmeyer/site_prism/issues/new)
 
 ## Synopsis
 
@@ -419,7 +424,7 @@ end
 @home.load
 
 @home.search_field #=> will return the capybara element found using the selector
-@home.search_field.set 'the search string' #=> since search_field returns a capybara element, you can use the capybara API to deal with it
+@home.search_field.set 'the search string' #=> `search_field` returns a capybara element, so use the capybara API to deal with it
 @home.search_field.text #=> standard method on a capybara element; returns a string
 ```
 
@@ -609,7 +614,7 @@ end
 Then the following method is available:
 
 ```ruby
-@friends_page.has_names? #=> returns true if at least one element is found using the relevant selector
+@friends_page.has_names? #=> returns true if at least one `name` element is found
 ```
 
 This in turn allows the following nice test code
@@ -732,7 +737,8 @@ The way to add a section to a page (or another section - which is possible) is t
 call the `section` method. It takes 3 arguments: the first is the name of the section as
 referred to on the page (sections that appear on multiple pages can be named differently).
 The second argument is the class of which an instance will be created to represent
-the page section, and the following arguments are [Capybara::Node::Finders](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Finders).
+the page section, and the following arguments are
+[Capybara::Node::Finders](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Finders).
 These identify the root node of the section on this page (note that the css selector
 can be different for different pages as the whole point of sections is that they can
 appear in different places / ways on different pages).
@@ -754,9 +760,9 @@ class HomePage < SitePrism::Page
 end
 ```
 
-The 3rd argument (Locators), can be omitted if you are re-using the same locator for all
-references to the section Class. In order to do this, simply tell SitePrism that
-you want to use a default search argument.
+The 3rd argument (Locators), can be omitted if you are re-using the same
+locator for all references to the section Class. In order to do this,
+simply tell SitePrism that you want to use default search arguments.
 
 ```ruby
 class People < SitePrism::Section
@@ -1321,7 +1327,7 @@ class SomePage < SitePrism::Page
 end
 ```
 
-The block may be defined as a two-element array which includes the boolean check
+The block *may* be defined as a two-element array which includes the boolean check
 as the first element and an error message as the second element.
 It is highly recommended to supply an error message, as they are
 extremely useful in debugging validation errors.
@@ -1579,9 +1585,9 @@ end
 
 SitePrism can be configured to change its behaviour.
 
-For each of the following configuration options, either add it in the `spec_helper.rb` file
-if you are running SitePrism as a Unit Test framework, or in your `env.rb` if you are running
-a Cucumber based framework
+For each of the following configuration options, either add it in the
+`spec_helper.rb` file if you are running SitePrism as a Unit Test framework,
+or in your `env.rb` if you are running a Cucumber based framework.
 
 ### Using Capybara Implicit Waits
 
@@ -1695,7 +1701,8 @@ end
 The only thing that needs instantiating is the `App` class - from then on
 pages don't need to be initialized, they are now returned by methods on `@app`.
 
-It is possible to further optimise this, by using Cucumber/RSpec hooks, however
-the investigation and optimisation of this is left as an exercise to the Reader.
+It is possible to further optimise this, by using Cucumber/RSpec hooks, amongst
+other things. However the investigation and optimisation of this (and other
+aspects of SitePrism), is left as an exercise to the Reader.
 
 Happy testing from all of the SitePrism team!

data/lib/site_prism.rb

@@ -13,18 +13,55 @@ module SitePrism
   autoload :Waiter, 'site_prism/waiter'
 
   class << self
-    attr_writer :enable_logging
-
     def configure
       yield self
     end
 
+    # The SitePrism logger object - This is called automatically in several
+    # locations and will log messages according to the normal Ruby protocol
+    # To alter (or check), the log level; call .log_level= or .log_level
+    #
+    # This logger object can also be used to manually log messages
+    #
+    # To Manually log a message
+    #   SitePrism.logger.info('Information')
+    #   SitePrism.logger.debug('Input debug message')
+    #
+    # By default the logger will output all messages to $stdout, but can be
+    # altered to log to a file or another IO location by calling `.log_path=`
     def logger
       @logger ||= SitePrism::Logger.new.create
     end
 
-    def enable_logging
-      @enable_logging ||= false
+    # `Logger#reopen` was added in Ruby 2.3 - Which is now the minimum version
+    # for the site_prism gem
+    #
+    # This writer method allows you to configure where you want the output of
+    # the site_prism logs to go (Default is $stdout)
+    #
+    # example: SitePrism.log_path = 'site_prism.log' would save all
+    # log messages to `./site_prism.log`
+    def log_path=(logdev)
+      logger.reopen(logdev)
+    end
+
+    # To enable full logging (This uses the Ruby API, so can accept any of a
+    # Symbol / String / Integer as an input
+    #   SitePrism.log_level = :DEBUG
+    #   SitePrism.log_level = 'DEBUG'
+    #   SitePrism.log_level = 0
+    #
+    # To disable all logging (Done by default)
+    #   SitePrism.log_level = :UNKNOWN
+    def log_level=(value)
+      logger.level = value
+    end
+
+    # To query what level is being logged
+    #   SitePrism.log_level
+    #   => :UNKNOWN # By default
+    def log_level
+      %i[DEBUG INFO WARN ERROR FATAL UNKNOWN][logger.level]
     end
   end
 end

data/lib/site_prism/dsl.rb

@@ -66,14 +66,12 @@ module SitePrism
       options[:wait] = wait_time unless wait_key_present?(options)
     end
 
-    # True if the +wait+ key is present in the options hash.
-    #
+    # Detect if the +wait+ key is present in the options hash.
     # Note that setting it to to false or 0, still will return true here.
     def wait_key_present?(options)
       options.key?(:wait)
     end
 
-    # rubocop:disable Metrics/ModuleLength
     module ClassMethods
       attr_reader :expected_items
 
@@ -124,13 +122,14 @@ module SitePrism
       def iframe(name, klass, *args)
         element_find_args = deduce_iframe_element_find_args(args)
         scope_find_args = deduce_iframe_scope_find_args(args)
-        map_item!(:iframe, name)
-        add_iframe_helper_methods(name, *element_find_args)
-        define_method(name) do |&block|
-          raise MissingBlockError unless block
 
-          within_frame(*scope_find_args) do
-            block.call(klass.new)
+        build(:iframe, name, *element_find_args) do
+          define_method(name) do |&block|
+            raise MissingBlockError unless block
+
+            within_frame(*scope_find_args) do
+              block.call(klass.new)
+            end
           end
         end
       end
@@ -145,14 +144,14 @@ module SitePrism
         if find_args.empty?
           create_error_method(name)
         else
-          map_item!(type, name)
+          map_item(type, name)
           yield
         end
         add_helper_methods(name, *find_args)
       end
 
-      def map_item!(type, name)
-        mapped_items << { type => name }
+      def map_item(type, name)
+        mapped_items << { type => name.to_sym }
       end
 
       def add_helper_methods(name, *find_args)
@@ -162,11 +161,6 @@ module SitePrism
         create_invisibility_waiter(name, *find_args)
       end
 
-      def add_iframe_helper_methods(name, *find_args)
-        create_existence_checker(name, *find_args)
-        create_nonexistence_checker(name, *find_args)
-      end
-
       def create_helper_method(proposed_method_name, *find_args)
         if find_args.empty?
           create_error_method(proposed_method_name)
@@ -228,27 +222,35 @@ module SitePrism
       end
 
       def deduce_iframe_scope_find_args(args)
+        warn_on_invalid_selector_input(args)
         case args[0]
-        when Integer
-          [args[0]]
-        when String
-          [:css, args[0]]
-        else
-          args
+        when Integer then [args[0]]
+        when String  then [:css, args[0]]
+        else args
         end
       end
 
       def deduce_iframe_element_find_args(args)
+        warn_on_invalid_selector_input(args)
         case args[0]
-        when Integer
-          "iframe:nth-of-type(#{args[0] + 1})"
-        when String
-          [:css, args[0]]
-        else
-          args
+        when Integer then "iframe:nth-of-type(#{args[0] + 1})"
+        when String  then [:css, args[0]]
+        else args
         end
       end
 
+      def warn_on_invalid_selector_input(args)
+        return unless looks_like_xpath?(args[0])
+
+        msg = 'The arguments passed in look like xpath. Check your locators.'
+        SitePrism.logger.warn(msg)
+        SitePrism.logger.debug("Default locator: #{Capybara.default_selector}")
+      end
+
+      def looks_like_xpath?(arg)
+        arg.is_a?(String) && arg.start_with?('/', './')
+      end
+
       def extract_section_options(args, &block)
         if args.first.is_a?(Class)
           klass = args.shift
@@ -262,14 +264,11 @@ module SitePrism
 
       def deduce_section_class(base_class, &block)
         klass = base_class
-
         klass = Class.new(klass || SitePrism::Section, &block) if block_given?
+        return klass if klass
 
-        unless klass
-          raise ArgumentError, "You should provide descendant of \
+        raise ArgumentError, "You should provide descendant of \
 SitePrism::Section class or/and a block as the second argument."
-        end
-        klass
       end
 
       def deduce_search_arguments(section_class, args)
@@ -283,6 +282,5 @@ in section creation or set_default_search_arguments within section class")
         args if args && !args.empty?
       end
     end
-    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/site_prism/loadable.rb

@@ -26,9 +26,10 @@ module SitePrism
       # @param block [&block] A block which returns true if the page
       # loaded successfully, or false if it did not.
       # This block can contain up to 2 elements in an array
-      # The first is the physical validation test to be truthily evaluated
-      # If this does not pass, then the 2nd item (If defined), is output
-      # as an error message to the FailedLoadValidationError that is thrown
+      # The first is the physical validation test to be truthily evaluated.
+      #
+      # If this does not pass, then the 2nd item (if defined), is output
+      # as an error message to the +FailedLoadValidationError+ that is thrown
       def load_validation(&block)
         _load_validations << block
       end

data/lib/site_prism/logger.rb

@@ -1,35 +1,21 @@
+# frozen_string_literal: true
+
 require 'logger'
 
 module SitePrism
-  # To enable full logging
-  #   SitePrism.enable_logging = true
   #
-  # To disable all logging (Done by default)
-  #   SitePrism.enable_logging = false
+  # @api private
   #
-  # To Manually log a message
-  #   SitePrism.logger.info('Information')
-  #   SitePrism.logger.debug('Input debug message')
   class Logger
     def create(output = $stdout)
       logger = ::Logger.new(output)
       logger.progname = 'SitePrism'
-      logger.level = log_level
+      logger.level = :UNKNOWN
       logger.formatter = proc do |severity, time, progname, msg|
         "#{time.strftime('%F %T')} - #{severity} - #{progname} - #{msg}\n"
       end
 
       logger
     end
-
-    private
-
-    def log_level
-      if SitePrism.enable_logging
-        0 # This is equivalent to debug standard logging
-      else
-        5 # This is equivalent to unknown (or no), logging
-      end
-    end
   end
 end

data/lib/site_prism/section.rb

@@ -36,7 +36,10 @@ module SitePrism
     # occurs and calls within a section (For example section.find(element))
     # correctly scope to look within the section only
     def page
-      root_element || super
+      return root_element if root_element
+
+      SitePrism.logger.warn('Root Element not found; Falling back to `super`')
+      super
     end
 
     def visible?
@@ -73,11 +76,11 @@ module SitePrism
     end
 
     def element_exists?(*find_args)
-      page && page.has_selector?(*find_args)
+      page.has_selector?(*find_args)
     end
 
     def element_does_not_exist?(*find_args)
-      page && page.has_no_selector?(*find_args)
+      page.has_no_selector?(*find_args)
     end
   end
 end

data/lib/site_prism/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SitePrism
-  VERSION = '3.0.3'.freeze
+  VERSION = '3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: '3.1'
 platform: ruby
 authors:
 - Nat Ritmeyer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-20 00:00:00.000000000 Z
+date: 2019-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -29,22 +29,16 @@ dependencies:
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.18'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.18'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: cucumber
   requirement: !ruby/object:Gem::Requirement
@@ -181,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.2'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="