pouch 0.1.0 → 0.2.0

data/README.md

@@ -1,6 +1,6 @@
 # Pouch
 
-TODO: Write a gem description
+Pouch is a flexible page object DSL for responsive UI testing and written with expressive scripting in mind. It currently works with watir-webdriver.
 
 ## Installation
 
@@ -20,12 +20,71 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Include Pouch in your page object classes, which will give them access to the element definition DSL.
+
+```ruby
+class Page
+  include Pouch
+  link(:home, id: 'go-home')
+  text_field(:search, id: 'search-term')
+  button(:submit, id: 'search-submit')
+end
+```
+
+Scripting is meant to be expressive, so calling the name of your element method returns the HTML object and forces you to write out your actions.
+
+```ruby
+page = Page.new browser_instance
+page.home.click
+page.search.value = 'search term'
+page.submit.click
+```
+
+Element method definitions are flexible. You can engineer more useful definitions with block arguments.
+
+```ruby
+class Page
+  include Pouch
+  list_item(:phone_number, id: 'phone-num')
+  list_item(:area_code, id: 'phone-num'){ |li| span.text[0..2] }
+end
+```
+
+This lets your scripting be more expressive too. For example, compare these two RSpec expectations using the page object definition above:
+
+```ruby
+expect(page.phone_number[0..2]).to eq '555'
+expect(page.area_code).to eq '555'
+```
+
+Pouch page objects can be created with contexts, allowing a single method call to execute two different element definitions based on that context. This is useful for responsive UI testing, when DOM elements change but the functionality is basically the same.
+
+```ruby
+class Page
+include Pouch
+link(:sign_in, id: 'desktop-login')
+link(:mobile_sign_in, id: 'mobile-login')
+```
+
+```ruby
+# script.rb
+page = Page.new browser_instance, context: ENV['CONTEXT']
+page.sign_in.attribute_value 'id' == 'desktop-login'
+```
+
+```
+$ ruby script.rb
+#=> true
+$ CONTEXT=mobile ruby script.rb
+#=> false
+```
 
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/pouch/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+3. Write tests
+4. Code until all tests pass
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a new Pull Request

data/lib/pouch/elements.rb

@@ -0,0 +1,119 @@
+module Pouch
+  module Elements
+
+    def element tag, name, identifier, *args, &block
+      define_method name do
+        return browser.element tag, identifier unless block_given?
+        block.call browser.send(:element, tag, identifier), *args
+      end
+    end
+
+    def button name, identifier, *args, &block
+      element :button, name, identifier, args, &block
+    end
+
+    def checkbox name, identifier, *args, &block
+      identifier.merge! type: 'checkbox'
+      element :input, name, identifier, args, &block
+    end
+
+    def div name, identifier, *args, &block
+      element :div, name, identifier, args, &block
+    end
+
+    def file_field name, identifier, *args, &block
+      identifier.merge! type: 'file'
+      element :input, name, identifier, args, &block
+    end
+
+    def form name, identifier, *args, &block
+      element :form, name, identifier, args, &block
+    end
+
+    def h1 name, identifier, *args, &block
+      element :h1, name, identifier, args, &block
+    end
+
+    def h2 name, identifier, *args, &block
+      element :h2, name, identifier, args, &block
+    end
+
+    def h3 name, identifier, *args, &block
+      element :h3, name, identifier, args, &block
+    end
+
+    def h4 name, identifier, *args, &block
+      element :h4, name, identifier, args, &block
+    end
+
+    def h5 name, identifier, *args, &block
+      element :h5, name, identifier, args, &block
+    end
+
+    def h6 name, identifier, *args, &block
+      element :h6, name, identifier, args, &block
+    end
+
+    def image name, identifier, *args, &block
+      element :img, name, identifier, args, &block
+    end
+
+    def link name, identifier, *args, &block
+      element :a, name, identifier, args, &block
+    end
+
+    def list_item name, identifier, *args, &block
+      element :li, name, identifier, args, &block
+    end
+
+    def ordered_list name, identifier, *args, &block
+      element :ol, name, identifier, args, &block
+    end
+
+    def paragraph name, identifier, *args, &block
+      element :p, name, identifier, args, &block
+    end
+
+    def radio_button name, identifier, *args, &block
+      identifier.merge! type: 'radio'
+      element :input, name, identifier, args, &block
+    end
+
+    def select_list name, identifier, *args, &block
+      element :select, name, identifier, args, &block
+    end
+
+    def span name, identifier, *args, &block
+      element :span, name, identifier, args, &block
+    end
+
+    def table name, identifier, *args, &block
+      element :table, name, identifier, args, &block
+    end
+
+    def table_cell name, identifier, *args, &block
+      element :td, name, identifier, args, &block
+    end
+
+    def table_header name, identifier, *args, &block
+      element :th, name, identifier, args, &block
+    end
+
+    def table_row name, identifier, *args, &block
+      element :tr, name, identifier, args, &block
+    end
+
+    def text_area name, identifier, *args, &block
+      element :textarea, name, identifier, args, &block
+    end
+
+    def text_field name, identifier, *args, &block
+      element :input, name, identifier, args, &block
+    end
+
+    def unordered_list name, identifier, *args, &block
+      element :ul, name, identifier, args, &block
+    end
+
+  end
+end

