site_prism 4.0.3 → 5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31d906cda08dd376f6e81fe3ed760b954cf172d2037dcee25d91c01b3b8ace24
-  data.tar.gz: aefc0ed612cf57548101505e46c92845ef9fa2f7482b23e5d6b38cc7c37cf9f7
+  metadata.gz: 3036f6b2266855a0a4d08a3c72b44b08d1ce6f423ca72e5dbe5b539cb90b1216
+  data.tar.gz: 1314d67df7aeb3c9d70478e5b884aec2cfb7b4216c58cf9841d4d6dc8b7bc9f5
 SHA512:
-  metadata.gz: 9eda5c088201fe6055d67d92cdd3a5f08a90ffe9ccbd2788ac1b4da6e6a0dff32e000c59819e113b4091fc33d2c38d875c9b3d36bd4d2dc549d42d4e1f071ac3
-  data.tar.gz: 5f926bac135af87939fc52ce5d110dd806ed7e3708bad8b885670a71e75065057d58de506547389ac11f2216ffcc043031262c4eeb5d11697ff38f114d1685f9
+  metadata.gz: 057576ee2b44eb40824344eeef80243e4fbbe8b30df7ab8e6b011053f652b0257065472103b16ed6a4ce094ed3ad608cf8c72dcb8e11c0e3e4f3daa2aaa9ef38
+  data.tar.gz: c9ef4c0ac315e0664f0089cd13a75e8566e7be3f553e85a7f2d17ef1bce7943762074b478767790bb44497968fc6ee0919440a1e613ed6a27f0efde585e19f24

data/README.md

