site_prism 2.8 → 2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55a6ce7e56d5856c12b9e656a157e69a23d88fb1
-  data.tar.gz: 3394ad1adb32985236d96080bcc181610538c5f7
+  metadata.gz: 7128da9d4090d139472b9eb01a8afcdc4ce68fb1
+  data.tar.gz: 970b46406b90860bf99397080a61fd0aefdc3c79
 SHA512:
-  metadata.gz: 29a2257b42cb9eb23e552706b0dfdc2a92ee4ef07cf6e41aa42bf3ea4638bfe2880828e23a8aea95e0c8bb8fc2efdc7c671891d9c50bd473415fedf4fe0b05b8
-  data.tar.gz: 825df856fa2537ba9f7019eb9d03c65a42793966ec218507ce132d761a6a9c92c96d1429f757ff7540a9ab0cb3c10d2ab792efeae1542c594a786b6cbc61ffc3
+  metadata.gz: c17b940cae8a127f9a06157d515420a2886a6e062c0cac67f8817a603b31c596cf431f9613dc3c6a01699127b881c7fdc8f16dbf345cfb63a3fcfc872b7d8b50
+  data.tar.gz: fe19493132869f4b645eb1aef2f6518e48d71ee64e5a507a078974c5d8c0ff796f093ee9c221b9001cac062fab908c0b8ffd6027b901f835bd7146552898baf3

data/README.md

@@ -459,7 +459,7 @@ that should be used to test for non-existence. Using the above example:
 
 ```ruby
 Then /^the search field exists$/ do
-  expect(@home).to have_no_search_field #NB: NOT => expect(@home).not_to_ have_search_field
+  expect(@home).to have_no_search_field #NB: NOT => expect(@home).not_to have_search_field
 end
 ```
 
@@ -860,6 +860,22 @@ Then /^the home page menu contains a link to the various search functions$/ do
 end
 ```
 
+##### Accessing section elements using a block
+
+Sections have a `within` method that allows scoped access to the section's elements inside a block.  This is similar to Capybara's `within` method and allows for shorter test code particularly with nested sections.
+Some of this test code can be made a little prettier by simply passing a block in.
+
+```ruby
+Then /^the home page menu contains a link to the various search functions$/ do
+  @home.menu do |menu|
+    expect(menu).to have_search
+    expect(menu.search['href']).to include "google.com"
+    expect(menu).to have_images
+    expect(menu).to have_maps
+  end
+end
+```
+
 #### Getting a section's parent
 
 It is possible to ask a section for its parent (page, or section if this
@@ -1217,6 +1233,143 @@ end
 @results_page.wait_for_search_results(10) #=> waits for 10 seconds instead of the default capybara timeout
 ```
 
