watirsome 0.1.0

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: 'travis-ci'

data/.travis.yml

@@ -0,0 +1,4 @@
+langauge: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Alex Rodionov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,330 @@
+## watirsome
+
+Pure dynamic Watir-based page object DSL.
+
+[![Gem Version](https://badge.fury.io/rb/watirsome.png)](http://badge.fury.io/rb/watirsome)
+[![Build Status](https://secure.travis-ci.org/p0deje/watirsome.png)](http://travis-ci.org/p0deje/watirsome)
+[![Coverage Status](https://coveralls.io/repos/p0deje/watirsome/badge.png?branch=master)](https://coveralls.io/r/p0deje/watirsome)
+
+Inspired by [page-object](https://github.com/cheezy/page-object) and [watir-page-helper](https://github.com/alisterscott/watir-page-helper).
+
+### Installation
+
+Just like any other gem:
+
+```shell
+➜ gem install watirsome
+```
+
+Or using bundler:
+
+```ruby
+# Gemfile
+gem 'watirsome'
+```
+
+### Examples
+
+```ruby
+class Page
+  include Watirsome
+  
+  text_field :username, label: 'Username'
+  text_field :password, label: 'Password'
+  button :login, text: 'Login'
+  
+  def login(username, password)
+    self.username = username
+    self.password = password
+    login
+  end
+end
+```
+
+### Accessors
+
+Watirsome provides you with accessors DSL to isolate elements from your methods. 
+
+All accessors are just proxied to Watir, thus you free to use all its power in your page objects.
+
+```ruby
+class Page
+  include Watirsome
+  
+  # any method defined in Watir::Container are accessible
+  body :body
+  section :section, id: 'section_one'
+  element :svg, tag_name: 'svg'
+end
+```
+
+#### Locators
+
+You can use any kind of locators you use with Watir.
+
+```ruby
+class Page
+  include Watirsome
+  
+  body :body
+  section :one, id: 'section_one'
+  element :svg, tag_name: 'svg'
+  button :login, class: 'submit', index: 1 
+end
+
+page = Page.new(@browser)
+page.body_element  # equals to @browser.body
+page.section_one   # equals to @browser.section(id: 'section')
+page.svg_element   # equals to @browser.element(tag_name: 'svg')
+page.login_button  # equals to @browser.button(class: 'submit', index: 1)
+```
+
+Watirsome also provides you with opportunity to locate elements by using any boolean method Watir element supports.
+
+```ruby
+class Page
+  include Watirsome
+  
+  div :layer, class: 'layer', visible: true    
+  span :wrapper, class: 'span', exists: false  
+end
+
+page = Page.new(@browser)
+page.layer_div     # equals to @browser.divs(class: 'layer').find { |e| e.visible? == true }
+page.wrapper_span  # equals to @browser.divs(class: 'layer').find { |e| e.exists? == false }
+```
+
+You can also use proc/lambda/block to locate element. Block is executed in the context of initalized page, so other accessors can be used.
+
+```ruby
+class Page
+  include Watirsome
+  
+  div :layer, class: 'layer'
+  span :wrapper, -> { layer_div.span(class: 'span') }
+end
+
+page = Page.new(@browser)
+page.wrapper_span  # equals to @browser.div(class: 'layer').span(class: 'span')
+```
+
+Moreover, you can pass arguments to blocks!
+
+```ruby
+class Page
+  include Watirsome
+  
+  div :layer, class: 'layer'
+  a :link, do |text| 
+    layer_div.a(text: text)
+  end
+end
+
+page = Page.new(@browser)
+page.link_a('Login')  # equals to @browser.div(class: 'layer').a(text: 'Login')
+```
+
+#### Element accessors
+
+For each element, accessor method is defined which returns instance of `Watir::Element` (or subtype when applicable).
+
+Element accessor method name is `#{element_name}_#{tag_name}`.
+
+```ruby
+class Page
+  include Watirsome
+
+  section :section_one, id: 'section_one'
+  element :svg, tag_name: 'svg'
+end
+
+page = Page.new(@browser)
+page.section_one_section  #=> #<Watir::HTMLElement:0x201b2f994f32c922 selector={:tag_name=>"section"}>
+page.svg_element          #=> #<Watir::HTMLElement:0x15288276ab771162 selector={:tag_name=>"svg"}>
+```
+
+#### Readable accessors
+
+For each redable element, accessor method is defined which returns text of that element.
+
+Read accessor method name is `element_name`.
+
+Default redable methods are: `[:div, :span, :p, :h1, :h2, :h3, :h4, :h5, :h6, :select_list, :text_field, :textarea]`.
+
+You can make other elements redable by adding tag names to `Watirsome.redable`.
+
+```ruby
+# make section redable
+Watirsome.redable << :section
+
+class Page
+  include Watirsome
+
+  div :main, id: 'main_div'
+  section :date, id: 'date'
+end
+
+page = Page.new(@browser)
+page.main  # returns text of main div
+page.date  # returns text of date section
+```
+
+There is a bit of logic behind text retrieval:
+
+1. If element is a text field or textarea, return value
+2. If element is a select list, return text of first selected option
+3. Otherwise, return text
+
+#### Clickable accessors
+
+For each clickable element, accessor method is defined which performs click on that element.
+
+Click accessor method name is `element_name`.
+
+Default clickable methods are: `[:a, :link, :button]`.
+
+You can make other elements clickable by adding tag names to `Watirsome.clickable`.
+
+```ruby
+# make input clickable
+Watirsome.clickable << :input
+
+class Page
+  include Watirsome
+
+  a :login, text: 'Login'
+  input :submit, ->(type) { @browser.input(type: type) }
+end
+
+page = Page.new(@browser)
+page.login             # clicks on link
+page.submit('submit')  # clicks on submit input
+```
+
+#### Settable accessors
+
+For each settable element, accessor method is defined which sets value to that element.
+
+Click accessor method name is `#{element_name}=`.
+
+Default settable methods are: `[:text_field, :file_field, :textarea, :checkbox]`.
+
+You can make other elements settable by adding tag names to `Watirsome.settable`.
+
+```ruby
+# make input settable
+Watirsome.settable << :input
+
+class Page
+  include Watirsome
+
+  text_field :username, label: 'Username'
+  input :date, type: 'date'
+end
+
+page = Page.new(@browser)
+page.username = 'Username'         # sets value of username text field
+page.date = '2013-01-01', :return  # sends text to element and hits "Enter"
+```
+
+If found element responds to `#set`, accessor calls it. Otherwise, `#send_keys` is used.
+
+#### Selectable accessors
+
+For each selectable element, accessor method is defined which selects opton of that element.
+
+Click accessor method name is `#{element_name}=`.
+
+Default selectable methods are: `[:select_list]`.
+
+You can make other elements selectable by adding tag names to `Watirsome.selectable`. Though, why would you want?
+
+```ruby
+class Page
+  include Watirsome
+
+  select_list :country, label: 'Country'
+end
+
+page = Page.new(@browser)
+page.country = 'Russia'  #=> selects option with "Russia" text
+```
+
+### Initializers
+
+Watirsome provides you with initializers DSL to dynamically modify your pages/regions behavior. 
+
+#### Page initializer
+
+Each page may define `#initialize_page` method which will be used as page constructor.
+
+```ruby
+class Page
+  include Watirsome
+
+  def initialize_page
+    puts 'Initialized!'
+  end
+end
+
+Page.new(@browser)
+#=> 'Initialized!'
+```
+
+#### Region initializer
+
+Each region you include/extend may define `#initialize_region` method which will be called after page constructor.
+
+
+```ruby
+module HeaderRegion
+  def initialize_region
+    puts 'Initialzed header!'
+  end
+end
+
+module FooterRegion
+  def initialize_region
+    puts 'Initialzed footer!'
+  end
+end
+
+class Page
+  include Watirsome
+  include HeaderRegion
+  
+  def initialize_page
+    extend FooterRegion
+  end
+end
+
+Page.new(@browser)
+#=> 'Initialized header!'
+#=> 'Initialized footer!'
+```
+
+Regions are being cached, so, once initialzed, they won't be executed if you call `Page#initialize_regions` again.
+
+Each module is first checked if its name matches the regular expression of region (to make sure we don't touch unrelated included modules). By default, regexp is `/^.+(Region)$/`, but you can change it by altering `Watirsome.region_matcher`.
+
+```ruby
+Watirsome.region_matcher = /^.+(Region|Helper)$/
+```
+
+### Limitations
+
+1. Currently tested to work only with `watir-webdriver`. Let me know if it works using `watir-classic`.
+2. You cannot use `Watir::Browser#select` method as it's overriden by `Kernel#select`. Use `Watir::Browser#select_list` instead.
+3. You cannot use block arguments to locate elements for settable/selectable accessors (it makes no sense). However, you can use block arguments for all other accessors.
+
+### Contribute
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+* Send me a pull request. Bonus points for topic branches.
+
+### Copyright
+
+Copyright (c) 2013 Alex Rodionov. See LICENSE.md for details.

data/Rakefile

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |spec|
+  spec.rspec_opts = %w(--color --require fuubar --format Fuubar)
+  spec.pattern    = 'spec/**/*_spec.rb'
+end
+
+task default: :spec

data/lib/watirsome/accessors.rb

@@ -0,0 +1,228 @@
+module Watirsome
+  module Accessors
+    module ClassMethods
+
+      #
+      # Iterate thorugh Watir continer methods and define all necessary
+      # class methods of element accessors.
+      #
+      Watirsome.watir_methods.each do |method|
+        define_method method do |*args, &blk|
+          name, args = parse_args(args)
+          block = proc_from_args(args, &blk)
+          define_element_accessor(name, method, args, &block)
+          define_click_accessor(name, method, args, &block)  if Watirsome.clickable?(method)
+          define_read_accessor(name, method, args, &block)   if Watirsome.readable?(method)
+          define_set_accessor(name, method, args, &block)    if Watirsome.settable?(method)
+          define_select_accessor(name, method, args, &block) if Watirsome.selectable?(method)
+        end
+      end
+
+      private
+
+      #
+      # Returns name and locators.
+      # @api private
+      #
+      def parse_args(args)
+        return args.shift, args.shift
+      end
+
+      #
+      # Returns block retreived from locators.
+      # @api private
+      #
+      def proc_from_args(*args, &blk)
+        if block_given?
+          blk
+        else
+          block = args.shift
+          block.is_a?(Proc) && args.empty? ? block : nil
+        end
+      end
+
+      #
+      # Defines accessor which returns Watir element instance.
+      # Method name is element name + tag.
+      #
+      # @param [Symbol] name Element name
+      # @param [Symbol] method Watir method
+      # @param [Array] args Splat of locators
+      # @param [Proc] block Block as element retriever
+      # @api private
+      #
+      def define_element_accessor(name, method, *args, &block)
+        watir_args, custom_args = extract_custom_args(args)
+        define_method :"#{name}_#{method}" do |*opts|
+          if block_given?
+            instance_exec(*opts, &block)
+          else
+            grab_elements(method, watir_args, custom_args)
+          end
+        end
+      end
+
+      #
+      # Defines accessor which clicks Watir element instance.
+      # Method name is element name.
+      #
+      # @param [Symbol] name Element name
+      # @param [Symbol] method Watir method
+      # @param [Array] args Splat of locators
+      # @param [Proc] block Block as element retriever
+      # @api private
+      #
+      def define_click_accessor(name, method, *args, &block)
+        watir_args, custom_args = extract_custom_args(args)
+        define_method name do |*opts|
+          if block_given?
+            instance_exec(*opts, &block).click
+          else
+            grab_elements(method, watir_args, custom_args).click
+          end
+        end
+      end
+
+      #
+      # Defines accessor which returns text of Watir element instance.
+      # Method name is element name.
+      #
+      # For textfield and textarea, value is returned.
+      # For select list, selected option text is returned.
+      # For other elements, text is returned.
+      #
+      # @param [Symbol] name Element name
+      # @param [Symbol] method Watir method
+      # @param [Array] args Splat of locators
+      # @param [Proc] block Block as element retriever
+      # @api private
+      #
+      def define_read_accessor(name, method, *args, &block)
+        watir_args, custom_args = extract_custom_args(args)
+        define_method name do |*opts|
+          element = if block_given?
+                      instance_exec(*opts, &block)
+                    else
+                      grab_elements(method, watir_args, custom_args)
+                    end
+          case method
+          when :text_field, :textarea
+            element.value
+          when :select_list
+            element.options.detect(&:selected?).text
+          else
+            element.text
+          end
+        end
+      end
+
+      #
+      # Defines accessor which sets value of Watir element instance.
+      # Method name is element name + "=".
+      #
+      # Note that custom block arguments are not used here.
+      #
+      # @param [Symbol] name Element name
+      # @param [Symbol] method Watir method
+      # @param [Array] args Splat of locators
+      # @param [Proc] block Block as element retriever
+      # @api private
+      #
+      def define_set_accessor(name, method, *args, &block)
+        watir_args, custom_args = extract_custom_args(args)
+        define_method :"#{name}=" do |*opts|
+          element = if block_given?
+                      instance_exec(&block)
+                    else
+                      grab_elements(method, watir_args, custom_args)
+                    end
+          if element.respond_to?(:set)
+            element.set *opts
+          else
+            element.send_keys *opts
+          end
+        end
+      end
+
+      #
+      # Defines accessor which selects option Watir element instance.
+      # Method name is element name + "=".
+      #
+      # Note that custom block arguments are not used here.
+      #
+      # @param [Symbol] name Element name
+      # @param [Symbol] method Watir method
+      # @param [Array] args Splat of locators
+      # @param [Proc] block Block as element retriever
+      # @api private
+      #
+      def define_select_accessor(name, method, *args, &block)
+        watir_args, custom_args = extract_custom_args(args)
+        define_method :"#{name}=" do |*opts|
+          if block_given?
+            instance_exec(&block).select *opts
+          else
+            grab_elements(method, watir_args, custom_args).select *opts
+          end
+        end
+      end
+
+      #
+      # Extracts custom arguments which Watirsome gracefully handles from
+      # mixed array with Watir locators.
+      #
+      # @param [Array] args
+      # @return Two arrays: Watir locators and custom locators
+      # @api private
+      #
+      def extract_custom_args(*args)
+        identifier = args.shift
+        watir_args, custom_args = [], []
+        identifier.each_with_index do |hashes, index|
+          watir_arg, custom_arg = {}, {}
+          if hashes && !hashes.is_a?(Proc)
+            hashes.each do |k, v|
+              if Watir::Element.instance_methods.include? :"#{k}?"
+                custom_arg[k] = identifier[index][k]
+              else
+                watir_arg[k] = v
+              end
+            end
+          end
+          watir_args  << watir_arg  unless watir_arg.empty?
+          custom_args << custom_arg unless custom_arg.empty?
+        end
+
+        return watir_args, custom_args
+      end
+
+    end # ClassMethods
+
+
+    module InstanceMethods
+
+      private
+
+      #
+      # Calls Watir browser instance to find element.
+      #
+      # @param [Symbol] method Watir method
+      # @param [Array] watir_args Watir locators
+      # @param [Array] custom_args Custom locators
+      # @api private
+      #
+      def grab_elements(method, watir_args, custom_args)
+        if custom_args.empty?
+          @browser.send(method, *watir_args)
+        else
+          plural = Watirsome.plural?(method)
+          method = :"#{method}s" unless plural
+          elements = @browser.send(method, *watir_args)
+          custom_args.first.each { |k, v| elements.to_a.select! { |e| e.send(:"#{k}?") == v } }
+          plural ? elements : elements.first
+        end
+      end
+
+    end # InstanceMethods
+  end # Accessors
+end # Watirsome

data/lib/watirsome/initializers.rb

@@ -0,0 +1,42 @@
+module Watirsome
+  module Initializers
+    
+    #
+    # Initializes page class.
+    # Allows to define "#initialize_page" which will be called as page constructor.
+    # After page is initialized, iterates through region and initialize each of them.
+    #
+    def initialize(browser)
+      @browser = browser
+      initialize_page if respond_to?(:initialize_page)
+      initialize_regions
+    end
+
+    #
+    # Iterates through definitions of "#initialize_region", thus implementing
+    # polymorphic Ruby modules (i.e. page regions).
+    #
+    # Only works with modules matching "Watirsome.region_matcher" regexp.
+    # @see Watirsome.region_matcher
+    #
+    def initialize_regions
+      # regions cacher
+      @initialized_regions ||= []
+      # get included and extended modules
+      modules = self.class.included_modules + (class << self; self end).included_modules
+      modules.uniq!
+      # make sure only necessary modules are being called
+      regexp = Watirsome.region_matcher
+      modules.select! { |m| regexp === m.to_s }
+      modules.each do |m|
+        # check that constructor is defined and we haven't called it before
+        if m.instance_methods.include?(:initialize_region) && !@initialized_regions.include?(m)
+          m.instance_method(:initialize_region).bind(self).call
+          # cache region
+          @initialized_regions << m
+        end
+      end
+    end
+
+  end # Initializers
+end # Watirsome

data/lib/watirsome/version.rb

@@ -0,0 +1,3 @@
+module Watirsome
+  VERSION = '0.1.0'
+end # Watirsome