RubyGems - xpath-specs - Versions diffs - 0.0.1 → 0.0.2 - Mend

xpath-specs 0.0.1 → 0.0.2

Files changed (16) hide show

checksums.yaml +8 -8
checksums.yaml.gz.sig +2 -2
data.tar.gz.sig +0 -0
data/.rspec +1 -0
data/.travis.yml +6 -0
data/Guardfile +9 -0
data/README.md +78 -1
data/Rakefile +6 -0
data/lib/xpath/specs/contain_a_matcher.rb +3 -0
data/lib/xpath/specs/page_part.rb +23 -4
data/lib/xpath/specs/version.rb +1 -1
data/spec/lib/xpath/specs/contain_a_matcher_spec.rb +102 -0
data/spec/spec_helper.rb +3 -0
data/xpath-specs.gemspec +3 -1
metadata +28 -7
metadata.gz.sig +0 -0

checksums.yaml CHANGED

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NDRlMGQ4MGQxZjA4Yzk0ODE3MDBiMGFiMWQ2YmNiMzZhYjEzMmEwOQ==
+    ZWNkNzJkN2RlODc2OTYyMDc2NmJkN2ZlMDg2MTU1NjdkYzNjOTljNw==
   data.tar.gz: !binary |-
-    MTVmMmViNDliNDhkZDYwYjNlNDczN2NiZmMxZjkxZDJhNTU5NWI1Yw==
+    NzhkZTliYWUxNDBiOWZjYjQ3NTEwNjZkZDBkN2M2NGUxNDQyMWU0Yg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    M2IzY2I1MjM2ZWRmZTQ1M2JhNmJmNjBhNTUxMTEyZGI2NzA4MDhjOWM3OTg2
-    NWJlN2UxYjIzZTYxNDczYjM3MjVmM2E3MmM3ZTA2ZDhkNGUyZTYzMjk3ZDA3
-    MjZjZGJkMDc0YzFmYmNlOGYyZGMxZmYwYjU1MGNlYzRhNTJlM2Y=
+    NWUwMTIxNTVlY2U1OWMyODI0MjI4YzExYTYxNzIwZTk1NmM5MDhmOGYxNDk3
+    NWYxNjQwZjRmNjBiNGQ0YzI4MjMwNjQ2MjhiMzg2MjE3MDI3ZDFlZWI4MmMx
+    YzZmYzQ3ZGY4MmE3ZjliZmYxYTkwYTExN2EyM2RhNDJmNzNjYjQ=
   data.tar.gz: !binary |-
-    YTU3ODFjNTdhYjM0YzQ4ZjMzYTMzMmEzMWJhMGFmMDA1NzIyN2M2YWVhMTFh
-    YmJlYWUxZjEwNjg1NjQwYzViZmY1OWY3YTNiMDg4NGNkMGY0ZDBkNWFjYTQ0
-    NGVjNDQ5MzJmYjJiMzNhNDFhMzEzZDliNGEwMWE1MjA0MDkwNTg=
+    NGFiN2RmNmJlNGY0MmQxY2M0N2MwNTVhNTg3NTRkNzQ5NmQ0N2EwN2M4YzMx
+    MmZkNTVhOWQxOGFjOThjNDRlNmQyZjBmNjk1OTYyNTM1N2M2MjIwZGViMjE0
+    MzIyNDQxYjAzMmIyOGMwNzJjZDMyYzY5MzExMDk3MGY3NjQ4MzY=

checksums.yaml.gz.sig CHANGED

