test-page 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+rvm:
+ - 1.8.7
+ - 1.9.2
+ - 1.9.3

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--no-private
+--hide-void-return
+--title "Test::Page"
+--files LICENSE
+--default-return ""

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Jarmo Pertman
+
+MIT License
+
+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,106 @@
+# Test::Page
+
+[![Build Status](https://secure.travis-ci.org/jarmo/test-page.png)](http://travis-ci.org/jarmo/test-page)
+[![Dependency Status](https://gemnasium.com/jarmo/test-page.png)](https://gemnasium.com/jarmo/test-page)
+[![Code Quality](https://codeclimate.com/badge.png)](https://codeclimate.com/github/jarmo/test-page)
+
+Test::Page helps you to write easily maintainable integration tests by implementing [Page Objects](https://code.google.com/p/selenium/wiki/PageObjects) pattern.
+
+Page Objects may be objects representing whole pages like LoginPage, ProfilePage or part of the pages like LoginForm, Header etc.
+
+Test::Page can be described like:
+
+* Is framework agnostic - you can use it with any library you want - [Watir](http://watir.com), [Selenium](http://seleniumhq.org/), [Capybara](https://github.com/jnicklas/capybara) etc.
+* Has really [easy API](http://rubydoc.info/github/jarmo/test-page/frames) - you can start testing right away instead of spending too much time to learn new framework.
+* Has really small codebase - even if you can't remember that small API you can dig right into the code - it's less than 100 lines!
+* Despite of its name you may use it with [RSpec](http://rspec.info/), [Test::Unit](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/test/unit/rdoc/Test/Unit.html) or any other testing library.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'test-page'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install test-page
+
+## Usage
+
+The following example uses Watir with RSpec, but you can use whichever library
+you like.
+
+[Check out Selenium example](https://github.com/jarmo/test-page/tree/master/examples) instead, if that's your flavor of choice.
+
+This is the spec we are trying to run:
+
+    # spec/search_spec.rb
+
+    require "test/page"
+    require "watir"
+    require File.expand_path("search_page", File.dirname(__FILE__))
+
+    describe "Bing" do
+      
+      let(:browser)     { Watir::Browser.new }
+      let(:search_page) { SearchPage.new }
+      
+      before { Test::Page.browser = browser }
+      after  { browser.close }
+
+      it "finds Google" do
+        results_page = search_page.search "google"
+        results_page.should have(10).results
+        results_page.results[0].should =~ /google/i
+      end
+
+      it "finds Bing itself" do
+        results_page = search_page.search "bing"
+        results_page.results.should include("Bing")
+      end
+    end
+
+Let's create the SearchPage object:
+
+    # spec/support/page/search_page.rb
+
+    require File.expand_path("results_page", File.dirname(__FILE__))
+
+    class SearchPage < Test::Page
+      element { browser.div(:id => "sbox") }
+
+      def setup
+        browser.goto "http://bing.com"
+      end
+
+      def search(term)
+        text_field(:id => "sb_form_q").set term
+        button(:id => "sb_form_go").click
+        redirect_to ResultsPage, browser.ul(:id => "wg0")
+      end
+    end
+
+Let's create the ResultsPage object:
+
+    # spec/support/page/results_page.rb
+
+    class ResultsPage < Test::Page
+      def results
+        modify lis(:class => "sa_wr").map(&:text),
+          :include? => proc { |term|
+            regexp = Regexp.new Regexp.escape(term)
+            results.any? { |result| result =~ regexp }
+        }
+      end
+    end
+
+There you have it, a fully functional spec using two page objects. Reference to the
+[API documentation](http://rubydoc.info/github/jarmo/test-page/frames) for more usage information.
+
+## License
+
+Copyright (c) Jarmo Pertman (jarmo.p@gmail.com). See LICENSE for details.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/examples/selenium/results_page.rb

@@ -0,0 +1,9 @@
+class ResultsPage < Test::Page
+  def results
+    modify find_elements(:class => "sa_wr").map(&:text),
+      :include? => proc { |term|
+        regexp = Regexp.new Regexp.escape term
+        results.any? {|result| result =~ regexp}
+      }
+  end
+end

data/examples/selenium/search_page.rb

@@ -0,0 +1,15 @@
+require File.expand_path("results_page", File.dirname(__FILE__))
+
+class SearchPage < Test::Page
+  element { browser.find_element(id: "sbox") }
+
+  def setup
+    browser.navigate.to("http://bing.com")
+  end
+
+  def search(term)
+    find_element(:id => "sb_form_q").send_keys term
+    find_element(:id => "sb_form_go").click
+    redirect_to ResultsPage, browser.find_element(:id => "wg0")
+  end
+end

data/examples/selenium/search_spec.rb

@@ -0,0 +1,23 @@
+require "test/page"
+require "selenium-webdriver"
+require File.expand_path("search_page", File.dirname(__FILE__))
+
+describe "Bing" do
+
+  let(:browser)     { Selenium::WebDriver.for :firefox }
+  let(:search_page) { SearchPage.new }
+  
+  before { Test::Page.browser = browser }
+  after  { browser.quit }
+
+  it "finds Google" do
+    results_page = search_page.search "google"
+    results_page.should have(10).results
+    results_page.results[0].should =~ /google/i
+  end
+
+  it "finds Bing itself" do
+    results_page = search_page.search "bing"
+    results_page.results.should include("Bing")
+  end
+end

data/examples/watir/results_page.rb

@@ -0,0 +1,9 @@
+class ResultsPage < Test::Page
+  def results
+    modify lis(:class => "sa_wr").map(&:text),
+      :include? => proc { |term|
+        regexp = Regexp.new Regexp.escape(term)
+        results.any? { |result| result =~ regexp }
+    }
+  end
+end

data/examples/watir/search_page.rb

@@ -0,0 +1,15 @@
+require File.expand_path("results_page", File.dirname(__FILE__))
+
+class SearchPage < Test::Page
+  element { browser.div(:id => "sbox") }
+
+  def setup
+    browser.goto "http://bing.com"
+  end
+
+  def search(term)
+    text_field(:id => "sb_form_q").set term
+    button(:id => "sb_form_go").click
+    redirect_to ResultsPage, browser.ul(:id => "wg0")
+  end
+end

data/examples/watir/search_spec.rb

@@ -0,0 +1,23 @@
+require "test/page"
+require "watir"
+require File.expand_path("search_page", File.dirname(__FILE__))
+
+describe "Bing" do
+  
+  let(:browser)     { Watir::Browser.new }
+  let(:search_page) { SearchPage.new }
+  
+  before { Test::Page.browser = browser }
+  after  { browser.close }
+
+  it "finds Google" do
+    results_page = search_page.search "google"
+    results_page.should have(10).results
+    results_page.results[0].should =~ /google/i
+  end
+
+  it "finds Bing itself" do
+    results_page = search_page.search "bing"
+    results_page.results.should include("Bing")
+  end
+end

data/lib/test/page.rb

@@ -0,0 +1,156 @@
+require File.expand_path("page/version", File.dirname(__FILE__))
+require 'forwardable'
+
+module Test
+  class Page
+    extend Forwardable
+
+    def_delegators :element, :present?, :p
+
+    class << self
+      # Set and get the browser object for {Page}.
+      #
+      # This makes it possible to reuse one global browser object between
+      # different {Page} objects. It will be also shared between sub-classes of {Page}
+      # class.
+      #
+      # @example Set Watir browser object as the global browser
+      #   Test::Page.browser = Watir::Browser.new
+      attr_accessor :browser
+
+      # @private
+      attr_reader :element_block 
+
+      # Set element for the {Page} via block.
+      # It will be evaluated lazily after {Page} has been instantiated.
+      #
+      # Element is like the container of the {Page} - everything outside of that element
+      # is not considered as part of the {Page}.
+      # Use as specific element as possible.
+      #
+      # @example Use Watir::Div as an {element}. 
+      #   class MyPage < Test::Page
+      #     element { browser.div(:id => "search") }
+      #   end
+      def element(&block)
+        @element_block = block
+      end
+    end
+
+    attr_writer :browser
+
+    # Set and get the browser object for specific {Page} instance.
+    #
+    # This is useful if some specific {Page} instance needs a different browser
+    # than is set via {.browser} method. Popup browser windows might be
+    # one example.
+    #
+    # If browser is not set via {#browser} then browser set via
+    # {.browser} will be used.
+    def browser
+      @browser || parent_page_browser
+    end
+
+    # Get the element instance.
+    #
+    # When {#setup} is defined, it will be executed once per {Page} instance.
+    #
+    # @return [Object] if element is specified for {#initialize}.
+    # @return [Object] otherwise {.element} block is evaluated once per {Page} instance and its value will be returned.
+    def element
+      @setup_done ||= begin
+                        setup if respond_to?(:setup)
+                        true
+                      end
+      @element ||= begin
+                     element_proc = self.class.element_block
+                     element_proc && instance_eval(&element_proc)
+                   end
+    end
+
+    # @param [Object] Element element for the {Page}. {.element} set via block will be used if not specified.
+    def initialize(element=nil)
+      @element = element
+    end
+
+    # Add or modify element instance methods.
+    #
+    # When element does not have the specified method then that method will be
+    # added to the specific element instance.
+    # When element has specified method it will be invoked before invoking the
+    # specified method.
+    #
+    # @example Add #png? method to Watir::Image
+    #   class Gallery < Test::Page
+    #     def thumbnail
+    #       image = img(:id => "thumbnail")
+    #       modify image,
+    #         :png? => proc { File.extname(image.src).downcase == ".png" }
+    #     end
+    #   end
+    #
+    #   Gallery.new.thumbnail.png? # returns true for images, which have
+    #                              # the src attribute set to png.
+    #
+    # @example Modify Watir::Button#click to return new MainPage instance after click
+    #   class LoginForm < Test::Page
+    #     def login_button
+    #       modify button(:id => "login"),
+    #         :click => proc { redirect_to MainPage }
+    #     end
+    #   end
+    #
+    #   LoginForm.new.login_button.click # performs the click and returns
+    #                                    # a new MainPage instance.
+    #
+    # @param [Object] Element element to modify.
+    # @param [Hash<Symbol,Proc>] Hash of method name as a Symbol and body as a Proc pairs.
+    #
+    # @return [Object] Modified Element instance.
+    def modify(element, methods)
+      methods.each_pair do |meth, return_value|
+        element.instance_eval do 
+          singleton = class << self; self end
+
+          singleton.send :alias_method, "__#{meth}", meth if respond_to? meth
+          singleton.send :define_method, meth do |*args|
+            self.send("__#{meth}", *args) if respond_to? "__#{meth}"
+            return_value.call(*args)
+          end
+        end
+      end
+      element
+    end
+
+    # Create new {Page} object conveniently on page actions.
+    #
+    # @param [Page] Page page class to make an instance of
+    # @param [Object] Element optional element instance. When not specified current {Page} element will be used.
+    def redirect_to(page, element=nil)
+      page.new element || self.element
+    end      
+
+    # Proxies every method call not found on {Page} to element instance.
+    # Subsequent executions of the same method will be invoked on the {Page} object directly.
+    def method_missing(name, *args)
+      if element.respond_to?(name)
+        self.class.send :define_method, name do |*args|
+          element.send(name, *args) {yield}
+        end
+        self.send(name, *args) {yield}
+      else
+        super
+      end
+    end
+
+    private
+
+    def parent_page_browser
+      page_with_browser = self.class.ancestors.find do |klass|
+        klass.respond_to?(:browser) && klass.browser
+      end
+      page_with_browser ? page_with_browser.browser : nil
+    end
+      
+  end
+end

data/lib/test/page/version.rb

@@ -0,0 +1,5 @@
+module Test
+  class Page
+    VERSION = "0.0.1"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require "simplecov"
+SimpleCov.start 

data/spec/test/page_spec.rb

@@ -0,0 +1,165 @@
+require File.expand_path("../spec_helper", File.dirname(__FILE__))
+require File.expand_path("../../lib/test/page", File.dirname(__FILE__))
+
+describe Test::Page do
+  let(:page_class) { Class.new(Test::Page) }
+
+  context ".browser" do
+    before { Test::Page.browser = nil }
+
+    it "sets the browser object for page" do
+      Test::Page.browser = "my browser"
+      Test::Page.browser.should == "my browser"
+    end
+
+    it "does not set the browser object for sub-page class" do
+      Test::Page.browser = "your browser"
+      page_class.browser.should be_nil
+    end
+
+    it "sets the browser object for sub-page instances" do
+      Test::Page.browser = "your browser"
+      page = page_class.new
+      page.browser.should == "your browser"
+    end
+
+    it "can be overridden by sub-page" do
+      Test::Page.browser = "their browser"
+      page_class.browser = "my page browser"
+      page_class.browser.should == "my page browser"
+      Test::Page.browser.should == "their browser"
+    end
+  end
+
+  context ".element" do
+    it "sets the element via block" do
+      page_class.element { "my element" }
+      page = page_class.new
+      page.element.should == "my element"
+    end
+  end
+
+  context "#initialize" do
+    it "allows to set element" do
+      page = page_class.new "my special element"
+      page.element.should == "my special element"
+    end
+  end
+
+  context "#element" do
+    it "evaluates element provided by the block only once per instance" do
+      block_called = false
+      page_class.element do
+        raise "block should have been called only once!" if block_called
+        block_called = true
+        "my element in block"
+      end
+      page = page_class.new
+      2.times { page.element.should == "my element in block" }
+      block_called.should be_true
+    end
+  end
+
+  context "#setup" do
+    it "is called only once if page has method defined" do
+      block_called = false
+      page_class.send :define_method, :setup do
+        raise "block should have been called only once!" if block_called
+        block_called = true
+        @element = "element via setup"
+      end
+      page = page_class.new
+      2.times { page.element.should == "element via setup" }
+      block_called.should be_true
+    end
+  end
+
+  context "#modify" do
+    let(:modified_page_class) do
+      page_class.send :define_method, :something do
+        modify Hash.new,
+          :action => proc { "hi" },
+          :store => proc { |a, b| a + b }
+      end      
+      page_class
+    end
+
+    it "returns the instance of the original object" do
+      page = modified_page_class.new
+      page.something.should == {}
+    end
+
+    it "allows to modify default behavior of the instance's methods" do
+      page = modified_page_class.new
+      page.something.store(1, 2).should == 3
+    end
+
+    it "executes the original instance method too" do
+      page = modified_page_class.new
+      result = page.something
+      result.store 1, 2
+      result.should == {1 => 2}
+    end
+
+    it "modifies only singleton instance methods, leaving original class intact" do
+      page = modified_page_class.new
+      result = page.something
+      result.store(1, 2).should == 3
+
+      original_hash = Hash.new
+      original_hash.store(1, 2).should == 2
+      original_hash.should == {1 => 2}
+    end
+
+    it "allows to add new methods too" do
+      page = modified_page_class.new
+      page.something.action.should == "hi"
+    end
+  end
+
+  context "#redirect_to" do
+    it "returns the new page instance" do
+      second_page = Class.new(Test::Page)
+      page_class.send(:define_method, :redirect_me) { redirect_to second_page }
+      page = page_class.new
+      page.redirect_me.should be_an_instance_of(second_page)
+    end
+
+    it "reuses the existing page element" do
+      second_page = Class.new(Test::Page)
+      page_class.send(:define_method, :redirect_me) { redirect_to second_page }
+      page = page_class.new "provided element"
+      redirected_page = page.redirect_me
+      redirected_page.element.should == "provided element"
+    end
+
+    it "is possible to specify new element" do
+      second_page = Class.new(Test::Page)
+      page_class.send(:define_method, :redirect_me) { redirect_to second_page, "new element" }
+      page = page_class.new "provided element"
+      redirected_page = page.redirect_me
+      redirected_page.element.should == "new element"
+    end
+
+  end  
+
+  context "#method_missing" do
+    it "calls all missing methods on element object" do
+      page = page_class.new "element"
+      page.should_not respond_to(:size)
+      page.size.should == "element".size
+    end
+
+    it "defines methods to the page class" do
+      page = page_class.new "element"
+      page.should_not respond_to(:size)
+      page.size
+      page.should respond_to(:size)
+    end
+
+    it "will raise a NoMethodError if no method is found on element" do
+      expect { page_class.new("element").foo }.to raise_error(NoMethodError)
+    end
+  end
+end
+

data/test-page.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/test/page/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Jarmo Pertman"]
+  gem.email         = ["jarmo.p@gmail.com"]
+  gem.description   = %q{Test::Page helps you to write easily maintainable integration tests by using Watir, Selenium or any other testing library.}
+  gem.summary       = %q{Test::Page helps you to write easily maintainable integration tests by using Watir, Selenium or any other testing library.}
+  gem.homepage      = "https://github.com/jarmo/test-page"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "test-page"
+  gem.require_paths = ["lib"]
+  gem.version       = Test::Page::VERSION
+
+  gem.add_development_dependency "rspec", "~>2.0"
+  gem.add_development_dependency "simplecov"
+  gem.add_development_dependency "yard"
+  gem.add_development_dependency "redcarpet"
+  gem.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: test-page
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jarmo Pertman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Test::Page helps you to write easily maintainable integration tests by
+  using Watir, Selenium or any other testing library.
+email:
+- jarmo.p@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- .yardopts
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/selenium/results_page.rb
+- examples/selenium/search_page.rb
+- examples/selenium/search_spec.rb
+- examples/watir/results_page.rb
+- examples/watir/search_page.rb
+- examples/watir/search_spec.rb
+- lib/test/page.rb
+- lib/test/page/version.rb
+- spec/spec_helper.rb
+- spec/test/page_spec.rb
+- test-page.gemspec
+homepage: https://github.com/jarmo/test-page
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Test::Page helps you to write easily maintainable integration tests by using
+  Watir, Selenium or any other testing library.
+test_files:
+- spec/spec_helper.rb
+- spec/test/page_spec.rb
+has_rdoc: