site_prism 4.0.beta → 4.0.1

data/lib/site_prism/deprecator.rb

@@ -15,7 +15,7 @@ module SitePrism
           warn("#{old} is being deprecated and should no longer be used.")
         end
 
-        warn("#{old} will be removed in SitePrism v4. You have been warned!")
+        warn("#{old} will be removed in SitePrism v5. You have been warned!")
       end
 
       # @return SitePrism.logger.debug(msg)
@@ -27,9 +27,9 @@ module SitePrism
       # NB: As this is bubbled up at debug level, often users will not see this. So it will
       # never be a candidate for removal directly
       def soft_deprecate(old, reason, new = nil)
-        debug("The #{old} method is changing, as is SitePrism, and is now configurable.")
+        debug("The #{old} method is changing, as is SitePrism, and is now advised to be changed.")
         debug("REASON: #{reason}.")
-        debug('Moving forwards into SitePrism v4, the default behaviour will change.')
+        debug('Moving forwards into SitePrism v5, the default behaviour will change.')
         debug("We advise you change to using #{new}") if new
       end
 

data/lib/site_prism/dsl.rb

@@ -16,7 +16,7 @@ module SitePrism
 
     private
 
-    def raise_if_block(object, name, has_block, type)
+    def raise_if_runtime_block_supplied(object, name, has_block, type)
       return unless has_block
 
       SitePrism.logger.debug("Type passed in: #{type}")
@@ -24,25 +24,21 @@ module SitePrism
       raise SitePrism::UnsupportedBlockError
     end
 
-    # Call `find` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _find(*find_args)
       kwargs = find_args.pop
       to_capybara_node.find(*find_args, **kwargs)
     end
 
-    # Call `all` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _all(*find_args)
       kwargs = find_args.pop
       to_capybara_node.all(*find_args, **kwargs)
     end
 
-    # Call `has_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_exists?(*find_args)
       kwargs = find_args.pop
       to_capybara_node.has_selector?(*find_args, **kwargs)
     end
 
-    # Call `has_no_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_does_not_exist?(*find_args)
       kwargs = find_args.pop
       to_capybara_node.has_no_selector?(*find_args, **kwargs)
@@ -103,10 +99,10 @@ module SitePrism
       # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
       # Validate certain properties about the element
       def element(name, *find_args)