@@ -1,2 +1,2 @@
-��c� a�;mM�\��ց��ho��(�_�I��w�d'~QH�i=&,A���9��<'��Қ�Mݧ^G���H�X��(-������y��w_{l'>�ڀ�
-O��b�I ��쒦q�=�'ꨭ�D��ȗZJ�V����7��p8�3���Q㓨Z����|��b}�pB;��2U̟T�aF=�kx�8� Y`�r��I��$��Q��0��ᷠuYhI�SO|�q������_���E�#Xz1�w[
+-���
+���9�H��^�\�&x]�s���po����S����

data.tar.gz.sig CHANGED

Binary file

data/.rspec ADDED

	@@ -0,0 +1 @@
1	+ --color

data/.travis.yml ADDED

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.1
+  - 2.0.0
+script: bundle exec rake

data/Guardfile ADDED

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md CHANGED

@@ -18,7 +18,84 @@ Or install it yourself as:
 ## Usage
-TODO: Write usage instructions here
+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
+```ruby
+# 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
+<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 :
+```ruby
+expect(html).to contain_a(dish_panel)
+```
+* You can test that it contains at least one dish
+```ruby
+expect(html).to contain_a(dish)
+```
+* You can also test that it contains a pizza
+```ruby
+expect(html).to contain_a(dish_with_name("Pizza")
+```
+* Eventually, if you try to search for a dish that is not there :
+```ruby
+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}')]])
+```
 ## Contributing

data/Rakefile CHANGED

@@ -1 +1,7 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+desc 'Run specs'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/xpath/specs/contain_a_matcher.rb CHANGED

@@ -1,8 +1,11 @@
 # -*- encoding: utf-8 -*-
+require 'nokogiri'
 module Xpath
   module Specs
+    # A custom rspec matcher to verify some html against a PagePart instance
     class ContainA
       def initialize(page_part)
         @page_part = page_part

data/lib/xpath/specs/page_part.rb CHANGED

@@ -3,7 +3,14 @@
 module Xpath
   module Specs
+    # XPath wrapper providing a user friendly description.
+    # Should be used with the contain_a rspec matcher.
     class PagePart
+      # description: user friendly text used in assertions error messages
+      # xpath: the actual xpath to search for
+      # parent: an optional parent page part, used to provide better assertion
+      # failure diagnostic
       def initialize(description, xpath, parent = nil)
         @xpath = xpath
         @description = description
@@ -16,20 +23,32 @@ module Xpath
         !parent.nil?
       end
+      # A full description containing the xpath
       def long_description
         "#{description} (#{xpath})"
       end
+      # Creates another PagePart instance to match elements relatively to self
+      # Uses a completely new description. It's the prefered way to mach sub
+      # elements, xpath should usually start with '/'
       def with(description, xpath)
         PagePart.new(description, self.xpath+xpath, self)
       end
-      def within_a(outer_page_part)
-        outer_page_part.with(self.description, self.xpath)
-      end
+      # Creates another PagePart instance to match elements relatively to self
+      # Concatenates the descriptions. It's the prefered way to add constraints
+      # to the currently matched elements, xpath should usually start with '['
       def that(description, xpath)
-        PagePart.new("#{self.description} that #{description}", self.xpath+xpath, self)
+        PagePart.new("#{self.description} that #{description}",
+                     self.xpath+xpath,
+                     self)
       end
+      # Creates another PagePart instance like self, but relatively to another
+      # existing page part.
+      def within_a(outer_page_part)
+        outer_page_part.with(self.description, self.xpath)
+      end
     end
   end

data/lib/xpath/specs/version.rb CHANGED

@@ -1,5 +1,5 @@
 module Xpath
   module Specs
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
   end
 end

data/spec/lib/xpath/specs/contain_a_matcher_spec.rb ADDED

@@ -0,0 +1,102 @@
+# -*- encoding: utf-8 -*-
+require 'spec_helper'
+module Xpath
+  module Specs
+    describe ContainA do
+      context 'direct matching' do
+        before :each do
+          @html_with_link = '<html>
+                              <head></head>
+                              <body>
+                               <a href="#">Click Me !</a>
+                              </body>
+                             </html>'
+          @blank_html = '<html>
+                          <head></head>
+                          <body>
+                          </body>
+                         </html>'
+          @link = PagePart.new("<my link>", '//a')
+        end
+        it 'matches an existing xpath' do
+          expect(@html_with_link).to contain_a(@link)
+        end
+        it 'has better error messages for missing xpath' do
+          expect do
+            expect(@blank_html).to contain_a(@link)
+          end.to raise_error(Regexp.new("expected the page to contain <my link> \\(\\/\\/a\\)"+
+                                        "\\s+but could not find <my link> \\(\\/\\/a\\)"))
+        end
+        it 'has clear error messages for unexpected xpath' do
+          expect do
+            expect(@html_with_link).not_to contain_a(@link)
+          end.to raise_error(/expected the page not to contain <my link> \(\/\/a\)/)
+        end
+        it 'automaticaly works on body attributes' do
+          expect(double(:body => @html_with_link)).to contain_a(@link)
+        end
+      end
+      context 'nesting xpath' do
+        before :each do
+          @html_with_link = '<html>
+                              <head></head>
+                              <body>
+                               <div>
+                                <a href="#">Click Me !</a>
+                               </div>
+                              </body>
+                             </html>'
+          @html_without_link = '<html>
+                                 <head></head>
+                                 <body>
+                                  <div></div>
+                                 </body>
+                                </html>'
+          @nested_link = PagePart.new("<my div>", '//div').with('<my nested link>', '/a')
+        end
+        it 'matches a nested xpath' do
+          expect(@html_with_link).to contain_a(@nested_link)
+        end
+        it 'has even better error messages for missing nested xpath' do
+          expect do
+            expect(@html_without_link).to contain_a(@nested_link)
+          end.to raise_error(Regexp.new("expected the page to contain <my nested link> \\(\\/\\/div\\/a\\)"+
+                                        "\\s+it found <my div> \\(\\/\\/div\\) :"+
+                                        "\\s+<div><\\/div>"+
+                                        "\\s+but not <my nested link> \\(\\/\\/div\\/a\\)"))
+        end
+        it 'supports nesting xpath the other way round' do
+          link_within = PagePart.new('link', '//a').within_a(PagePart.new('div', '//div'))
+          expect(link_within.xpath).to eq('//div//a')
+        end
+        it 'supports specializing xpath' do
+          red_link = PagePart.new('link', '//a').that('is red', "[@class='red']")
+          expect(red_link.xpath).to eq("//a[@class='red']")
+          expect(red_link.description).to eq('link that is red')
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb ADDED

@@ -0,0 +1,3 @@
+# -*- encoding: utf-8 -*-
+require 'xpath/specs'

data/xpath-specs.gemspec CHANGED

@@ -20,6 +20,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "nokogiri"
-  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "guard-rspec"
 end

metadata CHANGED

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xpath-specs
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Philou
@@ -38,7 +38,7 @@ cert_chain:
   NU5zd3dIY0llUVpCL05JRDdiZXJJZjlhd3gzCnlMY2wxY21tNUFMdEovK0Jr
   a21wMGk0YW1YZVRETXZxOXI4UEJzVnNRd3hZT1lKQlArVW14ejNQWDZIakZI
   clEKWGRrWHgzb1oKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
-date: 2014-05-13 00:00:00.000000000 Z
+date: 2014-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -58,16 +58,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -82,6 +82,20 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A gem providing recursive and named wrappers around xpaths, in order
   to improve error messages when testing xpath presence in html files
 email:
@@ -91,7 +105,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
+- .travis.yml
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -99,6 +116,8 @@ files:
 - lib/xpath/specs/contain_a_matcher.rb
 - lib/xpath/specs/page_part.rb
 - lib/xpath/specs/version.rb
+- spec/lib/xpath/specs/contain_a_matcher_spec.rb
+- spec/spec_helper.rb
 - xpath-specs.gemspec
 homepage: https://github.com/philou/xpath-specs
 licenses:
@@ -124,4 +143,6 @@ rubygems_version: 2.0.3
 signing_key:
 specification_version: 4
 summary: An RSpec library to get better messages when matching XPaths
-test_files: []
+test_files:
+- spec/lib/xpath/specs/contain_a_matcher_spec.rb
+- spec/spec_helper.rb

metadata.gz.sig CHANGED

Binary file