RubyGems - page_match - Versions diffs - 0.0.1 - Mend

page_match 0.0.1

Files changed (12) hide show

data/.gitignore ADDED

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec ADDED

	@@ -0,0 +1,2 @@
1	+ --colour
2	+ --format doc

data/Gemfile ADDED

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+# Specify your gem's dependencies in page_match.gemspec
+gemspec

data/README.md ADDED

@@ -0,0 +1,171 @@
+# page_match
+RSpec 2 matcher class for building custom Capybara matchers for use in acceptance-level tests.
+## Install
+page_match is distributed as a Ruby gem:
+    sudo gem install page_match
+## Using page_match
+With the rise in popularity of RSpec + Capybara as an acceptance (aka. request-level) test replacement for Cucumber, using custom matchers can go a long way to clean up your examples, as well as improve your test readability.
+Consider the following HTML, which is rendered as the home page of a standard Rack-based web app:
+``` html
+<html>
+  <head><title>Home Page</title></head>
+  <body>
+    <div id="#logout-link">
+      <a href="/logout">Logout Joe User</a>
+    </div>
+    <h1 id="#main-header">Welcome Joe User</h1>
+  </body>
+</html>
+```
+One fairly common acceptance test would be to verify the text rendered for the logout link and the main header to make sure they include the correct user's name. In vanilla RSpec that might look like this:
+```ruby
+describe "Visiting the home page", :type => :request do
+  before(:each) do
+    @user = User.login(:name => "Joe User")
+  end
+  context "The home page" do
+    before(:each) do
+      visit(root_path)
+    end
+    it "should have the correct logout link" do
+      within("#logout-link") do
+        page.should have_content("Logout #{@user.name}")
+      end
+    end
+    it "should have the correct main header" do
+      within("#main-header") do
+        page.should have_content("Welcome #{@user.name}")
+      end
+    end
+  end
+end
+```
+Running these examples with the _--format documentation_ option turned on, gives us:
+```
+Visiting the home page
+  The home page
+    should have the correct logout link
+    should have the correct main header
+```
+On the surface, this example code and the documentation output is just fine. However the code is both hard to refactor and extremely verbose, with the HTML structure traversal code directly in the examples. In addition, the output lines that describe the examples are very generic.
+Using **page_match** we can create helper methods that wrap the matcher logic for our examples, giving us methods that we can reuse and letting us construct much better example descriptions:
+```ruby
+module MatchHelpers
+  def have_logout_link_for(name)
+    PageMatch.match do |pm|
+      pm.have %(a logout link for "#{name}")
+      pm.page { within ("#logout-link") { has_content?("Logout #{name}") } }
+    end
+  end
+  def have_main_header_for(name)
+    PageMatch.match do |pm|
+      pm.have %(a main header for "#{name}")
+      pm.page { within ("#main-header") { has_content?("Welcome #{name}") } }
+    end
+  end
+end
+```
+With these helper methods in place, we can now rewrite the acceptance test:
+``` ruby
+describe "Visiting the home page", :type => :request do
+  before(:each) do
+    @user = User.login(:name => "Joe User")
+  end
+  subject { page }
+  context "The home page" do
+    before(:each) do
+      visit(root_path)
+    end
+    it { should have_logout_link_for(@user.name) }
+    it { should have_main_header_for(@user.name) }
+  end
+end
+```
+When we run this example file, with the _--format documentation_ option, we get:
+```
+Visiting the home page
+  The home page
+    should have a logout link for "Joe User"
+    should have a main header for "Joe User"
+```
+The resulting test file is now easier to read, contains examples that make use of custom, domain specific matchers, that when output provide us with context-specific descriptions for those examples.
+## Included Helper Methods
+When you install page_match you will also get a set of included helper methods, for the most common types of rendered page inspections. These include:
+### have_link
+``` ruby
+  it { should have_link(<Link Label>) }
+```
+### have_button
+``` ruby
+  it { should have_button(<Button Label>) }
+```
+### have_flash_notice
+``` ruby
+  it { should have_flash_notice(<Flash Text>) }
+```
+### have_form_error
+``` ruby
+  it { should have_form_error(<Error Text>) }
+```
+### have_text_field
+``` ruby
+  it { should have_text_field(:form_name, :field_name) }
+```
+### have_text_area
+``` ruby
+  it { should have_text_area(:form_name, :field_name) }
+```
+### have_check_box
+``` ruby
+  it { should have_check_box(:form_name, :field_name) }
+```
+### have_select_field
+``` ruby
+  it { should have_select_field(:form_name, :field_name) }
+```

data/Rakefile ADDED

	@@ -0,0 +1 @@
1	+ require 'bundler/gem_tasks'

data/lib/page_match.rb ADDED

@@ -0,0 +1,7 @@
+require "page_match/page"
+module PageMatch
+  def self.match &block
+    PageMatch::Page.match &block
+  end
+end

data/lib/page_match/helpers.rb ADDED

