Xpath::Specs

An RSpec library to get better messages when matching XPaths

Installation

Add this line to your application's Gemfile:

gem 'xpath-specs'

And then execute:

$ bundle

Or install it yourself as:

$ gem install xpath-specs

Usage

As an example, suppose you have website with dishes and receipes. You want to test your views (either in RSpec or Cucumber) to make sure that they contain parts you want them to.

Declare your page parts

In order to encourage reuse, create one or many custom page part definition files

# spec/support/knows_page_parts.rb

module KnowsPageParts
  def dish_panel
    Xpath::Specs::PagePart.new("the dish panel", "//table[@id='dish-panel']")
  end

  def dish
    # match a sub element of dish_panel
    dish_panel.with("a dish", "//tr")
  end

  def dish_with_name(name)
    # match a special dish
    dish.that("is named #{name}", "[td[contains(.,'#{name}')]]")
  end
end

Use them in your specs

With these page parts definitions in place, you can now use them to test your views. Suppose this is the html for your view :

<html>
 <head></head>
 <body>
  <div>
   <table id="dish-panel">
    <tr><td>Pizza</td>...</tr>
    <tr><td>Cheese Burger</td>...</tr>
    ...
   </table>
  </div>
 </body>
</html>

You can test that your view contains the dish panel :

expect(html).to contain_a(dish_panel)

You can test that it contains at least one dish

expect(html).to contain_a(dish)

You can also test that it contains a pizza

expect(html).to contain_a(dish_with_name("Pizza")

Eventually, if you try to search for a dish that is not there :

expect(html).to contain_a(dish_with_name("Grilled Lobster")

You'll get a nice error message :

expected the page to contain a dish that is named Grilled Lobster (//table[@id='dish-panel']//tr[td[contains(.,'#{name}')]])
       it found a dish (//table[@id='dish-panel']//tr) :
          <tr><td>Pizza</td>...</tr>
       but not a dish that is named Grilled Lobster (//table[@id='dish-panel']//tr[td[contains(.,'#{name}')]])

Testing from Cucumber

Just use the 'page' in place of your view :

expect(page).to contain_a(dish_panel)

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

xpath-specs

Development