data/lib/pouch/version.rb

@@ -1,3 +1,3 @@
 module Pouch
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/pouch.rb

@@ -1,6 +1,8 @@
 require "pouch/version"
+require "pouch/elements"
 
 module Pouch
+  include Elements
 
   class ContextualReplacementError < StandardError; end
   
@@ -34,13 +36,6 @@ module Pouch
     end
   end
 
-  def element tag, name, identifier, *args, &block
-    define_method name do
-      return browser.element_for tag, identifier unless block_given?
-      block.call browser.send('element_for', tag, identifier), *args
-    end
-  end
-
   private
 
   def contextualize_methods

data/pouch.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Johnson Denen"]
   spec.email         = ["jdenen@manta.com"]
   spec.summary       = %q{A flexible page object DSL for responsive UI testing}
-  spec.description   = %q{A flexible page object DSL for responsive UI testing via automated browsers and devices}
+  spec.description   = %q{A flexible page object DSL for responsive UI testing}
   spec.homepage      = "https://github.com/jdenen/pouch"
   spec.license       = "MIT"
 

data/spec/elements_spec.rb

@@ -0,0 +1,244 @@
+require 'spec_helper'
+require './lib/pouch/elements'
+
+describe Pouch::Elements do
+
+  class Page
+    include Pouch
+    element(:a, :generic, id: 'generic')
+    element(:a, :blocked, id: 'blocked'){ |link| link.href }
+    element(:a, :different_generic, id: 'generic-diff')
+    element(:a, :different_blocked, id: 'blocked-diff'){ |link| link.href }
+    element(:a, :what_replacement, id: 'no-match')
+  end
+
+  let(:browser){ double 'webdriver' }
+  let(:element){ double 'html_link' }
+  let(:page){ Page.new browser }
+  let(:diff){ Page.new browser, context: 'different' }
+  let(:what){ Page.new browser, context: 'what' }
+
+  describe "#element" do
+    it "returns the link element by default" do
+      expect(browser).to receive(:element).with(:a, id:'generic').and_return(element)
+      expect(page.generic).to eq element
+    end
+
+    it "returns an element that can be clicked" do
+      expect(browser).to receive(:element).with(:a, id:'generic').and_return(element)
+      expect(element).to receive(:click)
+      page.generic.click
+    end
+
+    it "returns the result of the definition block" do
+      expect(browser).to receive(:element).with(:a, id:'blocked').and_return(element)
+      expect(element).to receive(:href).and_return("www.test.com")
+      expect(page.blocked).to eq "www.test.com"
+    end
+
+    context "with context" do
+      it "uses the replacement method" do
+        expect(browser).to receive(:element).with(:a, id:'generic-diff').and_return(element)
+        expect(diff.generic).to eq element
+      end
+
+      it "uses the replacement method with definition block" do
+        expect(browser).to receive(:element).with(:a, id:'blocked-diff').and_return(element)
+        expect(element).to receive(:href).and_return("www.diff.com")
+        expect(diff.blocked).to eq "www.diff.com"
+      end
+
+      it "uses the standard method when context matches no replacement" do
+        expect(browser).to receive(:element).with(:a, id:'generic').and_return(element)
+        expect(Page.new(browser, context: 'test').generic).to eq element
+      end
+
+      it "throws an error with replacement but no standard method" do
+        expect{ what.replacement }.to raise_error Pouch::ContextualReplacementError, /Page defined no standard method for replacement/
+      end
+    end
+  end
+
+  describe "#button" do
+    it "calls :element with :button tag" do
+      expect(page).to receive(:element).with(:button, :button_name, {id: 'id'}, [])
+      page.send(:button, :button_name, id: 'id')
+    end
+  end
+
+  describe "#checkbox" do
+    it "calls :element with :checkbox tag" do
+      expect(page).to receive(:element).with(:input, :checkbox_name, {id: 'id', type: 'checkbox'}, [])
+      page.send(:checkbox, :checkbox_name, id: 'id')
+    end
+  end
+
+  describe "#div" do
+    it "calls :element with :div tag" do
+      expect(page).to receive(:element).with(:div, :div_name, {id: 'id'}, [])
+      page.send(:div, :div_name, id: 'id')
+    end
+  end
+
+  describe "#file_field" do
+    it "calls :element with :file_field tag" do
+      expect(page).to receive(:element).with(:input, :ff_name, {id: 'id', type: 'file'}, [])
+      page.send(:file_field, :ff_name, id: 'id')
+    end
+  end
+
+  describe "#form" do
+    it "calls :element with :form tag" do
+      expect(page).to receive(:element).with(:form, :form_name, {id: 'id'}, [])
+      page.send(:form, :form_name, id: 'id')
+    end
+  end
+
+  describe "#h1" do
+    it "calls :element with :h1 tag" do
+      expect(page).to receive(:element).with(:h1, :h1_name, {id: 'id'}, [])
+      page.send(:h1, :h1_name, id: 'id')
+    end
+  end
+
+  describe "#h2" do
+    it "calls :element with :h2 tag" do
+      expect(page).to receive(:element).with(:h2, :h2_name, {id: 'id'}, [])
+      page.send(:h2, :h2_name, id: 'id')
+    end
+  end
+
+  describe "#h3" do
+    it "calls :element with :h3 tag" do
+      expect(page).to receive(:element).with(:h3, :h3_name, {id: 'id'}, [])
+      page.send(:h3, :h3_name, id: 'id')
+    end
+  end
+
+  describe "#h4" do
+    it "calls :element with :h4 tag" do
+      expect(page).to receive(:element).with(:h4, :h4_name, {id: 'id'}, [])
+      page.send(:h4, :h4_name, id: 'id')
+    end
+  end
+
+  describe "#h5" do
+    it "calls :element with :h5 tag" do
+      expect(page).to receive(:element).with(:h5, :h5_name, {id: 'id'}, [])
+      page.send(:h5, :h5_name, id: 'id')
+    end
+  end
+
+  describe "#h6" do
+    it "calls :element with :h6 tag" do
+      expect(page).to receive(:element).with(:h6, :h6_name, {id: 'id'}, [])
+      page.send(:h6, :h6_name, id: 'id')
+    end
+  end
+
+  describe "#image" do
+    it "calls :element with :img tag" do
+      expect(page).to receive(:element).with(:img, :image_name, {id: 'id'}, [])
+      page.send(:image, :image_name, id: 'id')
+    end
+  end
+
+  describe "#link" do
+    it "calls :element with :a tag" do
+      expect(page).to receive(:element).with(:a, :link_name, {id: 'id'}, [])
+      page.send(:link, :link_name, id: 'id')
+    end
+  end
+
+  describe "#list_item" do
+    it "calls :element with :li tag" do
+      expect(page).to receive(:element).with(:li, :li_name, {id: 'id'}, [])
+      page.send(:list_item, :li_name, id: 'id')
+    end
+  end
+
+  describe "#ordered_list" do
+    it "calls :element with :ol tag" do
+      expect(page).to receive(:element).with(:ol, :ol_name, {id: 'id'}, [])
+      page.send(:ordered_list, :ol_name, id: 'id')
+    end
+  end
+
+  describe "#paragraph" do
+    it "calls :element with :p tag" do
+      expect(page).to receive(:element).with(:p, :paragraph_name, {id: 'id'}, [])
+      page.send(:paragraph, :paragraph_name, id: 'id')
+    end
+  end
+
+  describe "#radio_button" do
+    it "calls :element with :radio tag" do
+      expect(page).to receive(:element).with(:input, :radio_name, {id: 'id', type: 'radio'}, [])
+      page.send(:radio_button, :radio_name, id: 'id')
+    end
+  end
+
+  describe "#select_list" do
+    it "calls :element with :select tag" do
+      expect(page).to receive(:element).with(:select, :select_name, {id: 'id'}, [])
+      page.send(:select_list, :select_name, id: 'id')
+    end
+  end
+
+  describe "#span" do
+    it "calls :element with :span tag" do
+      expect(page).to receive(:element).with(:span, :span_name, {id: 'id'}, [])
+      page.send(:span, :span_name, id: 'id')
+    end
+  end
+
+  describe "#table" do
+    it "calls :element with :table tag" do
+      expect(page).to receive(:element).with(:table, :table_name, {id: 'id'}, [])
+      page.send(:table, :table_name, id: 'id')
+    end
+  end
+  
+  describe "#table_cell" do
+    it "calls :element with :td tag" do
+      expect(page).to receive(:element).with(:td, :cell_name, {id: 'id'}, [])
+      page.send(:table_cell, :cell_name, id: 'id')
+    end
+  end
+
+  describe "#table_header" do
+    it "calls :element with :th tag" do
+      expect(page).to receive(:element).with(:th, :header_name, {id: 'id'}, [])
+      page.send(:table_header, :header_name, id: 'id')
+    end
+  end
+
+  describe "#table_row" do
+    it "calls :element with :tr tag" do
+      expect(page).to receive(:element).with(:tr, :row_name, {id: 'id'}, [])
+      page.send(:table_row, :row_name, id: 'id')
+    end
+  end
+
+  describe "#text_area" do
+    it "calls :element with :input tag" do
+      expect(page).to receive(:element).with(:textarea, :text_area_name, {id: 'id'}, [])
+      page.send(:text_area, :text_area_name, id: 'id')
+    end
+  end
+
+  describe "#text_field" do
+    it "calls :element with :input tag" do
+      expect(page).to receive(:element).with(:input, :text_field_name, {id: 'id'}, [])
+      page.send(:text_field, :text_field_name, id: 'id')
+    end
+  end
+
+  describe "#unordered_list" do
+    it "calls :element with :ul tag" do
+      expect(page).to receive(:element).with(:ul, :ul_name, {id: 'id'}, [])
+      page.send(:unordered_list, :ul_name, id: 'id')
+    end
+  end
+  
+end