@@ -29,8 +29,8 @@ We have a brief set of setup docs [HERE](https://github.com/site-prism/site_pris
 
 ## Supported Rubies / Browsers
 
-SitePrism is built and tested to work on Ruby 2.6 - 3.1.
-If you are using SitePrism with Ruby 2.5-2.7 it is highly advisable to upgrade to a more modern
+SitePrism is built and tested to work on Ruby 2.7 - 3.2.
+If you are using SitePrism with Ruby 2.7 it is highly advisable to upgrade to a more modern
 Ruby (v3+), if for any other reason, to get a performance improvement!
 
 SitePrism should run on all major browsers. The gem's integration tests are run on Chrome and Firefox.
@@ -66,7 +66,7 @@ class SearchResults < SitePrism::Page
   end
 end
 
-# define sections used on multiple pages or multiple times on one page
+# Define sections that are used on multiple pages or multiple times on one page
 
 class Menu < SitePrism::Section
   element :search, 'a.search'
@@ -79,7 +79,7 @@ class SearchResults < SitePrism::Section
   element :blurb, 'span.result-description'
 end
 
-# now for some tests
+# Then we can write some tests
 
 When('I navigate to the google home page') do
   @home = Home.new
@@ -88,6 +88,7 @@ end
 
 Then('the home page should contain the menu and the search form') do
   @home.wait_until_menu_visible(wait: 5)
+  
   expect(@home).to have_menu
   expect(@home).to have_search_field
   expect(@home).to have_search_button
@@ -100,11 +101,13 @@ end
 
 Then('the search results page is displayed') do
   @results_page = SearchResults.new
+  
   expect(@results_page).to be_displayed
 end
 
 Then('the search results page contains 10 individual search results') do
   @results_page.wait_until_search_results_visible(wait: 5)
+  
   expect(@results_page).to have_search_results(count: 10)
 end
 
@@ -113,8 +116,6 @@ Then('the search results contain a link to the wikipedia sausages page') do
 end
 ```
 
-Now for the details...
-
 ## Setup
 
 ### Installation
@@ -166,19 +167,15 @@ And again, as above, a sample driver is no different to a normal driver instanti
 
 ## Introduction to the Page Object Model
 
-The Page Object Model is a test automation pattern that aims to create
-an abstraction of your site's user interface that can be used in tests.
-The most common way to do this is to model each page as a class, and
-to then use instances of those classes in your tests.
+The Page Object Model is a test automation pattern that aims to create an abstraction of your sites user
+interface that can be used in tests. The most common way to do this is to model each page as a class and
+then to use instances of those classes in your tests.
 
-If a class represents a page then each element of the page is
-represented by a method that, when called, returns a reference to that
-element that can then be acted upon (clicked, type in some text), or
-queried (is it enabled? / visible?).
+If a class represents a page then each element of the page is represented by a method that, when called, returns a
+reference to that element that can then be acted upon (clicked, type in some text), or queried (is it enabled? / visible?).
 
-SitePrism is based around this concept, but goes further as you'll see
-below by also allowing modelling of repeated sections that appear on
-multiple pages, or many times on a page using the concept of sections.
+SitePrism is based around this concept, but goes further as you'll see below by also allowing modelling of
+repeated sections that appear on multiple pages, or many times on a page using the concept of sections.
 
 ## Pages
 
@@ -216,9 +213,8 @@ class Home < SitePrism::Page
 end
 ```
 
-Note that setting a URL is **optional** - you only need to set a url if you want to be able to
-navigate directly to that page. It makes sense to set the URL for a page model of a
-home page or a login page, but probably not a search results page.
+Note that setting a URL is **optional** - you only need to set a url if you want to be able to navigate directly to that page.
+It makes sense to set the URL for a page model of a home page or a login page, but probably not a search results page.
 
 #### Parametrized URLs
 
@@ -281,10 +277,9 @@ navigate to the URL set against that page's class.
 
 ### Verifying that a particular page is displayed
 
-Automated tests often need to verify that a particular page is
-displayed. SitePrism can automatically parse your URL template
-and verify that whatever components your template specifies match the
-currently viewed page. For example, with the following URL template:
+Automated tests often need to verify that a particular page is displayed. SitePrism can automatically parse
+your templated URL and verify that whatever components your template specifies match the currently viewed page.
+For example, with the following URL template:
 
 ```ruby
 class Account < SitePrism::Page
@@ -302,10 +297,9 @@ expect(@account_page.current_url).to end_with('/accounts/22?token=ca2786616a4285
 expect(@account_page).to be_displayed
 ```
 
-Calling `#displayed?` will return true if the browser's current URL
-matches the page's template and false if it doesn't. It will wait for
-`Capybara.default_max_wait_time` seconds or you can pass an explicit
-wait time in seconds as the first argument like this:
+Calling `#displayed?` will return true if the browser's current URL matches the page's template and false if
+it doesn't. It will wait for `Capybara.default_max_wait_time` seconds or you can pass an explicit wait time in
+seconds as the first argument like this:
 
 ```ruby
 @account_page.displayed?(10) # wait up to 10 seconds for display
@@ -346,9 +340,8 @@ expect(@account_page.url_matches.dig('query', 'token')).to eq('ca2786616a4285bc'
 
 #### Falling back to basic regexp matchers
 
-If SitePrism's built-in URL matching is not sufficient for your needs
-you can override and use SitePrism's previous support for regular expression-based
-URL matchers by it by calling `set_url_matcher`:
+If SitePrism's built-in URL matching is not sufficient for your needs you can override and use SitePrism's
+support for regular expression-based URL matchers by it by calling `set_url_matcher`:
 
 ```ruby
 class Account < SitePrism::Page
@@ -377,6 +370,7 @@ end
 
 @account = Account.new
 @account.current_url #=> "http://www.example.com/account/123"
+
 expect(@account.current_url).to include('example.com/account/')
 ```
 
@@ -394,10 +388,9 @@ end
 
 ### HTTP vs. HTTPS
 
-You can easily tell if the page is secure or not by checking to see if
-the current URL begins with 'https' or not. SitePrism provides the
-`secure?` method that will return true if the current url begins with
-'https' and false if it doesn't. For example:
+You can easily tell if the page is secure or not by checking to see if the current URL begins with 'https' or not.
+SitePrism provides the `#secure?` method that will return true if the current url begins with 'https' and false if it doesn't.
+For example:
 
 ```ruby
 class Account < SitePrism::Page
@@ -405,16 +398,15 @@ end
 
 @account = Account.new
 @account.secure? #=> true/false
+
 expect(@account).to be_secure
 ```
 
 ## Elements
 
-Pages are made up of elements (text fields, buttons, combo boxes, etc),
-either individual elements or groups of them. Examples of individual
-elements would be a search field or a company logo image; examples of
-element collections would be items in any sort of list, eg: menu items,
-images in a carousel, etc.
+Pages are made up of elements (text fields, buttons, combo boxes, etc), either individual elements or groups of
+them. Examples of individual elements would be a search field or a company logo image; examples of element collections would
+be items in any sort of list, eg: menu items,images in a carousel, etc.
 
 ### Individual Elements
 
@@ -508,18 +500,16 @@ 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 THE SAME AS => expect(@home).not_to have_search_field
 end
 ```
 
 #### Waiting for an element to become visible
 
-A method that gets added by calling `element` is the
-`wait_until_<element_name>_visible` method.
+A method that gets added by calling `element` is the `wait_until_<element_name>_visible` method.
 This method delegates to [Capybara::Node::Matchers#has_selector?](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Matchers#has_selector%3F-instance_method).
-Calling this method will cause the test to wait for Capybara's default wait time for the element
-to become visible. You can customise the wait time by supplying a number
-of seconds to wait in-line or configuring the default wait time.
+Calling this method will cause the test to wait for Capybara's default wait time for the element to become visible. You can customise
+the wait time by supplying a number of seconds to wait in-line or configuring the default wait time.
 
 ```ruby
 @home.wait_until_search_field_visible # using the default wait time set
@@ -529,12 +519,10 @@ of seconds to wait in-line or configuring the default wait time.
 
 #### Waiting for an element to become invisible
 
-Another method added by calling `element` is the
-`wait_until_<element_name>_invisible` method.
+Another method added by calling `element` is the `wait_until_<element_name>_invisible` method.
 This method delegates to [Capybara::Node::Matchers#has_no_selector?](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Matchers#has_no_selector%3F-instance_method).
-Calling this method will cause the test to wait for Capybara's default
-wait time for the element to become invisible. You can as with the visibility
-waiter, customise the wait time in the same way.
+Calling this method will cause the test to wait for Capybara's default wait time for the element to become invisible.
+You can (as with the visibility waiter), customise the wait time in the same way.
 
 ```ruby
 @home.wait_until_search_field_invisible # using the default wait time set
@@ -544,9 +532,8 @@ waiter, customise the wait time in the same way.
 
 #### CSS Selectors vs. XPath Expressions
 
-While the above examples all use CSS selectors to find elements, it is
-possible to use XPath expressions too. In SitePrism, everywhere that you
-can use a CSS selector, you can use an XPath expression.
+While the above examples all use CSS selectors to find elements, it is possible to use XPath expressions too.
+In SitePrism, everywhere that you can use a CSS selector, you can use an XPath expression (Standard Capybara logic).
 
 An example:
 
@@ -1686,6 +1673,25 @@ When('I log in') do
 end
 ```
 
+## Shadow Root
+
+SitePrism allows you to interact with Shadow Roots too.
+
+### Creating an Shadow Root
+
+You can use the `section` methods and provide the arguments. Specify the reference name for the Shadow Root,
+the CSS selector to locate it, and add the `:shadow_root` option. For example:
+
+```ruby
+class Home < SitePrism::Page
+  section :foo, '.foo', shadow_root: true do
+    element :bar, '.bar'
+  end
+end
+```
+
+NB: By default `shadow_root` will be set to false
+
 ## SitePrism Configuration
 
 SitePrism can be configured to change its behaviour.

data/lib/site_prism/deprecator.rb

@@ -4,7 +4,7 @@ module SitePrism
   # [SitePrism::Deprecator]
   class Deprecator
     class << self
-      # @return SitePrism.logger.warn(msg)
+      # @return [SitePrism.logger.warn(msg)]
       #
       # Tells the user that they are using old functionality, which needs removing in the
       # next major version
@@ -15,22 +15,7 @@ module SitePrism
           warn("#{old} is being deprecated and should no longer be used.")
         end
 
-        warn("#{old} will be removed in SitePrism v5. You have been warned!")
-      end
-
-      # @return SitePrism.logger.debug(msg)
-      #
-      # Tells the user that they are using functionality which is non-optimal
-      # The functionality should usually provide a reason for it being poor, as well as an
-      # optional way of upgrading to something different
-      #
-      # 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 advised to be changed.")
-        debug("REASON: #{reason}.")
-        debug('Moving forwards into SitePrism v5, the default behaviour will change.')
-        debug("We advise you change to using #{new}") if new
+        warn("#{old} will be removed in SitePrism v6. You have been warned!")
       end
 
       private
@@ -38,10 +23,6 @@ module SitePrism
       def warn(msg)
         SitePrism.logger.warn(msg)
       end
-
-      def debug(msg)
-        SitePrism.logger.debug(msg)
-      end
     end
   end
 end

data/lib/site_prism/dsl/builder.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Builder]
+    #
+    # @api private
+    #
+    # The Building logic - Initially coming from `.build`
+    #   This will take a request to build from a DSL invocation such as `element` and generate a series of
+    #   helper methods and waiters. It will also generate the correct classes for `SitePrism::Section` objects
+    #
+    #   Whilst doing all of this, it will also build up a "map" of objects in memory which can be used for
+    #   future interrogation. There are 2 ways of this being stored currently (Default as a hash, Legacy as an array)
+    #
+    module Builder
+      # Return a list of all mapped items on a SitePrism class instance (Page or Section)
+      #
+      # @return [Hash]
+      def mapped_items
+        @mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
+      end
+
+      private
+
+      def build(type, name, *find_args)
+        invalid_element_name if invalid_element_name?(name)
+        blank_element(name) if find_args.empty?
+
+        mapped_items[type] << name.to_sym
+        yield
+        add_helper_methods(name, type, *find_args)
+      end
+
+      def invalid_element_name
+        raise InvalidDSLNameError, dsl_name_error
+      end
+
+      def invalid_element_name?(name)
+        !dsl_validation_disabled? && name_invalid?(name)
+      end
+
+      def dsl_validation_disabled?
+        SitePrism.dsl_validation_disabled || ENV.key?('SITEPRISM_DSL_VALIDATION_DISABLED')
+      end
+
+      def blank_element(name)
+        raise SitePrism::InvalidElementError, "#{name} has come from an item with no locators."
+      end
+
+      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)
+        create_visibility_waiter(name, *find_args)
+        create_invisibility_waiter(name, *find_args)
+      end
+
+      def create_existence_checker(element_name, *find_args)
+        method_name = "has_#{element_name}?"
+        create_helper_method(method_name, *find_args) do
+          define_method(method_name) do |*runtime_args|
+            args = merge_args(find_args, runtime_args)
+            element_exists?(*args)
+          end
+        end
+      end
+
+      def create_nonexistence_checker(element_name, *find_args)
+        method_name = "has_no_#{element_name}?"
+        create_helper_method(method_name, *find_args) do
+          define_method(method_name) do |*runtime_args|
+            args = merge_args(find_args, runtime_args)
+            element_does_not_exist?(*args)
+          end
+        end
+      end
+
+      def create_visibility_waiter(element_name, *find_args)
+        method_name = "wait_until_#{element_name}_visible"
+        create_helper_method(method_name, *find_args) do
+          define_method(method_name) do |*runtime_args|
+            args = merge_args(find_args, runtime_args, visible: true)
+            return true if element_exists?(*args)
+
+            raise SitePrism::ElementVisibilityTimeoutError
+          end
+        end
+      end
+
+      def create_invisibility_waiter(element_name, *find_args)
+        method_name = "wait_until_#{element_name}_invisible"
+        create_helper_method(method_name, *find_args) do
+          define_method(method_name) do |*runtime_args|
+            args = merge_args(find_args, runtime_args, visible: true)
+            return true if element_does_not_exist?(*args)
+
+            raise SitePrism::ElementInvisibilityTimeoutError
+          end
+        end
+      end
+
+      def create_helper_method(proposed_method_name, *find_args)
+        return blank_element(proposed_method_name) if find_args.empty?
+
+        yield
+      end
+
+      def extract_section_options(args, &block)
+        if args.first.is_a?(Class)
+          klass = args.shift
+          section_class = klass if klass <= SitePrism::Section
+        end
+
+        section_class = deduce_section_class(section_class, &block)
+        arguments = deduce_search_arguments(section_class, args)
+        [section_class, arguments]
+      end
+
+      def deduce_section_class(base_class, &block)
+        klass = base_class
+        klass = Class.new(klass || SitePrism::Section, &block) if block
+        return klass if klass
+
+        raise ArgumentError, 'You should provide descendant of SitePrism::Section class or/and a block as the second argument.'
+      end
+
+      def deduce_search_arguments(section_class, args)
+        extract_search_arguments(args) ||
+          extract_search_arguments(section_class.default_search_arguments) ||
+          invalidate_search_arguments!
+      end
+
+      def extract_search_arguments(args)
+        args if args && !args.empty?
+      end
+
+      def invalidate_search_arguments!
+        SitePrism.logger.error('Could not deduce search_arguments')
+        raise(ArgumentError, 'search arguments are needed in `section` definition or alternatively use `set_default_search_arguments`')
+      end
+    end
+  end
+end

data/lib/site_prism/dsl/locators.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Locators]
+    #
+    # The locator logic for scoping all items - for use in locators, boolean tests and waiters
+    #
+    # @api private
+    #
+    module Locators
+      private
+
+      def _find(*find_args)
+        kwargs = find_args.pop
+        shadow_root = kwargs.delete(:shadow_root) { false }
+        check_capybara_version_if_creating_shadow_root if shadow_root
+        to_capybara_node.find(*find_args, **kwargs).tap do |element|
+          break element.shadow_root if shadow_root
+        end
+      end
+
+      def _all(*find_args)
+        kwargs = find_args.pop
+        shadow_root = kwargs.delete(:shadow_root) { false }
+        check_capybara_version_if_creating_shadow_root if shadow_root
+        to_capybara_node.all(*find_args, **kwargs).tap do |element|
+          break element.map(&:shadow_root) if shadow_root
+        end
+      end
+
+      def element_exists?(*find_args)
+        kwargs = find_args.pop
+        kwargs.delete(:shadow_root)
+        to_capybara_node.has_selector?(*find_args, **kwargs)
+      end
+
+      def element_does_not_exist?(*find_args)
+        kwargs = find_args.pop
+        kwargs.delete(:shadow_root)
+        to_capybara_node.has_no_selector?(*find_args, **kwargs)
+      end
+
+      # Sanitize method called before calling any SitePrism DSL method or
+      # meta-programmed method. This ensures that the Capybara query is correct.
+      #
+      # Accepts any combination of arguments sent at DSL definition or runtime
+      # and combines them in such a way that Capybara can operate with them.
+      def merge_args(find_args, runtime_args, visibility_args = {})
+        find_args = find_args.dup
+        runtime_args = runtime_args.dup
+        options = visibility_args.dup
+        SitePrism.logger.debug("Initial args: #{find_args}, #{runtime_args}.")
+
+        recombine_args(find_args, runtime_args, options)
+
+        return [*find_args, *runtime_args, {}] if options.empty?
+
+        [*find_args, *runtime_args, options]
+      end
+
+      # Options re-combiner. This takes the original inputs and combines
+      # them such that there is only one hash passed as a final argument
+      # to Capybara.
+      #
+      # If the hash is empty, then the hash is omitted from the payload sent
+      # to Capybara, and the find / runtime arguments are sent alone.
+      #
+      # NB: If the +wait+ key is present in the options hash, even as false or 0, It will
+      # be set as the user-supplied value (So user error can be the cause for issues).
+      def recombine_args(find_args, runtime_args, options)
+        options.merge!(find_args.pop) if find_args.last.is_a? Hash
+        options.merge!(runtime_args.pop) if runtime_args.last.is_a? Hash
+        options[:wait] = Capybara.default_max_wait_time unless options.key?(:wait)
+      end
+
+      def check_capybara_version_if_creating_shadow_root
+        minimum_version = '3.37.0'
+        raise SitePrism::UnsupportedGemVersionError unless Capybara::VERSION >= minimum_version
+
+        SitePrism.logger.error("Shadow root support requires Capybara version >= #{minimum_version}. You are using #{Capybara::VERSION}.")
+      end
+    end
+  end
+end

