capybara-js_finders 0.2.0

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+nbproject
+README.test.html

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in capybara-js_finders.gemspec
+gemspec
+
+# gem 'bbq', :path => '/home/rupert/develop/bbq'

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Robert Pankowecki, Gavdi Polska
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# Capybara JS Finders
+
+Capybara JS Finders is a set of additional finders for capybara. Currently it only contains cell finder which allows
+you to find a table cell based on column and row descriptions.
+
+## Installation
+
+Simply add it to your Gemfile and bundle it up:
+
+```ruby
+gem 'capybara-js_finders', '~> 0.0.1'
+gem 'capybara'
+```
+
+Make sure to add it before `capybara` in your Gemfile!
+
+## API
+
+Use it like any other capybara finder.
+
+### find_cell
+
+Allows you to find table cell (td, th) based on cell and row descriptions.
+The method is colspan and rowspan attribute-aware which means it will be able to find
+a cell even if it is under collspaned th containing a description.
+
+#### Example
+
+    <table>
+      <tr>
+        <th>
+          User
+        </th>
+        <th>
+          Email
+        </th>
+        <th>
+          Permissions
+        </th>
+      </tr>
+
+      <tr>
+        <td>
+          John Smith
+        </td>
+        <td>
+          john@example.org
+        </td>
+        <td>
+          Admin
+        </td>
+      </tr>
+
+      <tr>
+        <td>
+          Andrew Bon
+        </td>
+        <td>
+          andrew@example.org
+        </td>
+        <td>
+          Moderator
+        </td>
+      </tr>
+
+    </table>
+
+```ruby
+assert find_cell(:row => "John Smith", :column => "Permissions").has_content?("Admin")
+assert find_cell(:row => "Andrew Bon", :column => "Email").has_no_content?("john")
+```
+
+#### Example
+
+```ruby
+assert find_cell(:row => "John Smith", :column => "January", :text => "28").has_text?("Present at work")
+```
+
+#### Multicolumn and multirows support
+
+If there are many rows and/or columns matching `:row` and/or `:column` parameter you can wider the search to include all of them
+by using `:multirow` and/or `:multicolumn` action.
+
+##### Example
+
+    <table>
+      <tr>
+        <th>
+          User
+        </th>
+        <th>
+          Email
+        </th>
+        <th>
+          Permissions
+        </th>
+      </tr>
+
+      <tr>
+        <td>
+          John Smith
+        </td>
+        <td>
+          john@example.org
+        </td>
+        <td>
+          Admin
+        </td>
+      </tr>
+
+      <tr>
+        <td>
+          John Smith
+        </td>
+        <td>
+          smith@example.org
+        </td>
+        <td>
+          Moderator
+        </td>
+      </tr>
+
+    </table>
+
+```ruby
+find_cell(:row => "John Smith", :column => "Permissions", :text => "Moderator") # raises an exception
+find_cell(:multirow => true, :row => "John Smith", :column => "Permissions", :text => "Moderator") # will find the proper cell
+```
+
+## License
+
+MIT License
+
+## Integration
+
+Integrates nicely with bbq
+
+```ruby
+user = Bbq::TestUser.new(:driver => :selenium, :session_name => :default)
+user.visit '/page'
+assert user.find_cell(:row => "RowDescription", :column => "ColumnDescription").has_content?("CellContent")
+```

data/Rakefile

@@ -0,0 +1,47 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+require 'rdoc/task'
+require 'rake/testtask'
+require 'rake'
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Capybara JS Finders'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test
+
+task :script do
+  require "capybara-js_finders"
+  puts Capybara::JsFinders::SCRIPT
+end
+
+namespace :find_cell_tests do
+  task :app do
+    $LOAD_PATH << './test'
+    require 'unit/find_cell_tests/app/app'
+    FindCellTests::App.run!
+  end
+end
+
+task :readme do
+  #require 'redcloth'
+  `redcarpet README.md > README.test.html`
+end

data/capybara-js_finders.gemspec