data/spec/pouch_spec.rb

@@ -95,74 +95,18 @@ describe Pouch do
     end
   end
 
-  class Page3
-    include Pouch
-    element(:a, :generic, id: 'generic')
-    element(:a, :blocked, id: 'blocked'){ |link| link.href }
-    element(:a, :different_generic, id: 'generic-diff')
-    element(:a, :different_blocked, id: 'blocked-diff'){ |link| link.href }
-    element(:a, :what_replacement, id: 'no-match')
-  end
-
   describe "#browser" do
     it "returns the browser instance" do
-      obj = Page3.new 'webdriver'
+      obj = Page.new 'webdriver'
       expect(obj.browser).to eq 'webdriver'
     end
   end
 
   describe "#context" do
     it "returns the page object context" do
-      obj = Page3.new 'webdriver', context: ['one', :two, ['three']]
+      obj = Page.new 'webdriver', context: ['one', :two, ['three']]
       expect(obj.context).to eq ['one', 'two', 'three']
     end
   end
-
-  describe "#element" do
-    let(:browser){ double 'webdriver' }
-    let(:element){ double 'html_link' }
-    let(:page){ Page3.new browser }
-    let(:diff){ Page3.new browser, context: 'different' }
-    let(:what){ Page3.new browser, context: 'what' }
-
-    it "returns the link element by default" do
-      expect(browser).to receive(:element_for).with(:a, id:'generic').and_return(element)
-      expect(page.generic).to eq element
-    end
-
-    it "returns an element that can be clicked" do
-      expect(browser).to receive(:element_for).with(:a, id:'generic').and_return(element)
-      expect(element).to receive(:click)
-      page.generic.click
-    end
-
-    it "returns the result of the definition block" do
-      expect(browser).to receive(:element_for).with(:a, id:'blocked').and_return(element)
-      expect(element).to receive(:href).and_return("www.test.com")
-      expect(page.blocked).to eq "www.test.com"
-    end
-
-    context "with context" do
-      it "uses the replacement method" do
-        expect(browser).to receive(:element_for).with(:a, id:'generic-diff').and_return(element)
-        expect(diff.generic).to eq element
-      end
-
-      it "uses the replacement method with definition block" do
-        expect(browser).to receive(:element_for).with(:a, id:'blocked-diff').and_return(element)
-        expect(element).to receive(:href).and_return("www.diff.com")
-        expect(diff.blocked).to eq "www.diff.com"
-      end
-
-      it "uses the standard method when context matches no replacement" do
-        expect(browser).to receive(:element_for).with(:a, id:'generic').and_return(element)
-        expect(Page3.new(browser, context: 'test').generic).to eq element
-      end
-
-      it "throws an error with replacement but no standard method" do
-        expect{ what.replacement }.to raise_error Pouch::ContextualReplacementError, /Page3 defined no standard method for replacement/
-      end
-    end
-  end
   
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pouch
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-26 00:00:00.000000000 Z
+date: 2014-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: watir-webdriver
@@ -75,8 +75,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 3.0.0
-description: A flexible page object DSL for responsive UI testing via automated browsers
-  and devices
+description: A flexible page object DSL for responsive UI testing
 email:
 - jdenen@manta.com
 executables: []
@@ -89,8 +88,10 @@ files:
 - README.md
 - Rakefile
 - lib/pouch.rb
+- lib/pouch/elements.rb
 - lib/pouch/version.rb
 - pouch.gemspec
+- spec/elements_spec.rb
 - spec/pouch_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/jdenen/pouch
@@ -119,6 +120,7 @@ signing_key:
 specification_version: 3
 summary: A flexible page object DSL for responsive UI testing
 test_files:
+- spec/elements_spec.rb
 - spec/pouch_spec.rb
 - spec/spec_helper.rb
 has_rdoc: