capybara-wheel 0.0.3 → 0.0.4

data/README.md

@@ -10,11 +10,28 @@ Capybara wheel is a page model framework which natively and (hopefully) easily e
   - Enforces single point of reference to selectors / elements.
   - Also helps reducing memoizations.
 
-- Subelements structure to scope finds to a specific section of the page.
+- Element hierarchy structure to scope finds to a specific section of the page.
   - Reduces ambiguity.
 
 *A special thank you to @woollyams for the initial concept*
 
+## Why Wheel?
+
+Browser driven acceptance tests are notorious for being unstable and hard to maintain. The main culprits are:
+
+1. Timing issues which result in unstable waits and "is the page loaded?" queries accross the specs.
+
+2. Memoizing the state of the page (e.g. `search_result = Capybara.find('li')` ) at a certain time. Each spec run might memoize a different state, leading to unstable tests.
+
+3. No convention around page interactions (e.g. sometimes calling a page model, sometimes a native find with a selector).
+
+Wheel solves all these by forcing the spec to always act or query the currect state of the page.
+If the page is not in a state that the spec expects, the native Capybara wait will be used until it is; removing the need to `sleep` or build mechanics to test for page loads.
+
+Specs are always written in one uniform, clean, way - always calling the same model when dealing with the same page / element. No more hunting multiple specs to change a selector.
+
+The Element model DSL is still eaily customisable just like "normal" page model classes so domain specfic applications are just as easy, resulting in descriptive, easy to read specs.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -46,7 +63,7 @@ To model a new page:
 
     class NewPage < Capybara::Wheel::Page
 
-A page needs to implament two methods:
+A page needs to implement two methods:
 
     def path
       # implament to support visiting the page directly
@@ -65,22 +82,22 @@ A page needs to implament two methods:
       # e.g. Capybara.find('h1', text: 'Login Page')
     end
 
-> Example:
->
->     class SuperVillanConsole << Capybara::Wheel::Page
->
->       def path
->         super_villan_console_path
->       end
->
->       def on_page?
->         has_title?('Destroy all humans')
->       end
->     end
+**_Example:_**
+
+     class SuperVillanConsole << Capybara::Wheel::Page
+
+       def path
+         super_villan_console_path
+       end
+
+       def on_page?
+         has_title?('Destroy all humans')
+       end
+     end
 
 ***
 
-### Element and Subelement model
+### Element model
 
 #### Element
 
@@ -96,54 +113,69 @@ The `element` method does several important things:
 1. It defines a Page method element_name which allows access and initializes...
 2. an Element model
 
-Out of the box, Element accepts all the old familar Capybara Element actions / queries (e.g. click, set, text, visible?).Once an action or query is sent to a Wheel element it then finds the native Capybara element and passes it on. This ensures that each method call is executed on the newset version of the element.
+Out of the box, Element accepts all the old familar Capybara Element actions / queries (e.g. click, set, text, visible?). Once an action or query is sent to a Wheel element it then finds the native Capybara element and passes it on. This ensures that each method call is executed on the newset version of the element.
 
-Passing a block to element gives access to the Element object for the purpose of implamenting SubElements (see below) or rolling your own methods:
+Passing a block to element gives access to the Element object for the purpose of implamenting a subelement (see below) or rolling your own customised methods:
 
 **The `capybara_element` method is the direct accessor to the native Capybara element callback.**
 
-> Example
->
->     element 'ButtonOfDoom', '#doom-button' do
->
->        def armed?
->          capybara_element.text == 'Armed'
->        end
->
->      end
->
->     element 'MissleTracker', '.missle-tracker'
->
->
->     #=> SuperVillanConsole.new.button_of_doom.armed?
->
->     #=> SuperVillanConsole.new.missle_tracker.visible?
->
-
-
-#### Subelement
-
-An element block also accepts the `subelement` method.
-
-    subelement 'SubElementName', 'selector' *optional block*
-
-A subelement behaves exactly like element with one difference, the find is scoped to the containing (or parent) element which reduces ambiguity.
-
-> Example
->
->     element 'ButtonOfDoom', '#doom-button' do
->
->        subelement 'ArmingKey', '#key' do
->
->          def turn
->            capybara_element.click
->          end
->
->        end
->     end
->
->     #=> SuperVillanConsole.new.button_of_doom.turn
+**_Example:_**
+
+     element 'ButtonOfDoom', '#doom-button' do
+
+        def armed?
+          capybara_element.text == 'Armed'
+        end
+
+      end
+
+     element 'MissleTracker', '.missle-tracker'
+
+
+     #=> SuperVillanConsole.new.button_of_doom.armed?
+
+     #=> SuperVillanConsole.new.missle_tracker.visible?
+
+
+
+#### (Sub)Element
+
+An element block also accepts the `element` method.
+
+    element 'SubElementName', 'selector' *optional block*
+
+When called inside an element block, the element behaves like an Element but is now scoped to the containing (or parent) element, which reduces ambiguity.
+
+**_Example:_**
+
+ Two buttons have an `li` element with the `.key` class. We want to be able to find one and turn it without accidently causing world peace:
+
+     element 'ButtonOfDoom', '#doom-button' do
+
+        # reference to this key is scoped inside the #doom-button element
+        element 'ArmingKey', 'li.key' do
+
+          def turn
+            capybara_element.click
+          end
+
+        end
+     end
+
+     element 'ButtonOfWorldPeace', '#peace-button' do
+
+       # reference to this key is scoped inside the #peace-button element
+       element 'ArmingKey', 'li.key' do
+
+         def turn
+           capybara_element.click
+         end
+
+       end
+     end
 