@@ -0,0 +1,67 @@
+module PageMatch
+  module Helpers
+    def have_link(label)
+      PageMatch.match do |m|
+        m.have %(a link named "#{label}")
+        m.page { has_link?(label) }
+      end
+    end
+    def have_button(label)
+      PageMatch.match do |m|
+        m.have %(a button named "#{label}")
+        m.page { has_button?(label) }
+      end
+    end
+    def have_flash_notice(note)
+      PageMatch.match do |m|
+        m.have %(a flash notice containing "#{note}")
+        m.page { within("#flash_notice") { has_content?(note) } }
+      end
+    end
+    def have_flash_error(error)
+      PageMatch.match do |m|
+        m.have %(a flash error containing "#{error}")
+        m.page { within("#flash_error") { has_content?(error) } }
+      end
+    end
+    def have_form_error(error)
+      PageMatch.match do |m|
+        m.have %(a form error that contains "#{error}")
+        m.page { within(".error_messages") { has_content?(error) } }
+      end
+    end
+    def have_text_field(form, field)
+      PageMatch.match do |m|
+        m.have %(a text field on the #{form} form for #{field.inspect})
+        m.page { has_selector?(:xpath, %(.//input[@id="#{form}_#{field}"][@type="text"])) }
+      end
+    end
+    def have_text_area(form, field)
+      PageMatch.match do |m|
+        m.have %(a text area on the #{form} form for #{field.inspect})
+        m.page { has_selector?(:xpath, %(.//textarea[@id="#{form}_#{field}"])) }
+      end
+    end
+    def have_check_box(form, field)
+      PageMatch.match do |m|
+        m.have %(a checkbox on the #{form} form for #{field.inspect.gsub(/_$/, '')})
+        m.page { has_selector?(:xpath, %(.//input[@id="#{form}_#{field}"][@type="checkbox"])) }
+      end
+    end
+    def have_select_field(form, field)
+      PageMatch.match do |m|
+        m.have %(a select field on the #{form} form for #{field.inspect})
+        m.page { has_selector?(:xpath, %(.//select[@id="#{form}_#{field}"])) }
+      end
+    end
+  end
+end

data/lib/page_match/page.rb ADDED

@@ -0,0 +1,40 @@
+module PageMatch
+  class Page
+    attr_reader :description, :message
+    attr_accessor :contain, :not_contain, :did, :did_not
+    def initialize
+      @contain = %(expected the page to contain)
+      @not_contain = %(expected the page to not contain)
+      @did = %(but it did)
+      @did_not = %(but it didn't)
+    end
+    def self.match(&block)
+      page = Page.new
+      yield page if block_given?
+      page
+    end
+    def page(&block)
+      @page_block = block
+    end
+    def have(msg='')
+      @message = msg
+      @description = %(have #{msg})
+    end
+    def failure_message
+      %(#{contain} #{message}, #{did_not})
+    end
+    def negative_failure_message
+      %(#{not_contain} #{message}, #{did})
+    end
+    def matches?(page_instance)
+      page_instance.instance_eval(&@page_block)
+    end
+  end
+end

data/lib/page_match/version.rb ADDED

@@ -0,0 +1,3 @@
+module PageMatch
+  VERSION = "0.0.1"
+end

data/page_match.gemspec ADDED

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "page_match/version"
+Gem::Specification.new do |s|
+  s.name        = "page_match"
+  s.version     = PageMatch::VERSION
+  s.authors     = ["Brian V. Hughes"]
+  s.email       = ["brianvh@mac.com"]
+  s.homepage    = %(https://github.com/brianvh/page_match)
+  s.summary     = %(#{s.name}-#{s.version})
+  s.description = %(PageMatch: RSpec 2 matcher class for building custom
+Capybara matchers in acceptance tests.)
+  s.add_dependency 'capybara', '>= 1.0.0'
+  s.add_development_dependency 'bundler', '>= 1.0.15'
+  s.add_development_dependency 'rspec', '~> 2.6.0'
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/spec/page_spec.rb ADDED

@@ -0,0 +1,49 @@
+require 'rspec'
+require 'page_match'
+describe "PageMatch module" do
+  describe ".match" do
+    it "returns an instance of PageMatch::Page" do
+      matcher = PageMatch.match { have 'a Page instance' }
+      matcher.should be_instance_of(PageMatch::Page)
+    end
+  end
+end
+describe PageMatch::Page do
+  before(:each) do
+    @matcher = PageMatch::Page.new
+  end
+  it "initializes with a nil message attribute" do
+    @matcher.message.should be_nil
+  end
+  context "#matches? against a page object" do
+    before(:each) do
+      @page = mock(:page)
+    end
+    context "for a true match" do
+      before(:each) do
+        @page.should_receive(:is_true?).once.and_return(true)
+        @matcher.page { is_true? }
+      end
+      it "returns true" do
+        @matcher.should be_matches(@page)
+      end
+    end
+    context "for a false match" do
+      before(:each) do
+        @page.should_receive(:is_not_true?).once.and_return(false)
+        @matcher.page { is_not_true? }
+      end
+      it "returns false" do
+        @matcher.should_not be_matches(@page)
+      end
+    end
+  end
+end

metadata ADDED

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: page_match
+version: !ruby/object:Gem::Version
+  hash: 29
+  prerelease:
+  segments:
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors:
+- Brian V. Hughes
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2012-10-02 00:00:00 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        hash: 23
+        segments:
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        hash: 9
+        segments:
+        - 1
+        - 0
+        - 15
+        version: 1.0.15
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        hash: 23
+        segments:
+        - 2
+        - 6
+        - 0
+        version: 2.6.0
+  type: :development
+  version_requirements: *id003
+description: |-
+  PageMatch: RSpec 2 matcher class for building custom
+  Capybara matchers in acceptance tests.
+email:
+- brianvh@mac.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- README.md
+- Rakefile
+- lib/page_match.rb
+- lib/page_match/helpers.rb
+- lib/page_match/page.rb
+- lib/page_match/version.rb
+- page_match.gemspec
+- spec/page_spec.rb
+homepage: https://github.com/brianvh/page_match
+licenses: []
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 3
+      segments:
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 3
+      segments:
+      - 0
+      version: "0"
+requirements: []
+rubyforge_project:
+rubygems_version: 1.8.24
+signing_key:
+specification_version: 3
+summary: page_match-0.0.1
+test_files:
+- spec/page_spec.rb