@@ -0,0 +1,42 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "capybara-js_finders/version"
+
+Gem::Specification.new do |s|
+  s.name        = "capybara-js_finders"
+  s.version     = Capybara::JsFinders::VERSION
+  s.authors     = ["Robert Pankowecki"]
+  s.email       = %w(robert.pankowecki@gmail.com rpa@gavdi.com)
+  s.homepage    = "https://github.com/paneq/capybara-js_finders"
+  s.summary     = %q{Additional finders for capybara that for some reason cannot use only xpath for finding nodes but needs to execute js for some calculations}
+  s.description = <<-DESC
+    Additional finders for capybara that for some reason
+    cannot use only xpath for finding nodes but needs to
+    execute js for some calculations.
+
+    Ex: I you want to find a table cell
+    that is under or next to other cell the easiest way to do it is to
+    check their position on page and compare them. This way you do not
+    need to wory about calculating the effects of using colspan 
+    and rowspan attributes.
+
+    The downside is that you need to use capybara driver that runs
+    a browser like selenium.
+  DESC
+
+  s.rubyforge_project = "capybara-js_finders"
+
+  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"]
+
+  s.add_dependency "capybara", "~> 1.0.0"
+  s.add_development_dependency "rake", "~> 0.9.0"
+  s.add_development_dependency "rdoc", ">= 2.4.2"
+  s.add_development_dependency "sinatra", "~> 1.2.6"
+  s.add_development_dependency "erubis", "~> 2.6.6"
+  s.add_development_dependency "bbq", "~> 0.0.3"
+  s.add_development_dependency "redcarpet", "~> 1.17"
+  s.add_development_dependency "ruby-debug19"
+end

data/lib/capybara-js_finders/capybara_extensions.rb

@@ -0,0 +1,33 @@
+require 'capybara/node/finders'
+
+Capybara::Node::Finders.send(:include, Capybara::JsFinders)
+
+require 'capybara/dsl'
+
+Capybara::DSL.module_eval do
+  def execute_script(*args, &block)
+    page.execute_script(*args, &block)
+  end
+  def find_cell(*params, &block)
+    page.find_cell(*params, &block)
+  end
+end
+
+require 'capybara'
+
+Capybara::Node::Base.module_eval do
+  def execute_script(script)
+    driver.execute_script(script)
+  end
+  def evaluate_script(script)
+    driver.evaluate_script(script)
+  end
+end
+
+Capybara::Session::NODE_METHODS << :find_cell
+Capybara::Session::DSL_METHODS  << :find_cell
+Capybara::Session.class_eval do
+  def find_cell(*params, &block)
+    current_node.find_cell(*params, &block)
+  end
+end

data/lib/capybara-js_finders/version.rb

@@ -0,0 +1,5 @@
+module Capybara
+  module JsFinders
+    VERSION = "0.2.0"
+  end
+end

data/lib/capybara-js_finders/xpath_extensions.rb

@@ -0,0 +1,27 @@
+require 'xpath'
+
+module XPath
+  class Expression
+    class Father < Multiple
+      def to_xpath(predicate=nil)
+        if @expressions.length == 1
+          "#{@left.to_xpath(predicate)}/../self::#{@expressions.first.to_xpath(predicate)}"
+        elsif @expressions.length > 1
+          "#{@left.to_xpath(predicate)}/../self::*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
+        else
+          "#{@left.to_xpath(predicate)}/../self::*"
+        end
+      end
+    end
+  end
+
+  def father(*expressions)
+    Expression::Father.new(current, expressions)
+  end
+end
+
+XPath::HTML.module_eval do
+  def cell(locator)
+    descendant(:td, :th)[attr(:id).equals(locator) | string.n.is(locator)]
+  end
+end

data/lib/capybara-js_finders.rb