+## Load Validations
+
+Load validations enable common validations to be abstracted and performed on a Page or Section to determine
+when it has finished loading and is ready for interaction in your tests.
+
+For example, suppose you have a page which displays a 'Loading...' message while the body of
+the page is loaded in the background.  Load validations can be used to ensure tests wait for the correct url
+to be displayed and the loading message removed before trying to interact with with the page.
+
+Other use cases include Sections which are displayed conditionally and may take time to become ready to
+interact with, such as animated lightboxes.
+
+### Using Load Validations
+
+Load validations can be used in three constructs:
+
+* Passing a block to `Page#load`
+* Passing a block to `Loadable#when_loaded`
+* Calling `Loadable#loaded?`
+
+#### Page#load
+
+When a block is passed to the `Page#load` method, the url will be loaded normally and then the block will be
+executed within the context of `when_loaded`.  See `when_loaded` documentation below for further details.
+
+Example:
+
+```ruby
+# Load the page and then execute a block after all load validations pass:
+my_page_instance.load do |page|
+  page.do_something
+end
+```
+
+#### Loadable#when_loaded
+
+The `Loadable#when_loaded` method on a Loadable class instance will yield the instance of the class into a
+block after all load validations have passed.
+
+If any load validation fails, an error will be raised with the reason, if given, for the failure.
+
+Example:
+
+```ruby
+# Execute a block after all load validations pass:
+a_loadable_page_or_section.when_loaded do |loadable|
+  loadable.do_something
+end
+```
+
+#### Loadable#loaded?
+
+You can explicitly run load validations on a Loadable via the `loaded?` method.
+This method will execute all load validations on the object and return a boolean value.
+In the event of a validation failure, a validation error can be accessed via the `load_error`
+method on the object, if any error message was emitted by the failing validation.
+
+Example:
+
+```ruby
+it 'loads the page' do
+  some_page.load
+  some_page.loaded?    #=> true if/when all load validations pass
+  another_page.loaded? #=> false if any load validations fail
+  another_page.load_error #=> A string error message if one was supplied by the failing load validation, or nil
+end
+```
+
+### Defining Load Validations
+
+A load validation is a block which returns a boolean value when evaluated against an instance of the Loadable.
+
+```ruby
+class SomePage < SitePrism::Page
+  element :foo_element, '.foo'
+  load_validation { has_foo_element? }
+end
+```
+
+The block may instead return a two-element array which includes the boolean result 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.
+
+The error message will be ignored unless the boolean value is falsey.
+
+```ruby
+class SomePage < SitePrism::Page
+  element :foo_element, '.foo'
+  load_validation { [has_foo_element?, 'did not have foo element!'] }
+end
+```
+
+Load validations may be defined on `SitePrism::Page` and `SitePrism::Section` classes (herein referred
+to as `Loadables`) and are evaluated against an instance of the class when executed.
+
+### Load Validation Inheritance and Execution Order
+
+Any number of load validations may be defined on a Loadable class and will be inherited by its subclasses.
+
+Load validations are executed in the order that they are defined.  Inherited load validations are executed
+from the top of the inheritance chain (e.g. `SitePrism::Page` or `SitePrism::Section`) to the bottom.
+
+For example:
+
+```ruby
+class BasePage < SitePrism::Page
+  element :loading_message, '.loader'
+
+  load_validation do
+    wait_for_loading_message(1)
+    [ has_no_loading_message?(wait: 10), 'loading message was still displayed' ]
+  end
+end
+
+class FooPage < BasePage
+  set_url '/foo'
+
+  section :form, '#form'
+  element :some_other_element, '.myelement'
+
+  load_validation { [has_form?, 'form did not appear'] }
+  load_validation { [has_some_other_element?, 'some other element did not appear'] }
+end
+```
+
+In the above example, when `loaded?` is called on an instance of `FooPage`, the validations will be performed in the
+following order:
+
+1. The `SitePrism::Page` default load validation will check `displayed?`
+2. The `BasePage` load validation will wait for the loading message to disappear.
+3. The `FooPage` load validation will wait for the `form` element to be present.
+4. The `FooPage` load validation will wait for the `some_other_element` element to be present.
+
+NOTE: `SitePrism::Page` includes a default load validation on `page.displayed?` which is applied
+to all pages.  It is therefore not necessary to define a load validation for this condition on
+inheriting page objects.
+
 ## Using Capybara Query Options
 
 When querying an element, section or a collection of elements or sections, you may
@@ -1339,7 +1492,7 @@ end
 To expose the iframe, reference it from another page or class using the `iframe`
 method. The `iframe` method takes 3 arguments; the name by which you
 would like to reference the iframe, the page class that represents the
-iframe, and an ID by which you can locate the iframe. For example:
+iframe, and an ID or class by which you can locate the iframe. For example:
 
 ```ruby
 class PageContainingIframe < SitePrism::Page
@@ -1347,10 +1500,8 @@ class PageContainingIframe < SitePrism::Page
 end
 ```
 
-NB: An iframe can only be referenced by its ID. This is a limitation
-imposed by Capybara. The third argument to the `iframe` method must
-contain a selector that will locate the iframe node, and the portion of
-the selector that locates the iframe node must use the iframe node's ID.
+The third argument to the `iframe` method must
+contain a selector that will locate the iframe node.
 
 ### Testing for an iframe's existence
 

data/lib/site_prism.rb

@@ -17,7 +17,5 @@ module SitePrism
     end
   end
 
-  private
-
   @use_implicit_waits = false
 end

data/lib/site_prism/element_container.rb

@@ -19,14 +19,13 @@ module SitePrism
         end
       end
     end
