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

napybara 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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