watir_pump 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fbc8d45a395114f228e95ff0295d63f805413569
-  data.tar.gz: 44ecc359ec890c7cebca9ea0c01b4083574b6c14
+  metadata.gz: 825e0f544c5d9359dc7d582330d6778c1ff643c7
+  data.tar.gz: 3ffb4f6c5084f2fbe28ac99137c628abd4866817
 SHA512:
-  metadata.gz: d996f58058addce4787230775fd4812b0c54ec33961a798c221f80ec5e357388fc588bb9db6ecd25432feb0ec570dcc44a400c0b6493c6fb8beae136802be19d
-  data.tar.gz: 2182e0353b6b46fb3a0194681fea3bcea8653db6040bbca6fa2890886c68fc29a8349260a2c87fec70ba1d5961a0be1f40163d476ada64997802cf213e1f283c
+  metadata.gz: 5b3628fb10dac751866eef5ae29f26b2580c8715a29ab89ace6ae0497693bfbf8ca9c396e8217e997e3ed7217fe45adbe448df354b7541f51dde1d4c6caa9938
+  data.tar.gz: 2479f5aea9ebcf75751f3a6cf1e07b3a6c96228a87a3eded35cdd525d55640bd8bb70fd28c5811f088c88e095a249806f411bd344ccd6b82e28c3f5181a6fb2e

data/lib/watir_pump/component.rb

@@ -14,6 +14,36 @@ require_relative 'components/dropdown_list'
 require_relative 'components/flag'
 
 module WatirPump
+  # Representation of a reusable page component.
+  #
+  # Next to class methods documented below it contains also dynamically
+  # generated methods for declaring +Watir::Elements+ belonging to the
+  # component.
+  #
+  # See {WatirPump::WATIR_METHOD_MAPPING} for a complete list of elemet methods.
+  #
+  # There are also dynamically generated class methods that create +reader+,
+  # +writer+ and +clicker+ instance methods.
+  # Please refer to {file:README.md} for more details.
+  #
+  # @example
+  #   class MyComponent < WatirPump::Component
+  #     # declaration of a div element
+  #     # instance method `description` returns Watir::Div
+  #     div :description, id: 'desc'
+  #
+  #     # declaration of a div element reader
+  #     # instance method `description` returns String
+  #     div_reader :description, id: 'desc'
+  #
+  #     # declaration of a button element clicker
+  #     # instance method `login` clicks on the button
+  #     button_clicker :login, id: 'submit'
+  #
+  #     # declaration of a text_field writer
+  #     # instance method `surname=(value)` sets value of the text_field
+  #     text_field_writer :surname, id: 'surname'
+  #   end
   class Component # rubocop:disable Metrics/ClassLength
     extend Forwardable
 
@@ -21,7 +51,12 @@ module WatirPump
 
     delegate Constants::METHODS_FORWARDED_TO_ROOT => :root
 
+    # Reference to browser instance
+    # @return [Watir::Browser]
     attr_reader :browser
+
+    # Parent {Component}. +nil+ for Pages
+    # @return [Component]
     attr_reader :parent
 
     class << self
@@ -35,10 +70,16 @@ module WatirPump
         end
       end
 
+      # Returns a set of declared element readers. Used by {form_data}
+      #
+      # @return [Set<Symbol>]
       def form_field_readers
         @form_field_readers ||= Set.new
       end
 
+      # Returns a set of declared element writers. Used by {fill_form}
+      #
+      # @return [Set<Symbol>]
       def form_field_writers
         @form_field_writers ||= Set.new
       end
@@ -48,11 +89,35 @@ module WatirPump
       include Components::DropdownList
       include Components::Flag
 
+      # Declares a custom element reader.
+      # @example
+      #   custom_reader :price, -> { root.span(id: 'price').text.to_f }
+      #   custom_reader :price2
+      #
+      #   def price2
+      #     root.span(id: 'price').text.to_f
+      #   end
+      #
+      # @param [Symbol] name Name of the reader method
+      # @param [Proc] Method body (optional). If not provided a regular instance
+      #   with given name has to be declared
       def custom_reader(name, code = nil)
         form_field_readers << name
         query(name, code) if code
       end
 
+      # Declares a custom element writer.
+      # @example
+      #   custom_writer :price, ->(v) { root.text_field(id: 'price').set(v) }
+      #   custom_writer :price2
+      #
+      #   def price2=(v)
+      #     root.text_field(id: 'price').set(v)
+      #   end
+      #
+      # @param [Symbol] name Name of the writer method (without trailing '=')
+      # @param [Proc] Method body (optional). If not provided a regular instance
+      #   with given name (with trailing '=') has to be declared
       def custom_writer(name, code = nil)
         form_field_writers << name
         query("#{name}=", code) if code