-    alias_method :collection, :elements
+    alias collection elements
 
     def section(section_name, *args, &block)
       section_class, find_args = extract_section_options args, &block
       build section_name, *find_args do
-        define_method section_name do |*runtime_args, &element_block|
-          self.class.raise_if_block(self, section_name.to_s, !element_block.nil?)
-          section_class.new self, find_first(*find_args, *runtime_args)
+        define_method section_name do |*runtime_args, &runtime_block|
+          section_class.new self, find_first(*find_args, *runtime_args), &runtime_block
         end
       end
     end
@@ -64,7 +63,7 @@ module SitePrism
 
     def raise_if_block(obj, name, has_block)
       return unless has_block
-      fail SitePrism::UnsupportedBlock, "#{obj.class}##{name} does not accept blocks, did you mean to define a (i)frame?"
+      raise SitePrism::UnsupportedBlock, "#{obj.class}##{name} does not accept blocks, did you mean to define a (i)frame?"
     end
 
     private
@@ -159,7 +158,7 @@ module SitePrism
 
     def create_no_selector(method_name)
       define_method method_name do
-        fail SitePrism::NoSelectorForElement.new, "#{self.class.name} => :#{method_name} needs a selector"
+        raise SitePrism::NoSelectorForElement.new, "#{self.class.name} => :#{method_name} needs a selector"
       end
     end
 
@@ -172,12 +171,13 @@ module SitePrism
     end
 
     def extract_section_options(args, &block)
-      if args.first.is_a? Class
+      case
+      when args.first.is_a?(Class)
         section_class = args.shift
-      elsif block_given?
+      when block_given?
         section_class = Class.new SitePrism::Section, &block
       else
-        fail ArgumentError, 'You should provide section class either as a block, or as the second argument'
+        raise ArgumentError, 'You should provide section class either as a block, or as the second argument'
       end
       return section_class, args
     end

data/lib/site_prism/exceptions.rb

@@ -7,4 +7,5 @@ module SitePrism
   class TimeOutWaitingForElementVisibility < StandardError; end
   class TimeOutWaitingForElementInvisibility < StandardError; end
   class UnsupportedBlock < StandardError; end
+  NotLoadedError = Class.new(StandardError)
 end

data/lib/site_prism/loadable.rb

@@ -0,0 +1,85 @@
+module SitePrism
+  module Loadable
+    module ClassMethods
+      # The list of load_validations.  They will be executed in the order they are defined.
+      #
+      # @return [Array]
+      def load_validations
+        if superclass.respond_to?(:load_validations)
+          superclass.load_validations + _load_validations
+        else
+          _load_validations
+        end
+      end
+
+      # Appends a load validation block to the page class.
+      #
+      # When `loaded?` is called, these blocks are instance_eval'd against the current page
+      # instance.  This allows users to wait for specific events to occur on the page or certain elements
+      # to be loaded before performing any actions on the page.
+      #
+      # @param block [&block] A block which returns true if the page loaded successfully, or false if it did not.
+      def load_validation(&block)
+        _load_validations << block
+      end
+
+      def _load_validations
+        @_load_validations ||= []
+      end
+      private :_load_validations
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # In certain circumstances, we cache that the page has already been confirmed to be loaded so that actions which
+    # call `loaded?` a second time do not need to perform the load_validation queries against the page a second time.
+    attr_accessor :loaded, :load_error
+
+    # Executes the given block after the page is loaded.
+    #
+    # The loadable object instance is yielded into the block.
+    #
+    # @param block [&block] The block to be executed once the page has finished loading.
+    def when_loaded(&_block)
+      previously_loaded = loaded # Get original loaded value, in case we are nested inside another when_loaded block.
+      raise(ArgumentError, 'A block was expected, but none received.') unless block_given?
+
+      # Within the block, cache loaded? to optimize performance.
+      self.loaded = loaded?
+      unless loaded
+        message = "Failed to load because: #{load_error || 'no reason given'}"
+        raise(::SitePrism::NotLoadedError, message)
+      end
+
+      yield self
+    ensure
+      self.loaded = previously_loaded
+    end
+
+    # 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.
+    #
+    # @return [Boolean] True if the page loaded successfully; otherwise false.
+    def loaded?
+      self.load_error = nil
+
+      return true if loaded
+
+      load_validations_pass?
+    end
+
+    # 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)
+
+        self.load_error = message if message && !passed
+        passed
+      end
+    end
+    private :load_validations_pass?
+  end
+end