-        raise_if_block(self, name, block_given?, :element)
+        raise_if_build_time_block_supplied(self, name, block_given?, :element)
         build(:element, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_block(self, name, runtime_block, :element)
+            raise_if_runtime_block_supplied(self, name, runtime_block, :element)
             _find(*merge_args(find_args, runtime_args))
           end
         end
@@ -118,10 +114,10 @@ module SitePrism
       # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
       # Validate certain properties about the elements
       def elements(name, *find_args)
-        raise_if_block(self, name, block_given?, :elements)
+        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
         build(:elements, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_block(self, name, runtime_block, :elements)
+            raise_if_runtime_block_supplied(self, name, runtime_block, :elements)
             _all(*merge_args(find_args, runtime_args))
           end
         end
@@ -151,7 +147,7 @@ module SitePrism
         section_class, find_args = extract_section_options(args, &block)
         build(:sections, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_block(self, name, runtime_block, :sections)
+            raise_if_runtime_block_supplied(self, name, runtime_block, :sections)
             _all(*merge_args(find_args, runtime_args)).map do |element|
               section_class.new(self, element)
             end
@@ -160,7 +156,7 @@ module SitePrism
       end
 
       def iframe(name, klass, *args)
-        SitePrism.logger.debug('Block passed into iFrame construct at build time') if block_given?
+        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
         element_find_args = deduce_iframe_element_find_args(args)
         scope_find_args = deduce_iframe_scope_find_args(args)
         build(:iframe, name, *element_find_args) do
@@ -175,10 +171,10 @@ module SitePrism
       # Return a list of all mapped items on a SitePrism class instance (Page or Section)
       # If legacy is set to true (Default) -> @return [Array]
       # If legacy is set to false (New behaviour) -> @return [Hash]
-      def mapped_items(legacy: true)
-        return old_mapped_items if legacy
+      def mapped_items(legacy: false)
+        return legacy_mapped_items if legacy
 
-        new_mapped_items
+        @mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
       end
 
       private
@@ -192,13 +188,13 @@ module SitePrism
           map_item(type, name)
           yield
         end
-        add_helper_methods(name, *find_args)
+        add_helper_methods(name, type, *find_args)
       end
 
-      def add_helper_methods(name, *find_args)
+      def add_helper_methods(name, _type, *find_args)
         create_existence_checker(name, *find_args)
         create_nonexistence_checker(name, *find_args)
-        SitePrism::RspecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
+        SitePrism::RSpecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
         create_visibility_waiter(name, *find_args)
         create_invisibility_waiter(name, *find_args)
       end
@@ -254,15 +250,15 @@ module SitePrism
       end
 
       def create_error_method(name)
-        SitePrism.logger.error("#{name} has come from an item with no locators.")
-        SitePrism::Deprecator.soft_deprecate(
+        SitePrism::Deprecator.deprecate(
           'DSL definition with no find_args',
-          'All DSL elements should have find_args'
+          'DSL definition with at least 1 find_arg'
         )
+        SitePrism.logger.error("#{name} has come from an item with no locators.")
         define_method(name) { raise SitePrism::InvalidElementError }
       end
 
-      def raise_if_block(parent_object, name, has_block, type)
+      def raise_if_build_time_block_supplied(parent_object, name, has_block, type)
         return unless has_block
 
         SitePrism.logger.debug("Type passed in: #{type}")
@@ -270,22 +266,19 @@ module SitePrism
         raise SitePrism::UnsupportedBlockError
       end
 
-      def old_mapped_items
-        SitePrism::Deprecator.soft_deprecate(
-          '.mapped_items on a class',
-          'To allow easier recursion through the items in conjunction with #all_there?',
-          '.mapped_items(legacy: false)'
-        )
-        @old_mapped_items ||= []
-      end
-
-      def new_mapped_items
-        @new_mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
+      def legacy_mapped_items
+        @legacy_mapped_items ||= begin
+          SitePrism::Deprecator.deprecate(
+            '.mapped_items structure (internally), on a class',
+            'the new .mapped_items structure'
+          )
+          []
+        end
       end
 
       def map_item(type, name)
-        old_mapped_items << { type => name }
-        new_mapped_items[type] << name.to_sym
+        mapped_items(legacy: true) << { type => name }
+        mapped_items[type] << name.to_sym
       end
 
       def deduce_iframe_scope_find_args(args)

data/lib/site_prism/element_checker.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module SitePrism
+  #
   # [SitePrism::ElementChecker]
   #
   # This allows users to run `#all_there?` checks on an instance.
   #
-  # NB: This functionality is being removed in v4 in favour of the all_there gem
   module ElementChecker
     # Runnable in the scope of any SitePrism::Page or Section.
     # Returns +true+ when "every item" that is being checked is
@@ -13,10 +13,16 @@ module SitePrism
     # for how the definition of "every item" is derived.
     #
     # Example
-    # @my_page.mapped_items
-    # { element => :button_one, element => :button_two, section => :filters }
+    # @my_page.class.mapped_items
+    #  {
+    #    element => [:button_one, :button_two],
+    #    elements => [:button_collection_one, :button_collection_two],
+    #    section => [:filters],
+    #    sections => [:search_result],
+    #    iframe => []
+    #  }
     # @my_page.all_there?
-    # => true - If the three items above are all present
+    # => true - If the items above are all present
     #
     # Note that #elements_to_check will check the hash of mapped_items
     #
@@ -26,13 +32,7 @@ module SitePrism
     # Override: 'one' => Perform one recursive dive into all section/sections
     # items and call #all_there? on all of those items too.
     def all_there?(recursion: :none)
-      case recursion
-      when :none; then elements_to_check.all? { |name| there?(name) }
-      when :one;  then SitePrism::AllThere::RecursionChecker.new(self).all_there?
-      else
-        SitePrism.logger.debug("Input value '#{recursion}'. Valid values are :none or :one.")
-        SitePrism.logger.error('Invalid recursion setting, Will not run #all_there?.')
-      end
+      SitePrism::AllThere::RecursionChecker.new(self).all_there?(recursion: recursion)
     end
 
     # Returns each element that is currently present inside the scope being tested
@@ -51,8 +51,6 @@ module SitePrism
 
     private
 
-    # If the page or section has expected_items set, return expected_items that are mapped
-    # otherwise just return the list of all mapped_items
     def elements_to_check
       if _expected_items
         SitePrism.logger.debug('Expected Items has been set.')
@@ -63,7 +61,7 @@ module SitePrism
     end
 
     def _mapped_items
-      self.class.mapped_items(legacy: false).values.flatten.uniq
+      self.class.mapped_items.values.flatten.uniq
     end
 
     def _expected_items

data/lib/site_prism/loadable.rb

@@ -43,10 +43,11 @@ module SitePrism
 
     # Check if the page is loaded.
     #
-    # On failure, if an error was reported by a failing validation,
-    # it will be available via the `load_error` accessor.
+    # On failure, if an error was reported by a failing validation, it will be available via the `load_error` accessor
     #
-    # @return [Boolean] True if the page loaded successfully; otherwise false.
+    # It will return true if the page has been loaded successfully; otherwise it returns false
+    #
+    # @return [Boolean]
     def loaded?
       self.load_error = nil
 
@@ -57,8 +58,6 @@ module SitePrism
 
     private
 
-    # If any load validations from page subclasses returns false,
-    # immediately return false.
     def load_validations_pass?
       self.class.load_validations.all? do |validation|
         passed, message = instance_eval(&validation)

data/lib/site_prism/page.rb

@@ -9,7 +9,7 @@ module SitePrism
   # through clicking buttons or filling in fields, or verbosely loaded by using the `#load` method
   #
   # All method calls made whilst on a page are scoped using `#to_capybara_node` which defaults to the
-  # current Capybara session
+  # current Capybara session or the `@page` that has been loaded in-line
   class Page
     include Capybara::DSL
     include ElementChecker
@@ -48,12 +48,17 @@ module SitePrism
     #
     # @return [Capybara::Node::Simple || Capybara::Session]
     def page
-      (defined?(@page) && @page) || Capybara.current_session
+      @_page ||= begin
+        SitePrism::Deprecator.deprecate('Calling #page on a SitePrism::Page instance')
+        to_capybara_node
+      end
     end
 
     # This scopes our calls inside Page correctly to the `Capybara::Session`
+    #
+    # @return [Capybara::Node::Simple || Capybara::Session]
     def to_capybara_node
-      page
+      (defined?(@page) && @page) || Capybara.current_session
     end
 
     # Loads the page.
@@ -85,12 +90,21 @@ module SitePrism
       return_yield || true
     end
 
+    # Returns true if the page is displayed within the requisite time
+    # Returns false if the page is not displayed within the requisite time
+    #
+    # @return [Boolean]
     def displayed?(*args)
       wait_until_displayed(*args)
     rescue SitePrism::TimeoutError
       false
     end
 
+    # Wait until the page is displayed according to input arguments
+    # If no url_matcher is provided we don't know how to determine if the page is displayed. So we return an error
+    # Then we wait until the url matches the expected mappings
+    #
+    # @return [Boolean]
     def wait_until_displayed(*args)
       raise SitePrism::NoUrlMatcherForPageError unless url_matcher
 
@@ -99,6 +113,13 @@ module SitePrism
       Waiter.wait_until_true(seconds) { url_matches?(expected_mappings) }
     end
 
+    # Return the matching information of a page
+    #
+    # Return nil if the page is not displayed correctly
+    # Return the regex matches if we have provided a regexp style url_matcher
+    # Otherwise fall back to an addressable-style template of matches
+    #
+    # @return [Nil || MatchData || Hash]
     def url_matches(seconds = Capybara.default_max_wait_time)
       return unless displayed?(seconds)
       return regexp_backed_matches if url_matcher.is_a?(Regexp)
@@ -106,14 +127,24 @@ module SitePrism
       template_backed_matches
     end
 
+    # Returns the templated url from the set_url property defined during the page definition
+    # Returns `nil` if there was not a property set (i.e. the page should not be directly loaded)
+    #
+    # @return [NilClass || String]
     def url(expansion = {})
       self.class.url && Addressable::Template.new(self.class.url).expand(expansion).to_s
     end
 
+    # Returns the url_matcher property defined during the page definition
+    #
+    # @return [Regexp]
     def url_matcher
       self.class.url_matcher
     end
 
+    # Returns true if the page is secure, otherwise returns false
+    #
+    # @return [Boolean]
     def secure?
       page.current_url.start_with?('https')
     end

data/lib/site_prism/rspec_matchers.rb

@@ -4,13 +4,16 @@ module SitePrism
   #
   # @api private
   #
-  class RspecMatchers
+  class RSpecMatchers
     attr_reader :element_name
 
     def initialize(element_name)
       @element_name = element_name
     end
 
+    # Create the positive and negative rspec matchers that will use the SitePrism boolean methods
+    #
+    # @return [Symbol]
     def _create_rspec_existence_matchers
       SitePrism.logger.debug('Including all relevant matcher names / warnings in RSpec scope.')
       create_rspec_existence_matchers(matcher, object_method, negated_object_method, warning)
@@ -43,8 +46,8 @@ module SitePrism
     end
 
     def warning
-      "The RSpec matcher '#{matcher}' was added by SitePrism, but the object under test "\
-        "does not respond to '#{negated_object_method}' and is probably not a SitePrism object. "\
+      "The RSpec matcher '#{matcher}' was added by SitePrism, but the object under test " \
+        "does not respond to '#{negated_object_method}' and is probably not a SitePrism object. " \
         'Falling back to the default RSpec matcher.'
     end
   end

data/lib/site_prism/section.rb

@@ -72,13 +72,6 @@ module SitePrism
       Capybara.within(root_element) { yield(self) }
     end
 
-    # This was the old API-style of delegating through the Capybara.page call and over-loading
-    # the method so we always went through our correct `root_element`
-    def page
-      SitePrism.logger.fatal('This is not supposed to be used. All delegation now happens automatically!')
-      raise SitePrism::SitePrismError
-    end
-
     def capybara_session
       Capybara.current_session
     end

data/lib/site_prism/timer.rb

@@ -1,15 +1,12 @@
 # frozen_string_literal: true
 
 module SitePrism
-  # [SitePrism::Timer]
   #
-  # Used to count asynchronously towards an overall desired duration or condition (Block)
+  # @api private
+  #
   class Timer
     attr_reader :wait_time
 
-    # Return &block
-    #
-    # Count towards a specified time (Supplied)
     def self.run(wait_time, &block)
       new(wait_time).run(&block)
     end
@@ -19,16 +16,10 @@ module SitePrism
       @done = false
     end
 
-    # Return Boolean
-    #
-    # Whether the timer has completed
     def done?
       @done == true
     end
 
-    # Return &block
-    #
-    # Start the Timer and re-evaluate the block repeatedly
     def run
       start
       yield self
@@ -36,9 +27,8 @@ module SitePrism
       stop
     end
 
-    # Return [Boolean, Nil]
-    #
-    # Start the Timer in a separate process
+    private
+
     def start
       stop
       return if wait_time.zero?
@@ -50,9 +40,6 @@ module SitePrism
       end
     end
 
-    # Return True
-    #
-    # Forcibly stop the timer, and kill any threads created by it
     def stop
       if @thread
         @thread.kill

data/lib/site_prism/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SitePrism
-  VERSION = '4.0.beta'
+  VERSION = '4.0.1'
 end

data/lib/site_prism/waiter.rb

@@ -3,10 +3,10 @@
 module SitePrism
   # [SitePrism::Waiter]
   class Waiter
-    # @return Boolean
-    #
     # A looper that will wait until the passed in block evaluates to true
     # Alternatively it will time out once the wait_time is exceeded
+    #
+    # @return [Boolean]
     def self.wait_until_true(wait_time = Capybara.default_max_wait_time, sleep_duration = 0.05)
       Timer.run(wait_time) do |timer|
         loop do

data/lib/site_prism.rb

@@ -2,25 +2,25 @@
 
 require 'site_prism/error'
 require 'site_prism/all_there'
+
 require 'addressable/template'
 require 'forwardable'
 
-# [SitePrism] namespace
-# We autoload our files underneath here to provide a slightly more optimal load solution
-module SitePrism
-  autoload :AddressableUrlMatcher, 'site_prism/addressable_url_matcher'
-  autoload :DSL, 'site_prism/dsl'
-  autoload :DSLValidator, 'site_prism/dsl_validator'
-  autoload :Deprecator, 'site_prism/deprecator'
-  autoload :ElementChecker, 'site_prism/element_checker'
-  autoload :Loadable, 'site_prism/loadable'
-  autoload :Logger, 'site_prism/logger'
-  autoload :Page, 'site_prism/page'
-  autoload :RspecMatchers, 'site_prism/rspec_matchers'
-  autoload :Section, 'site_prism/section'
-  autoload :Timer, 'site_prism/timer'
-  autoload :Waiter, 'site_prism/waiter'
+require 'site_prism/addressable_url_matcher'
+require 'site_prism/dsl'
+require 'site_prism/dsl_validator'
+require 'site_prism/deprecator'
+require 'site_prism/element_checker'
+require 'site_prism/loadable'
+require 'site_prism/logger'
+require 'site_prism/page'
+require 'site_prism/rspec_matchers'
+require 'site_prism/section'
+require 'site_prism/timer'
+require 'site_prism/waiter'
 
+# [SitePrism]
+module SitePrism
   class << self
     def configure
       yield self