+     #=> SuperVillanConsole.new.button_of_world_peace.arming_key.turn
+     #=> SuperVillanConsole.new.button_of_doom.arming_key.turn
 ***
 ***
 ***
@@ -156,4 +188,4 @@ A subelement behaves exactly like element with one difference, the find is scope
 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 new Pull Request
+5. Create new Pull Request

data/lib/capybara/wheel.rb

@@ -1,5 +1,5 @@
 Dir.glob(File.join(File.dirname(__FILE__), 'wheel', '*.rb')).each {|file| require file}
-require "capybara"
+require 'capybara'
 require 'capybara/dsl'
 require 'rspec'
 

data/lib/capybara/wheel/element.rb

@@ -9,8 +9,11 @@ module Capybara
         include Capybara::Wheel::Includes
         extend Capybara::Wheel::Includes::ClassIncludes
 
-        def initialize(selector = nil)
+        attr_reader :scope
+
+        def initialize(selector = nil, scope = nil)
           @selector = selector if selector
+          @scope    = scope
         end
 
         def_delegators  :capybara_element,
@@ -46,17 +49,30 @@ module Capybara
           false
         end
 
-        def self.subelement(name, selector, block = nil)
+        def self.element(name, selector, block = nil)
           subelement_factory = lambda do |parent_element|
-            Capybara::Wheel::ElementFactory.create_subelement(selector, parent_element, block)
+            Capybara::Wheel::ElementFactory.create_element(selector, parent_element, block)
           end
 
           define_method(underscore(name).to_sym) { subelement_factory.call(self) }
           self
         end
 
+        def element(name, selector, &block)
+          self.class.element(name, selector, block)
+        end
+
+        #TODO: deprecated in 0.0.5
         def subelement(name, selector, &block)
-          self.class.subelement(name, selector, block)
+          puts "subelement will be deprecated in future versions."
+          puts "Calling element inside an element block will scope it to the parent element"
+          element(name, selector, block)
+        end
+
+        def self.subelement(name, selector, &block)
+          puts "subelement will be deprecated in future versions."
+          puts "Calling element inside an element block will scope it to the parent element"
+          element(name, selector, &block)
         end
 
         def selector
@@ -65,9 +81,14 @@ module Capybara
 
         protected
 
+
         # Finds a capybara element representing this thing
         def capybara_element
-          capybara.find(selector)
+          scope_capybara.find(selector)
+        end
+
+        def scope_capybara
+          scope.nil? ? capybara : scope.send(:capybara_element)
         end
 
     end

data/lib/capybara/wheel/element_factory.rb

@@ -10,7 +10,7 @@ module Capybara
         _selector = selector
 
         subclass.class_exec do
-          define_method(:selector) { @selector = _selector}
+          define_method(:selector) { @selector = _selector }
         end
 
         subclass.class_eval(&block) if block
@@ -19,8 +19,8 @@ module Capybara
       end
 
       #TODO: Pass object not an instance
-      def self.create_subelement(selector, parent_element, block = nil)
-        subelement = Capybara::Wheel::SubElement.new(selector, parent_element)
+      def self.create_element(selector, parent_element, block = nil)
+        subelement = Capybara::Wheel::Element.new(selector, parent_element)
         subelement.instance_eval(&block) if block
 
         subelement

data/lib/capybara/wheel/page.rb

@@ -37,7 +37,6 @@ module Capybara
         raise NotImplementedError, "implement me, e.g. using #has_title?"
       end
 
-      # callback commonly used for on_page?
       def has_title?(expected_title)
         capybara.has_css?("head title", :text => expected_title)
       end

data/lib/capybara/wheel/version.rb

@@ -1,5 +1,5 @@
 module Capybara
   module Wheel
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
   end
 end

data/spec/element_factory_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+feature 'ElementFactory' do
+  let(:subject)               { Capybara::Wheel::ElementFactory }
+  let(:selector)              { '#rad-selector'}
+  let(:created_element_klass) { subject.create_element_klass(selector) }
+
+
+  it 'creates an element' do
+    created_element_klass.superclass.should == Capybara::Wheel::Element
+  end
+
+  it 'allows access to the selector' do
+    created_element_klass.new.selector.should == selector
+  end
+
+  it 'generated instance evalutes block' do
+    test_block = Proc.new do
+      def evaled_method
+      end
+    end
+
+    subject.create_element_klass(selector, test_block).new.should respond_to(:evaled_method)
+  end
+end

data/spec/element_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+feature 'Element' do
+  let(:element_selector)  { '#some-selector' }
+  let(:element)           { Capybara::Wheel::Element }
+  let(:element_instance)  {  element.new(element_selector) }
+
+  it 'has access to capybara' do
+    element_instance.methods.include?(:capybara).should be_true
+  end
+
+  it 'has delegators for Capybara actions' do
+    pending 'grab all the actions from Capybara and ensure delegators are implemented'
+  end
+
+  context 'self.element' do
+    let(:element_selector)    { '#rad-parent-selector' }
+
+    let(:subelement_name)     { 'RadSubElement' }
+    let(:subelement_selector) { '#rad-sub-selector' }
+
+    before do
+      element_instance.instance_eval do
+        element('RadSubElement', '#rad-sub-selector')
+      end
+    end
+
+    it 'created a method for calling the element' do
+      element_instance.should respond_to(:rad_sub_element)
+    end
+
+    it 'create a (sub)element with parent element context' do
+      element_instance.send(:rad_sub_element).scope.should == element_instance
+    end
+
+    it 'the find would be scoped to parent' do
+      subelement             = element_instance.send(:rad_sub_element)
+      mock_capybara_session  = mock(Capybara::Session)
+      mock_capybara_element  = mock('Capybara::Element')
+      Capybara.stub!(:current_session).and_return(mock_capybara_session)
+      mock_capybara_session.stub(:find).with(element_selector).and_return(mock_capybara_element)
+      mock_capybara_element.stub(:find).with(subelement_selector).and_return(mock_capybara_element)
+
+      element_instance.should_receive(:capybara_element).once.and_return(mock_capybara_element)
+
+      subelement.send(:capybara_element)
+    end
+  end
+
+end

data/spec/feature_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+RSpec.configure do |config|
+  config.before(:each, :some_hook) do
+    @hook_passed_on = true
+  end
+end
+
+feature 'runs as a wheel feature', :some_hook do
+
+  it 'should pass' do
+  end
+
+  it 'should be set as a wheel feature' do
+    example.metadata[:type].should == :wheel_feature
+  end
+
+  it 'should pass the right hook' do
+    @hook_passed_on.should be_true
+  end
+end

data/spec/page_spec.rb

@@ -0,0 +1,16 @@
+require 'spec_helper'
+
+feature 'Page' do
+  let(:page) { Capybara::Wheel::Page }
+
+  it 'has access to capybara' do
+    page.new.methods.include?(:capybara).should be_true
+  end
+
+  context 'can create an element instance' do
+    it 'and create a method for it' do
+      page.element('RadElement', '#rad-selector').new.should respond_to(:rad_element)
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -1,3 +1,4 @@
+require 'capybara/wheel'
 require 'rspec'
 require 'pry'
 

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: capybara-wheel
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
+  prerelease: 
 platform: ruby
 authors:
-- '@gabrielrotbart'
+- ! '@gabrielrotbart'
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-08 00:00:00.000000000 Z
+date: 2013-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -20,6 +22,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -27,34 +30,39 @@ dependencies:
 - !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'
 - !ruby/object:Gem::Dependency
   name: rspec
   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: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -62,6 +70,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -69,6 +78,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -76,6 +86,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -83,20 +94,23 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
   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: capybara
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -104,6 +118,7 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -111,15 +126,17 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Keeping the rodent on track
@@ -140,35 +157,41 @@ files:
 - lib/capybara/wheel/element_factory.rb
 - lib/capybara/wheel/includes.rb
 - lib/capybara/wheel/page.rb
-- lib/capybara/wheel/subelement.rb
 - lib/capybara/wheel/version.rb
+- spec/element_factory_spec.rb
+- spec/element_spec.rb
+- spec/feature_spec.rb
+- spec/page_spec.rb
 - spec/spec_helper.rb
-- spec/wheel_spec.rb
 homepage: ''
 licenses:
 - MIT