data/lib/site_prism/dsl/methods.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Methods]
+    #
+    # The meta-programmed methods for using SitePrism during runtime. This public DSL contains all the methods
+    # you will use on `SitePrism::Page` or `SitePrism::Section` classes
+    #
+    module Methods
+      attr_reader :expected_items
+
+      # Sets the `expected_items` iVar on a class. This property is used in conjunction with
+      # `all_there?` to provide a way of granularising the check made to only interrogate a sub-set
+      # of DSL defined items
+      def expected_elements(*elements)
+        @expected_items = elements
+      end
+
+      # Creates an instance of a SitePrism Element - This will create several methods designed to
+      # Locate the element -> @return [Capybara::Node::Element]
+      # Check the elements presence or non-presence -> @return [Boolean]
+      # 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_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_runtime_block_supplied(self, name, runtime_block, :element)
+            _find(*merge_args(find_args, runtime_args))
+          end
+        end
+      end
+
+      # Creates a enumerable instance of a SitePrism Element - This will create several methods designed to
+      # Locate the enumerable element -> @return [Capybara::Result]
+      # Check the elements presence or non-presence -> @return [Boolean]
+      # 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_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_runtime_block_supplied(self, name, runtime_block, :elements)
+            _all(*merge_args(find_args, runtime_args))
+          end
+        end
+      end
+
+      # Creates an instance of a SitePrism Section - This will create several methods designed to
+      # Locate the section -> @return [SitePrism::Section]
+      # Check the section presence or non-presence -> @return [Boolean]
+      # Wait for the section to be present or not -> @return [TrueClass, SitePrism::Error]
+      # Validate certain properties about the section
+      def section(name, *args, &block)
+        section_class, find_args = extract_section_options(args, &block)
+        build(:section, name, *find_args) do
+          define_method(name) do |*runtime_args, &runtime_block|
+            section_element = _find(*merge_args(find_args, runtime_args))
+            section_class.new(self, section_element, &runtime_block)
+          end
+        end
+      end
+
+      # Creates an enumerable instance of a SitePrism Section - This will create several methods designed to
+      # Locate the sections -> @return [Array]
+      # Check the sections presence or non-presence -> @return [Boolean]
+      # Wait for the sections to be present or not -> @return [TrueClass, SitePrism::Error]
+      # Validate certain properties about the section
+      def sections(name, *args, &block)
+        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_runtime_block_supplied(self, name, runtime_block, :sections)
+            _all(*merge_args(find_args, runtime_args)).map do |element|
+              section_class.new(self, element)
+            end
+          end
+        end
+      end
+
+      def iframe(name, klass, *args)
+        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
+          define_method(name) do |&block|
+            raise MissingBlockError unless block
+
+            within_frame(*scope_find_args) { block.call(klass.new) }
+          end
+        end
+      end
+
+      private
+
+      def raise_if_build_time_block_supplied(parent_object, name, has_block, type)
+        return unless has_block
+
+        SitePrism.logger.debug("Type passed in: #{type}")
+        SitePrism.logger.error("#{name} has been defined as a '#{type}' item in #{parent_object}. It does not accept build-time blocks.")
+        raise SitePrism::UnsupportedBlockError
+      end
+
+      def deduce_iframe_element_find_args(args)
+        warn_on_invalid_selector_input(args)
+        case args[0]
+        when Integer then "iframe:nth-of-type(#{args[0] + 1})"
+        when String  then [:css, args[0]]
+        else args
+        end
+      end
+
+      def deduce_iframe_scope_find_args(args)
+        warn_on_invalid_selector_input(args)
+        case args[0]
+        when Integer then [args[0]]
+        when String  then [:css, args[0]]
+        else args
+        end
+      end
+
+      def warn_on_invalid_selector_input(args)
+        return unless looks_like_xpath?(args[0])
+
+        SitePrism.logger.warn('The arguments passed in look like xpath. Check your locators.')
+        SitePrism.logger.debug("Default locator strategy: #{Capybara.default_selector}")
+      end
+
+      def looks_like_xpath?(arg)
+        arg.is_a?(String) && arg.start_with?('/', './')
+      end
+    end
+  end
+end