RubyGems - napybara - Versions diffs - 0.3.0 → 0.3.1 - Mend

napybara 0.3.0 → 0.3.1

Files changed (7) hide show

checksums.yaml +4 -4
data/README.md +179 -45
data/lib/napybara/element.rb +2 -2
data/lib/napybara/version.rb +1 -1
data/napybara.gemspec +1 -1
data/spec/integration/readme_spec.rb +172 -0
metadata +5 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1acb0ab3b95532810db2654efd6a23ff89d23a58
-  data.tar.gz: 8d24168fbf6adc727fdd89afe2ecf8d1c6c1d714
+  metadata.gz: c60bfd33a34b3c9225ede612cd2ceaecb644b235
+  data.tar.gz: ed872c87a98a39850a887a9f66e5fdcf5884e143
 SHA512:
-  metadata.gz: d3f4c003ac74d14684fcff69c18e06d571ae68d43f00df59738581af6b4711127eaf8657d7adb07e2c3ea9f46a25738b224a5949ec0165738011f43ac300d571
-  data.tar.gz: 0a46fea43e3df63a71780a4691894d4cb61efbe380e02f2185442d590cf9af67c4c4b14a0f47529b17671b5d07679986f57cc1b8d82221fd470482d3f16fbd4c
+  metadata.gz: 745db690753460d0e8b058f176463fac216f5a335b3abf4409e2229f3f6c3f8c75ea79b5b84f6d8ce204b2134cf7172f6dfc0caef95ad11207df7b1dfdbe245f
+  data.tar.gz: dcde1d036cedd78c9894b01110d6536db00e66a954cd82cd977ac8bcdd4961b535810e5ffb7b51b40c159bacffe8619412266289c486193c19468807d299248c

data/README.md CHANGED Viewed

@@ -5,12 +5,12 @@ So you're writing an integration test for the following page:
 ```html
 <html>
   <body>
-    <ul class='messages-list'>
-      <li class="message">Hello world!</li>
-      <li class="message">Kamusta mundo!</li>
+    <ul class='message-list'>
+      <li class="message" id="message-1">Hello world!</li>
+      <li class="message" id="message-2">Kamusta mundo!</li>
     </ul>
     <form class='new-message'>
-      <div class="message" />
+      <div class="message-row" />
         <label for='message'>Message</label>
         <input id='message' type='text' name='message'>
       </div>
@@ -19,87 +19,221 @@ So you're writing an integration test for the following page:
 </html>
 ```
-Wouldn't it be nice if your test helpers followed the structure of the page?
+Wouldn't it be nice if you can write test helpers so that they followed the page structure?
 ```ruby
 messages_page.visit!
-messages_page.form.message.text_field.get.set 'Hello World!'
+messages_page.form.message_row.text_field.get.set 'Hello World!'
 messages_page.form.submit!
-expect(messages_page.messages[0]).to have_content('Hello world!')
-expect(messages_page.messages[1]).to have_content('Kamusta mundo!')
+expect(messages_page.message(Message.find(1))).to have_content('Hello world!')
+expect(messages_page.message(Message.find(2))).to have_content('Kamusta mundo!')
+expect(messages_page.message_items[0]).to have_content('Hello world!')
+expect(messages_page.message_items[1]).to have_content('Kamusta mundo!')
+```
+With Napybara, now you can!
+## Napybara::Element.new and #get
+First off, let's wrap the Capybara session in a Napybara element:
+```ruby
+let(:messages_page) do
+  Napybara::Element.new(self)
+end
 ```