-metadata: {}
 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: 2.0.3
+rubygems_version: 1.8.25
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Creating (yet another) page model gem based around making capybara tests
   more stable with no need for waits
 test_files:
+- spec/element_factory_spec.rb
+- spec/element_spec.rb
+- spec/feature_spec.rb
+- spec/page_spec.rb
 - spec/spec_helper.rb
-- spec/wheel_spec.rb

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: fd80ae9d800e4bff8293c3c6a913e0817915ee8e
-  data.tar.gz: 83f9bafd3a783f3c5503704e7b0f16988c4073db
-SHA512:
-  metadata.gz: 65aed3f76018833406c291d04acea02753f5541d672c0de57311eb1c6f1a406aa4caba3957dc2e463a70c93279f52df612fb8296e741ad77f3ff531673beba6e
-  data.tar.gz: a793890e6f6ae8f8ffbcb361c7bd68f5acf502cd1ba9b3c098601bc18558fa98001a04db98bb96f41d9f6b493c8f4e236cc0d2093e3fb7659b6a53a0550e6f4a

data/lib/capybara/wheel/subelement.rb

@@ -1,24 +0,0 @@
-require 'capybara/wheel/includes'
-
-module Capybara
-  module Wheel
-    class SubElement < Capybara::Wheel::Element
-      attr_reader :parent
-
-      def initialize(selector, parent)
-        @parent   = parent
-        @selector =  selector
-      end
-
-      private
-      def capybara_element
-        parent_element.find(selector)
-      end
-
-      def parent_element
-        parent.send(:capybara_element)
-      end
-
-    end
-  end
-end

data/spec/wheel_spec.rb

@@ -1,108 +0,0 @@
-require 'spec_helper'
-require 'capybara/wheel'
-
-RSpec.configure do |config|
-  config.before(:each, :some_hook) do
-    @hook_passed_on = true
-  end
-end
-
-feature 'runs as a wheel feature', :some_hook do
-
-  it 'should pass' do
-  end
-
-  it 'should be set as a wheel feature' do
-    example.metadata[:type].should == :wheel_feature
-  end
-
-  it 'should pass the right hook' do
-    @hook_passed_on.should be_true
-  end
-end
-
-feature 'Page' do
-  let(:page) { Capybara::Wheel::Page }
-
-  it 'has access to capybara' do
-    page.new.methods.include?(:capybara).should be_true
-  end
-
-  context 'can create an element instance' do
-    it 'and create a method for it' do
-      page.element('RadElement', '#rad-selector').new.should respond_to(:rad_element)
-    end
-  end
-
-end
-
-feature 'Element' do
-  let(:element) { Capybara::Wheel::Element }
-
-  it 'has access to capybara' do
-    element.new('#some-selector').methods.include?(:capybara).should be_true
-  end
-
-  context 'can create a subelement instance' do
-    let(:subelement_name)     { 'RadSubElement' }
-    let(:subelement_selector) { '#rad-sub-selector' }
-    let(:element_instance)    { element.new.subelement(subelement_name, subelement_selector).new('#rad-selector') }
-
-    it 'and create a method for it' do
-      element_instance.should respond_to(:rad_sub_element)
-    end
-
-    it 'create a subelement with parent element context' do
-      element_instance.send(:rad_sub_element).parent.should == element_instance
-    end
-  end
-
-end
-
-feature 'SubElement' do
-  let(:parent_selector) { '#parent-selector'}
-  let(:sub_selector)    { '#sub-selector'}
-  let!(:parent_element) { Capybara::Wheel::Element.new(parent_selector) }
-  let!(:subelement)     { class ASubElement < Capybara::Wheel::SubElement
-                              def my_element
-                                capybara_element
-                              end
-                          end }
-
-  before :each do
-    parent_element.instance_eval do
-      def a_sub_element
-        ASubElement.new('#sub-selector', self)
-      end
-    end
-  end
-
-  it 'calls parent element capybara_element' do
-    pending
-  end
-
-end
-
-feature 'ElementFactory' do
-  let(:subject)               { Capybara::Wheel::ElementFactory }
-  let(:selector)              { '#rad-selector'}
-  let(:created_element_klass) { subject.create_element_klass(selector) }
-
-
-  it 'creates an element' do
-    created_element_klass.superclass.should == Capybara::Wheel::Element
-  end
-
-  it 'allows access to the selector' do
-    created_element_klass.new.selector.should == selector
-  end
-
-  it 'generated instance evalutes block' do
-    test_block = Proc.new do
-      def evaled_method
-      end
-    end
-
-    subject.create_element_klass(selector, test_block).new.should respond_to(:evaled_method)
-  end
-end