@@ -68,6 +133,7 @@ module WatirPump
           end
         end
       end
+      private_class_method :define_reader
 
       def self.define_writer(watir_method)
         define_method "#{watir_method}_writer" do |name, *args|
@@ -78,6 +144,7 @@ module WatirPump
           end
         end
       end
+      private_class_method :define_writer
 
       def self.define_accessor(watir_method) # rubocop:disable Metrics/AbcSize
         define_method "#{watir_method}_accessor" do |name, *args|
@@ -95,6 +162,7 @@ module WatirPump
           end
         end
       end
+      private_class_method :define_accessor
 
       # Methods for element content readers
       # span_reader, :title, id: asd
@@ -124,12 +192,28 @@ module WatirPump
         end
       end
 
+      # A shorthand to generate one-liner instance methods
+      #
+      # @example
+      #   query :sum, ->(a, b) { a + b }
+      #   # is equivalent to:
+      #   def sum(a, b)
+      #     a + b
+      #   end
+      #
+      # @param [Symbol] name Name of the method
+      # @param [Proc] p Body of the method
       def query(name, p)
         define_method(name) do |*args|
           instance_exec(*args, &p)
         end
       end
 
+      # Declares an element located with lambda.
+      # @example
+      #   element :name, -> { root.span(id: 'name') }
+      #
+      # @return [Watir::Element]
       def element(name, p)
         define_method(name) do |*args|
           ret = instance_exec(*args, &p)
@@ -143,6 +227,12 @@ module WatirPump
         end
       end
 
+      # Declares an element collection located with lambda.
+      # @example
+      #   # mind the plural in watir method name: `lis` - not `li`!
+      #   elements :items, -> { root.lis(class: 'item') }
+      #
+      # @return [Watir::ElementCollection]
       def elements(name, p)
         define_method(name) do |*args|
           ret = instance_exec(*args, &p)
@@ -156,11 +246,33 @@ module WatirPump
         end
       end
 
+      # Declares anonymous component (namespace).
+      # @example
+      #   class HomePage < WatirPump::Page
+      #     region :login_box, :div, id: 'login_box' do
+      #       text_field :username, id: 'user'
+      #       text_field :password, id: 'pass'
+      #       button :login, id: 'login'
+      #     end
+      #
+      #     def do_login(user, pass)
+      #       login_box.username.set user
+      #       login_box.password.set pass
+      #       login_box.login.click
+      #     end
+      #   end
       def region(name, loc_method = nil, *loc_args, &blk)
         klass = Class.new(Component) { instance_exec(&blk) }
         component(name, klass, loc_method, *loc_args)
       end
 