-With Napybara, now they can! All you need is to define the structure of the page with Napybara's DSL:
+In Rails integration tests which use Capybara, `self` usually is the Capybara session.
+You can get the capybara element wrapped by the Napybara element with
+`Napybara::Element#get`:
 ```ruby
-# spec/features/messages_spec.rb
+expect(messages_page.get).to eq(self)
+```
+## Finding by selector
-let(:new_message_page) do
+You can add finders to the Napybara page with `Napybara::Element#finder`:
+```ruby
+let(:messages_page) do
   Napybara::Element.new(self) do |page|
-    page.finder :message, '.messages-list .message'
+    page.finder :form, 'form.new-message'
+  end
+end
-    page.finder :form, 'form.new-message' do |form|
-      form.finder :message, '.message' do |row|
-        row.finder :text_field, 'input#message'
-      end
+# ...
-      form.finder :submit_button, 'input[type=submit]'
-    end
+expect(messages_page.form.get['class']).to eq('new-message')
+```
+## Finding by object
+In Rails, dom elements usually have ids which end with object ids, the objects
+usually being active records. The method generated by `Napybara::Element#finder`
+can also accept an object when searching for the object's matching element:
+```ruby
+let(:messages_page) do
+  Napybara::Element.new(self) do |page|
+    page.finder :message, '#message-'
   end
 end
+let(:some_message) do
+  Message.find(1)
+end
+# ...
+expect(messages_page.message(some_message).get['id'])
+  .to eq("messages-#{some_message.id}")
+```
+In the above example, the `message` finder looks for an element matching the
+given selector (`#message-`) with `some_message`'s id (`1`). So it ends up
+looking for "#message-1".
+## Calling the finder with or without an object argument
+As you may have observed, the finder added by `Napybara::Element#finder`
+can be called with or without an object argument. Usually, you only want to use
+just one of these two options; the selector you declare will determine what
+option you want to use. For example, `#message-` only makes sense with an object
+id at the end of the selector, so you want to call the `messages_page.message()`
+finder with an object. On the other hand, `form.new-message` does not make sense
+with an object id at the end of the selector, so you want to call the
+`messages_page.form()` finder without an object argument.
+## Checking if an element exists
+`Napybara::Element#finder` also adds `has_` and `has_no_` methods to the element.
+With the Napybara elements above, you can call:
 ```
+expect(messages_page.has_form?).to be_true
+expect(messages_page).to have_form
-In the integration test above, the `self` in `Napybara::Element.new(self)` points to the current test session. In Rails integration tests which include `Capybara::DSL`, `self` would already have access to `Capybara::DSL`'s methods.
+expect(messages_page.has_message?(some_message).to be_true
+expect(messages_page).to have_message(some_message)
- What about the custom `messages_page.visit!` and `form.submit!` methods? With Napybara, you can extend each element in the structure. So if you want to add a `visit!` method to the `messages_page` element, you can write
+non_existent_message = Message.find(3)
+expect(messages_page.has_no_message?(non_existent_message)).to be_true
+expect(messages_page).to have_no_message(non_existent_message)
+```
+Due to the magic that Capybara does when finding elements in a Ajaxified page,
+it's recommended to call `expect(element).to have_no_...` instead of
+`expect(element).to_not have...`, since the former relies on Capybara's Ajax-
+friendly `has_no_css?` method.
+## Finding all elements matching a selector
+Finally, `Napybara::Element#finder` adds a pluralized version of the finder. For example,
 ```ruby
-Napybara::Element.new(self) do |page|
-  def page.visit!
-    get.visit '/messages/index'
+let(:messages_page) do
+  Napybara::Element.new(self) do |page|
+    page.finder :message_item, '.message'
   end
+end
+# ...
+expect(messages_page.message_items[0].get.text).to eq("Hello world!")
+expect(messages_page.message_items[1].get.text).to eq("Kamusta mundo!")
+```
+Napybara uses ActiveSupport to get the plural version of the finder name.
+## Adding custom methods to a Napybara element
-  # ...
+We can add new methods to a Napybara element with plain Ruby:
+```ruby
+let(:messages_page) do
+  Napybara::Element.new(self) do |page|
+    def page.visit!
+      get.visit get.messages_path
+    end
+  end
 end
+# ...
+messages_page.visit!
 ```
-`get` here points to the Capybara element that the Napybara element is wrapping.
+## Extending a Napybara element with a module
-You can also reuse helpers by extend the Napybara element with a module. For example, with `form.submit!`:
+Adding the same methods to multiple Napybara elements? You can share the methods in a module:
 ```ruby
-module FormExtensions
-  def submit!
-    submit_button.get.click
+module PageExtensions
+  def visit!
+    get.visit get.messages_path
+    @visited = true
+  end
+  def visited?
+    !! @visited
   end
 end
-Napybara::Element.new(self) do |page|
-  page.finder :form, 'form.new-message' do |form|
-    form.extend FormExtensions
-    # ...
+let(:messages_page) do
+  Napybara::Element.new(capybara_page) do |page|
+    page.extend PageExtensions
   end
 end
+# ...
+messages_page.visit!
+expect(messages_page).to be_visited
 ```
-## Installation
+## Putting it all together
-Add this line to your application's Gemfile:
+Oh yeah, the "N" in Napybara stands for nesting. Here's how you can define the
+helpers at the start of this README:
-    gem 'Napybara'
+```ruby
+let(:messages_page) do
+  Napybara::Element.new(capybara_page) do |page|
+    def page.visit!
+      get.visit get.messages_path
+    end
-And then execute:
+    page.finder :form, 'form.new-message' do |form|
+      def form.submit!
+        submit_button.get.click
+      end
-    $ bundle
+      form.finder :message_row, '.message-row' do |row|
+        row.finder :text_field, 'input[type=text]'
+      end
-Or install it yourself as:
+      form.finder :submit_button, 'input[type=submit]'
+    end
+    page.finder :message, '.message-list #message-'
+    page.finder :message_item, '.message-list .message'
+  end
+end
+```
-    $ gem install Napybara
+## Installation
+```
+$ gem install Napybara
+```
 ## Contributing
-1. Fork it ( http://github.com/<my-github-username>/Napybara/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 new Pull Request
+I'm still looking for ways to improve Napybara's DSL. If you have an idea, a
+pull request would be awesome :)

data/lib/napybara/element.rb CHANGED Viewed

@@ -16,12 +16,12 @@ module Napybara
         self.class.new(self.get.find(selector.to_s), &block)
       end
-      self.define_singleton_method("has_#{child_element_name}?") do |record|
+      self.define_singleton_method("has_#{child_element_name}?") do |record = nil|
         selector = Selector.new(child_element_selector, method_name, record)
         self.get.has_css?(selector.to_s)
       end
-      self.define_singleton_method("has_no_#{child_element_name}?") do |record|
+      self.define_singleton_method("has_no_#{child_element_name}?") do |record = nil|
         selector = Selector.new(child_element_selector, method_name, record)
         self.get.has_no_css?(selector.to_s)
       end

data/lib/napybara/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module Napybara
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/napybara.gemspec CHANGED Viewed

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["gsmendoza@gmail.com"]
   spec.summary       = %q{napybara == nested capybara}
   spec.description   = %q{DSL for nesting capybara helpers}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/gsmendoza/napybara"
   spec.license       = "MIT"
   spec.files         = `git ls-files -z`.split("\x0")

data/spec/integration/readme_spec.rb ADDED Viewed

@@ -0,0 +1,172 @@
+require 'spec_helper'
+require 'dummy_app/dummy_app'
+describe 'Readme example:' do
+  let(:capybara_page) do
+    Capybara.string <<-HTML
+      <html>
+        <body>
+          <ul class='messages-list'>
+            <li class="message" id="message-1">Hello world!</li>
+            <li class="message" id="message-2">Kamusta mundo!</li>
+          </ul>
+          <form class='new-message'>
+            <div class="message-row" />
+              <label for='message'>Message</label>
+              <input id='message' type='text' name='message'>
+            </div>
+            <input type='submit' value='Send'/>
+          </form>
+      </html>
+    HTML
+  end
+  Steps "Wrapping a page in a Napybara element" do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I wrap that capybara page in a Napybara page" do
+      @messages_page = Napybara::Element.new(capybara_page)
+    end
+    And "I call #get on the Napybara page" do
+      @get_result = @messages_page.get
+    end
+    Then "I should get the capybara page" do
+      expect(@get_result).to eq(capybara_page)
+    end
+  end
+  Steps 'Find by selector' do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I add a finder to the Napybara page wrapping the capybara page" do
+      @messages_page = Napybara::Element.new(capybara_page) do |page|
+        page.finder :form, 'form.new-message'
+      end
+    end
+    Then "the finder should be able to find the element matching the selector" do
+      expect(@messages_page.form.get['class']).to eq('new-message')
+    end
+  end
+  Steps 'Find by object' do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I add an object finder to the Napybara page wrapping the capybara page" do
+      @messages_page = Napybara::Element.new(capybara_page) do |page|
+        page.finder :message, '#message-'
+      end
+    end
+    Then "the finder should be able to find the element matching a given object" do
+      id = 1
+      message = OpenStruct.new(id: id)
+      expect(@messages_page.message(message).get['id']).to eq("message-#{id}")
+    end
+  end
+  Steps 'Existence finders' do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I add finders to the Napybara page wrapping the capybara page" do
+      @messages_page = Napybara::Element.new(capybara_page) do |page|
+        page.finder :form, 'form.new-message'
+        page.finder :message, '#message-'
+      end
+    end
+    Then "I can check for the existence of elements" do
+      expect(@messages_page.has_form?).to be_true
+      expect(@messages_page).to have_form
+      some_message = OpenStruct.new(id: 1)
+      expect(@messages_page.has_message?(some_message)).to be_true
+      expect(@messages_page).to have_message(some_message)
+      non_existent_message = OpenStruct.new(id: 3)
+      expect(@messages_page.has_no_message?(non_existent_message)).to be_true
+      expect(@messages_page).to have_no_message(non_existent_message)
+    end
+  end
+  Steps 'Find all by selector' do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I add a plain finder to the Napybara page wrapping the capybara page" do
+      @messages_page = Napybara::Element.new(capybara_page) do |page|
+        page.finder :message_item, '.message'
+      end
+    end
+    Then "I should be able to find all the elements matching the selector with
+      a plural version of the finder name" do
+      expect(@messages_page.message_items[0].get.text).to eq("Hello world!")
+      expect(@messages_page.message_items[1].get.text).to eq("Kamusta mundo!")
+    end
+  end
+  Steps "Adding a custom method to the Napybara element" do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I add a custom method to the Napybara element wrapping the capybara
+      element" do
+      @messages_page = Napybara::Element.new(capybara_page) do |page|
+        def page.visit!
+          @visited = true
+        end
+        def page.visited?
+          !! @visited
+        end
+      end
+    end
+    Then "I can call the custom method on the Napybara element" do
+      @messages_page.visit!
+      expect(@messages_page).to be_visited
+    end
+  end
+  Steps "Extending the Napybara element with a module" do
+    Given "I have a capybara page" do
+      capybara_page
+    end
+    When "I extend the Napybara element with a module" do
+      module PageExtensions
+        def visit!
+          @visited = true
+        end
+        def visited?
+          !! @visited
+        end
+      end
+      @messages_page = Napybara::Element.new(capybara_page) do |page|
+        page.extend PageExtensions
+      end
+    end
+    Then "I can call the custom methods in the module on the Napybara element" do
+      @messages_page.visit!
+      expect(@messages_page).to be_visited
+    end
+  end
+end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: napybara
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - George Mendoza
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-04-02 00:00:00.000000000 Z
+date: 2014-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -205,9 +205,10 @@ files:
 - spec/dummy_app/public/new_content.html
 - spec/dummy_app/public/test.html
 - spec/integration/napybara_spec.rb
+- spec/integration/readme_spec.rb
 - spec/napybara/element_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://github.com/gsmendoza/napybara
 licenses:
 - MIT
 metadata: {}
@@ -238,5 +239,6 @@ test_files:
 - spec/dummy_app/public/new_content.html
 - spec/dummy_app/public/test.html
 - spec/integration/napybara_spec.rb
+- spec/integration/readme_spec.rb
 - spec/napybara/element_spec.rb
 - spec/spec_helper.rb