@@ -0,0 +1,129 @@
+require "capybara-js_finders/version"
+require "capybara-js_finders/xpath_extensions"
+
+module Capybara
+
+  module JsFinders
+
+    extend XPath
+
+    LR = "lr".freeze # Left range
+    RR = "rr".freeze # Right range
+    TR = "tr".freeze # Top range
+    BR = "br".freeze # Bottom range
+    XpathTrue = "(1=1)"
+
+    # TODO: This script is only prototype compatibile. Let it discover jquery or prototype and use proper methods.
+    SCRIPT = <<-JS
+    xpathResult = document.evaluate( "#{descendant(:th, :td)}", document, null, XPathResult.ANY_TYPE, null);
+    var ary = [];
+    var td;
+    while( td = xpathResult.iterateNext() ){
+      ary.push(td);
+    }
+    ary.each(function(ele){
+      var offset = ele.cumulativeOffset();
+      var lr = offset.left;
+      var rr = lr + ele.getWidth();
+      var tr = offset.top;
+      var br = tr + ele.getHeight();
+      ele.setAttribute('#{LR}', lr);
+      ele.setAttribute('#{RR}', rr);
+      ele.setAttribute('#{TR}', tr);
+      ele.setAttribute('#{BR}', br);
+    });
+    JS
+    SCRIPT.freeze
+
+    def self.overlaps_columns(columns)
+      return XpathTrue if columns.first == true
+      columns_xpath = columns.map{|column| overlaps_column(column) }.join(" or ")
+      columns_xpath = "( #{columns_xpath} )"
+      return columns_xpath
+    end
+
+    def self.overlaps_column(column)
+      overlaps_horizontal(column[LR], column[RR])
+    end
+
+    # clr, crr - Column left and right range
+    def self.overlaps_horizontal(clr, crr)
+      "(./@#{RR} >= #{clr} and ./@#{LR} <= #{crr})"
+    end
+
+    def self.overlaps_rows(rows)
+      return XpathTrue if rows.first == true
+      rows_xpath = rows.map{|row| overlaps_row(row) }.join(" or ")
+      rows_xpath = "( #{rows_xpath} )"
+      return rows_xpath
+    end
+
+    def self.overlaps_row(row)
+      overlaps_vertical(row[TR], row[BR])
+    end
+
+    # rtr, rbr - row top and bottom range
+    def self.overlaps_vertical(rtr, rbr)
+      "(./@#{BR} >= #{rtr} and ./@#{TR} <= #{rbr})"
+    end
+
+    # Condition for td to be under one of column and on the same level as one of the rows
+    def self.cell_condition(columns, rows)
+      xpath = "( #{overlaps_rows(rows)} ) and ( #{overlaps_columns(columns)} ) "
+      return xpath
+    end
+
+    # :column - text which should appear in the table column, or td/th Capybara::Node::Element object [or Array of them]
+    #           representing the columns which narrow the search area of the table. Nil is allowed.
+    #
+    # :row - text which should appear in the row of the table, or td/th Capybara::Node::Element object [or Array of them]
+    #           representing the columns which narrow the search area of the table. Nil is allowed.
+    # :text - text which should appear in the cell
+    # :multicolumn - set to true if finding column by test should return multiple results instead of just one
+    # :multirow - set to true if finding rows by test should return multiple results instead of just one
+    #
+    # :visible
+    # :with
+    def find_cell(options = {})
+      # TODO: Jak pierwszy arg to string to wywolaj cell zamiast tego
+
+      columns = case options[:column]
+      when String
+        method = options[:multicolumn] ? :all : :find
+        send(method, :xpath, XPath::HTML.cell(options[:column]) ) # TODO: jak all to musi byc conajmniej 1
+      when Capybara::Node::Element
+        options[:column]
+      when Array
+        options[:column].each{|x| raise ArgumentError unless x.is_a?(Capybara::Node::Element) }
+      when NilClass
+        true
+      else
+        raise ArgumentError
+      end
+      columns = Array.wrap(columns)
+
+      rows = case options[:row]
+      when String
+        method = options[:multirow] ? :all : :find
+        send(method, :xpath, XPath::HTML.cell(options[:row]) ) # TODO: jak all to musi byc conajmniej 1
+      when Capybara::Node::Element
+        options[:row]
+      when Array
+        options[:row].each{|x| raise ArgumentError unless x.is_a?(Capybara::Node::Element) }
+      when NilClass
+        true
+      else
+        raise ArgumentError
+      end
+      rows = Array.wrap(rows)
+
+      execute_script(SCRIPT)
+      xpath = JsFinders.cell_condition(columns, rows)
+      xpath = ".//td[ #{xpath} ]"
+      #puts xpath
+      find(:xpath, xpath, options)
+    end
+  end
+end
+
+require "capybara-js_finders/capybara_extensions"

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require 'test/unit'
+
+require 'sinatra'
+require 'bbq/test'
+require 'erubis'
+
+require 'capybara-js_finders'
+require 'capybara'

data/test/unit/find_cell_tests/app/app.rb

@@ -0,0 +1,13 @@
+require 'sinatra'
+
+module FindCellTests
+
+  class App < Sinatra::Base
+    set :views,  File.join(  File.expand_path( File.dirname(__FILE__) ),  'views'  )
+    set :public, File.join(  File.expand_path( File.dirname(__FILE__) ),  'public'  )
+    get "/" do
+      erubis :table
+    end
+  end
+  
+end