data/lib/site_prism/page.rb

@@ -1,27 +1,43 @@
+require 'site_prism/loadable'
+
 module SitePrism
   class Page
     include Capybara::DSL
     include ElementChecker
+    include Loadable
     extend ElementContainer
 
+    load_validation do
+      [displayed?, "Expected #{current_url} to match #{url_matcher} but it did not."]
+    end
+
     def page
       @page || Capybara.current_session
     end
 
-    def load(expansion_or_html = {})
+    # Loads the page.
+    # Executes the block, if given, after running load validations on the page.
+    #
+    # @param expansion_or_html
+    # @param block [&block] A block to run once the page is loaded.  The page will yield itself into the block.
+    def load(expansion_or_html = {}, &block)
+      self.loaded = false
+
       if expansion_or_html.is_a? String
         @page = Capybara.string(expansion_or_html)
       else
         expanded_url = url(expansion_or_html)
-        fail SitePrism::NoUrlForPage if expanded_url.nil?
+        raise SitePrism::NoUrlForPage if expanded_url.nil?
         visit expanded_url
       end
+
+      when_loaded(&block) if block_given?
     end
 
     def displayed?(*args)
       expected_mappings = args.last.is_a?(::Hash) ? args.pop : {}
-      seconds = args.length > 0 ? args.first : Waiter.default_wait_time
-      fail SitePrism::NoUrlMatcherForPage if url_matcher.nil?
+      seconds = !args.empty? ? args.first : Waiter.default_wait_time
+      raise SitePrism::NoUrlMatcherForPage if url_matcher.nil?
       begin
         Waiter.wait_until_true(seconds) { url_matches?(expected_mappings) }
       rescue SitePrism::TimeoutException
@@ -95,12 +111,13 @@ module SitePrism
     end
 
     def url_matches?(expected_mappings = {})
-      if url_matcher.is_a?(Regexp)
+      case
+      when url_matcher.is_a?(Regexp)
         url_matches_by_regexp?
-      elsif url_matcher.respond_to?(:to_str)
+      when url_matcher.respond_to?(:to_str)
         url_matches_by_template?(expected_mappings)
       else
-        fail SitePrism::InvalidUrlMatcher
+        raise SitePrism::InvalidUrlMatcher
       end
     end
 

data/lib/site_prism/section.rb

@@ -1,7 +1,10 @@
+require 'site_prism/loadable'
+
 module SitePrism
   class Section
     include Capybara::DSL
     include ElementChecker
+    include Loadable
     extend ElementContainer
 
     attr_reader :root_element, :parent
@@ -9,12 +12,17 @@ module SitePrism
     def initialize(parent, root_element)
       @parent = parent
       @root_element = root_element
+      Capybara.within(@root_element) { yield(self) } if block_given?
     end
 
     def visible?
       root_element.visible?
     end
 
+    def text
+      root_element.text
+    end
+
     def execute_script(input)
       Capybara.current_session.execute_script input
     end

data/lib/site_prism/version.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module SitePrism
-  VERSION = '2.8'
+  VERSION = '2.9'.freeze
 end

data/lib/site_prism/waiter.rb

@@ -7,7 +7,7 @@ module SitePrism
         break unless Time.now - start_time <= wait_time_seconds
         sleep(0.05)
       end
-      fail SitePrism::TimeoutException, 'Timed out while waiting for block to return true'
+      raise SitePrism::TimeoutException, 'Timed out while waiting for block to return true'
     end
 
     def self.default_wait_time

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: '2.8'
+  version: '2.9'
 platform: ruby
 authors:
 - Nat Ritmeyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-30 00:00:00.000000000 Z
+date: 2016-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -78,6 +78,7 @@ files:
 - lib/site_prism/element_checker.rb
 - lib/site_prism/element_container.rb
 - lib/site_prism/exceptions.rb
+- lib/site_prism/loadable.rb
 - lib/site_prism/page.rb
 - lib/site_prism/section.rb
 - lib/site_prism/version.rb