+      # Declares a component of a given class under a given method name.
+      # @example
+      #   component :login_form1, LoginForm, :div, id: 'login_form1'
+      #   component :login_form2, LoginForm, -> { root.div(id: 'login_form2') }
+      #
+      # @param [Symbol] name Name of the method to access the component instance
+      # @param [Class] klass Class of the declared component
       def component(name, klass, loc_method = nil, *loc_args)
         define_method(name) do |*args|
           node = find_element_raw(watir_method: loc_method,
@@ -177,6 +289,14 @@ module WatirPump
         end
       end
 
+      # Declares a component collection
+      #   of a given class under a given method name.
+      # @example
+      #   components :products1, ProductList, :divs, class: 'product'
+      #   components :products2, ProductList, -> { root.divs(class: 'product') }
+      #
+      # @param [Symbol] name Name of the method to access the component list
+      # @param [Class] klass Class of the component in the list
       def components(name, klass, loc_method = nil, *loc_args)
         define_method(name) do |*args|
           nodes = find_element_raw(watir_method: loc_method,
@@ -193,6 +313,13 @@ module WatirPump
         end
       end
 
+      # Decorate the result of given method with a list of wrapper classes.
+      #
+      # @example
+      #   decorate :products, ProductCollection, AccessByNameCollection
+      #
+      # @param [Symbol] method Name of the method to be decorated
+      # @param [*Class] klasses List of wrapper classes
       def decorate(method, *klasses)
         klasses.each do |klass|
           original_name = "#{method}_before_#{klass}".to_sym
@@ -202,53 +329,47 @@ module WatirPump
           end
         end
       end
+    end # << self
 
-      def decorate2(method, code)
-        original_name = "#{method}_before_decorate2".to_sym
-        alias_method original_name, method
-        define_method method do |*args|
-          v = send(original_name, *args)
-          instance_exec(v, &code)
-        end
-      end
-    end
-
+    # Invoked implicity by WatirPump framework.
+    #
+    # @param [Watir::Browser] browser Reference to browser instance
+    # @param [Component] parent Parent Component
+    # @param [Watir::Element] root_node Component mounting point in the DOM tree
     def initialize(browser, parent = nil, root_node = nil)
       @browser = browser
       @parent = parent
       @root_node = root_node
     end
 
+    # Component mounting point in the DOM tree.
+    # All component elements are located relatively to it.
+    # For {Page} instances it points to +browser+
+    #
+    # @return [Watir::Element]
     def root
       return @root_node if @root_node
       return browser if parent.nil?
-      ret = parent.root
-      ret.class.name.include?('Collection') ? ret.first : ret
+      parent.root
     end
     alias node root
 
-    def form_field_writers
-      return @form_field_writers if @form_field_writers
-      @form_field_writers = Set.new
-      self.class.ancestors.each do |a|
-        if a.respond_to? :form_field_writers
-          @form_field_writers += a.form_field_writers
-        end
-      end
-      @form_field_writers
-    end
-
-    def form_field_readers
-      return @form_field_readers if @form_field_readers
-      @form_field_readers = Set.new
-      self.class.ancestors.each do |a|
-        if a.respond_to? :form_field_readers
-          @form_field_readers += a.form_field_readers
-        end
-      end
-      @form_field_readers
-    end
-
+    # Invokes element writer methods of given names with given values
+    # @example
+    #   class MyPage < WatirPump::Page
+    #     text_field_writer :first_name, id: 'first_name'
+    #     text_field_writer :last_name, id: 'last_name'
+    #     flag_writer :confirmed, id: 'confirmed'
+    #   end
+    #   MyPage.use do
+    #     fill_form(first_name: 'John', last_name: 'Smith', confirmed: true)
+    #     # is a shorthand for:
+    #     self.first_name = 'John'
+    #     self.last_name = 'Smith'
+    #     self.confirmed = true
+    #   end
+    #
+    # @param Hash data Names of writer methods (symbols), and values for them.
     def fill_form(data)
       missing = data.to_h.keys - form_field_writers.to_a
       unless missing.empty?
@@ -259,12 +380,30 @@ module WatirPump
       end
     end
 
+    # Same as {fill_form} but additionally invokes `submit` method if it exists.
+    # Otherwise raises an Exception.
+    #
+    # @param Hash data Names of writer methods (symbols), and values for them.
     def fill_form!(data)
       fill_form(data)
       raise ':fill_form! requries :submit method' unless respond_to? :submit
       submit
     end
 
+    # Invokes all reader methods at once and returns their values.
+    # @example
+    #   class MyPage < WatirPump::Page
+    #     span_reader :first_name, id: 'first_name'
+    #     span_reader :last_name, id: 'last_name'
+    #     flag_reader :confirmed, id: 'confirmed'
+    #   end
+    #   MyPage.use do
+    #     data = form_data
+    #     data == {first_name: 'John', last_name: 'Smith', confirmed: true}
+    #   end
+    #
+    # @return [Hash] Names of declared reader methods (symbols)
+    #   and values they returned.
     def form_data
       {}.tap do |h|
         form_field_readers.map do |field|
@@ -273,6 +412,30 @@ module WatirPump
       end
     end
 
+    private
+
+    def form_field_writers
+      return @form_field_writers if @form_field_writers
+      @form_field_writers = Set.new
+      self.class.ancestors.each do |a|
+        if a.respond_to? :form_field_writers
+          @form_field_writers += a.form_field_writers
+        end
+      end
+      @form_field_writers
+    end
+
+    def form_field_readers
+      return @form_field_readers if @form_field_readers
+      @form_field_readers = Set.new
+      self.class.ancestors.each do |a|
+        if a.respond_to? :form_field_readers
+          @form_field_readers += a.form_field_readers
+        end
+      end
+      @form_field_readers
+    end
+
     def find_element(watir_method, args, loc_args = nil)
       find_element_raw(watir_method: watir_method,
                        watir_method_args: args,

data/lib/watir_pump/constants.rb

@@ -39,6 +39,7 @@ module WatirPump
       h4
       h5
       h6
+      li
     ].freeze
   end
 end

data/lib/watir_pump/page.rb

@@ -5,18 +5,30 @@ require 'addressable/template'
 require_relative 'component'
 
 module WatirPump
+  # Representation of a single page of the application under test.
+  #
+  # Implements +Singleton+ pattern.
   class Page < Component
     class << self
       extend Forwardable
 
+      # List of class methods forwarded to the singleton instance
       INSTANCE_DELEGATED_METHODS = %i[
         browser
         open open_yield open_dsl
         use use_yield use_dsl
-        act act_yield use_dsl
+        act act_yield act_dsl
+        loaded?
+        matches_current_url?
+        url_template
       ].freeze
       delegate INSTANCE_DELEGATED_METHODS => :instance
 
+      # Class macro declaring Page's URI template. Example: +'/jobs/\{job_id}'+
+      #
+      # @see https://github.com/sporkmonger/addressable
+      # @param [String] uri URI of current page.
+      #   Compliant with +Addressable::Template+
       def uri(uri = nil)
         return @uri if @uri
         if uri.nil?
@@ -29,15 +41,27 @@ module WatirPump
         @uri
       end
 
-      def loaded?
-        Addressable::Template.new(instance.url_template).match browser.url
-      end
-
+      # Returns singleton instance of current Page
+      #
+      # @return [Page]
       def instance
         @instance ||= new(WatirPump.config.browser)
       end
     end # << self
 
+    # Returns complete (base plus URI) URL template for current Page
+    #
+    # @return [String]
+    def url_template
+      WatirPump.config.base_url + self.class.uri
+    end
+
+    # Opens the page in the browser and executes passed block in the scope
+    # of the page instance. Depending on the value of
+    # +WatirPump.config.call_page_blocks_with_yield+ method {open_yield}
+    # or {open_dsl} is called internally
+    #
+    # @param [Hash] params Parameters for the URL template
     def open(params = {}, &blk)
       if WatirPump.config.call_page_blocks_with_yield
         open_yield(params, &blk)
@@ -46,6 +70,17 @@ module WatirPump
       end
     end
 
+    # Opens the page in the browser and executes passed block in the scope
+    # of the page instance. Current +page+ and +browser+ references are
+    # passed to the yielded block.
+    #
+    # @example
+    #   UserPage.open_yield(id: 123) do |page, browser|
+    #     puts page.root.h1.text
+    #     puts browser.title
+    #   end
+    #
+    # @param [Hash] params Parameters for the URL template
     def open_yield(params = {}, &blk)
       url = Addressable::Template.new(url_template).expand(params).to_s
       browser.goto url
@@ -53,6 +88,16 @@ module WatirPump
       self
     end
 
+    # Opens the page in the browser and executes passed block in the scope
+    # of the page instance (+instance_exec+).
+    #
+    # @example
+    #   UserPage.open_dsl(id: 123) do
+    #     puts root.h1.text
+    #     puts browser.title
+    #   end
+    #
+    # @param [Hash] params Parameters for the URL template
     def open_dsl(params = {}, &blk)
       url = Addressable::Template.new(url_template).expand(params).to_s
       browser.goto url
@@ -60,6 +105,10 @@ module WatirPump
       self
     end
 
+    # Executes passed block in the scope of the page instance.
+    # Depending on the value of
+    # +WatirPump.config.call_page_blocks_with_yield+ method {use_yield}
+    # or {use_dsl} is called internally
     def use(&blk)
       if WatirPump.config.call_page_blocks_with_yield
         use_yield(&blk)
@@ -69,6 +118,15 @@ module WatirPump
     end
     alias act use
 
+    # Executes passed block in the scope of the page instance.
+    # Current +page+ and +browser+ references are
+    # passed to the yielded block.
+    #
+    # @example
+    #   UserPage.use_yield do |page, browser|
+    #     puts page.root.h1.text
+    #     puts browser.title
+    #   end
     def use_yield
       wait_for_loaded
       yield self, browser
@@ -76,6 +134,14 @@ module WatirPump
     end
     alias act_yield use_yield
 
+    # Executes passed block in the scope of the page instance.
+    # (+instance_exec+)
+    #
+    # @example
+    #   UserPage.use_dsl do
+    #     puts root.h1.text
+    #     puts browser.title
+    #   end
     def use_dsl(&blk)
       wait_for_loaded
       instance_exec(&blk)
@@ -83,10 +149,9 @@ module WatirPump
     end
     alias act_dsl use_dsl
 
-    def url_template
-      WatirPump.config.base_url + self.class.uri
-    end
-
+    # Waits until current Page is loaded
+    #
+    # @return [Page] self
     def wait_for_loaded
       Watir::Wait.until(message: "Timeout waiting for #{self} to load") do
         loaded?
@@ -94,12 +159,19 @@ module WatirPump
       self
     end
 
+    # Predicate denoting if page is ready to be interacted with
+    # Overload in child class to customize the readiness criteria
+    #
+    # @return [Boolean]
     def loaded?
-      self.class.loaded?
+      matches_current_url?
     end
 
-    def uri
-      self.class.uri
+    # Predicate denoting if current browser URL matches pages `uri` template
+    #
+    # @return [Boolean]
+    def matches_current_url?
+      Addressable::Template.new(url_template).match browser.url
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: watir_pump
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Bartek Wilczek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-06 00:00:00.000000000 Z
+date: 2018-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport