capybara-extensions 0.2.0 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: be82a50d10aa44c6b41eed1bdadbe9ccc47962d9
+  data.tar.gz: 66a534229850cad98e8a94c9b1a6af35c4b3c01a
+SHA512:
+  metadata.gz: a9fa104f4f7223a6578ef81b9a2a3762791641a2b57e3dbec208cf9d2426f85cfda12cc4adc975e825c40f6734422b9d7b44d2de309a83b3d1845275070b223b
+  data.tar.gz: 06102011a95173369fddad6c73caf117237de3c09090c69ed0d93733cb9a76ccd1bb6c9a98793fdb122b26b18b65f8c30dc6b0ee82e49ba4be369ca9e10c15a5

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+bin/

data/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contribution Guidelines #
+
+## Submitting a new issue ##
+
+If you want to ensure that your issue gets fixed *fast* you should
+attempt to reproduce the issue in an isolated example application that
+you can share.
+
+## Making a pull request ##
+
+If you'd like to submit a pull request please adhere to the following:
+
+1. Your code *must* be tested. Please TDD your code!
+2. No single-character variables
+3. Two-spaces instead of tabs
+4. Single-quotes instead of double-quotes unless you are using string
+   interpolation or escapes.
+5. General Rails/Ruby naming conventions for files and classes
+
+Please note that you must adhere to each of the aforementioned rules.
+Failure to do so will result in an immediate closing of the pull
+request. If you update and rebase the pull request to follow the
+guidelines your pull request will be re-opened and considered for
+inclusion.

data/Gemfile

@@ -1,14 +1,4 @@
-source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
+source 'https://rubygems.org'
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem "shoulda", ">= 0"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.6.4"
-  gem "rcov", ">= 0"
-  gem "capybara"
-end
+# Specify your gem's dependencies in capybara_extensions.gemspec
+gemspec

data/LICENSE.txt

@@ -1,4 +1,6 @@
-Copyright (c) 2012 Andy Waite
+Copyright (c) 2013 Michael Dupuis Jr.
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,26 +1,45 @@
-# capybara-extensions
+# CapybaraExtensions
 
-Adds the following methods to Capybara::Node::Finders
+[Capybara](https://github.com/jnicklas/capybara) has an intuitive API which mimics the language of an actual user. This library extends Capybara's finders and matchers with additional methods for interacting with tables, lists, and list items, as well as many HTML5 elements.
 
-* parent
+## Installation
 
-## Usage
+Add this line to your application's Gemfile:
 
     gem 'capybara-extensions'
 
-    require 'capybara-extensions'
+And then execute:
 
-## Contributing to capybara-extensions
+    $ bundle
 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+Or install it yourself as:
 
-## Copyright
+    $ gem install capybara-extensions
 
-Copyright (c) 2012 Andy Waite. See LICENSE.txt for
-further details.
+## Setup
+
+Require `capybara-extensions`:
+
+```ruby
+require 'capybara-extensions'
+``` 
+
+## The DSL
+
+A complete reference of the finders and matchers added by CapybaraExtensions is available at [Rubydoc.info](http://rubydoc.info/github/dockyard/capybara-extensions). You can read more about the library in [this blog post](http://reefpoints.dockyard.com/2013/10/25/capybara-extensions.html).
+
+## Versioning
+
+This gem follows [semantic versioning](http://semver.org).
+
+## Contributing
+
+Please see our [contribution guidelines](/CONTRIBUTING.md) on how to
+properly submit issues and pull requests.
+
+## Legal
+
+[DockYard, Inc](http://dockyard.com) © 2013
+
+Licensed under the [MIT
+license](http://www.opensource.org/licenses/mit-license.php).

data/Rakefile

@@ -1,53 +1,11 @@
-# encoding: utf-8
-
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "capybara-extensions"
-  gem.homepage = "http://github.com/andyw8/capybara-extensions"
-  gem.license = "MIT"
-  gem.summary = %Q{Some useful extensions to Capybara}
-  gem.description = %Q{Some useful extensions to Capybara}
-  gem.email = "andy@andywaite.com"
-  gem.authors = ["Andy Waite"]
-  gem.add_dependency 'capybara'
-end
-Jeweler::RubygemsDotOrgTasks.new
-
+require "bundler/gem_tasks"
 require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
 
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-  test.rcov_opts << '--exclude "gems/*"'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
 end
 
 task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "capybara-extensions #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end

data/capybara-extensions.gemspec

@@ -1,65 +1,30 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
-# -*- encoding: utf-8 -*-
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'capybara-extensions/version'
 
-Gem::Specification.new do |s|
-  s.name = "capybara-extensions"
-  s.version = "0.2.0"
+Gem::Specification.new do |spec|
+  spec.name          = "capybara-extensions"
+  spec.version       = CapybaraExtensions::VERSION
+  spec.authors       = ["Michael Dupuis Jr.", 'Dan McClain']
+  spec.email         = ["michael.dupuis@dockyard.com", 'rubygems@danmcclain.net']
+  spec.description   = %q{Complements Capybara with additional finders and matchers.}
+  spec.summary       = %q{Capybara has an intuitive API which mimics the language of an actual user. This library extends Capybara's finders and matchers with additional methods for interacting with tables, lists, and list items, as well as many HTML5 elements.}
+  spec.homepage      = "https://github.com/dockyard/capybara-extensions"
+  spec.license       = "MIT"
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Andy Waite"]
-  s.date = "2012-03-25"
-  s.description = "Some useful extensions to Capybara"
-  s.email = "andy@andywaite.com"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.md"
-  ]
-  s.files = [
-    ".document",
-    "Gemfile",
-    "Gemfile.lock",
-    "LICENSE.txt",
-    "README.md",
-    "Rakefile",
-    "VERSION",
-    "capybara-extensions.gemspec",
-    "lib/capybara-extensions.rb",
-    "test/helper.rb",
-    "test/test_capybara-extensions.rb"
-  ]
-  s.homepage = "http://github.com/andyw8/capybara-extensions"
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.10"
-  s.summary = "Some useful extensions to Capybara"
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
+  spec.add_development_dependency 'builder'
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'capybara_minitest_spec'
+  spec.add_development_dependency 'minitest', '< 5.0'
+  spec.add_development_dependency 'minitest-reporters', '~> 0.14.21'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'yard'
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
-      s.add_development_dependency(%q<rcov>, [">= 0"])
-      s.add_development_dependency(%q<capybara>, [">= 0"])
-      s.add_runtime_dependency(%q<capybara>, [">= 0"])
-    else
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
-      s.add_dependency(%q<rcov>, [">= 0"])
-      s.add_dependency(%q<capybara>, [">= 0"])
-      s.add_dependency(%q<capybara>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
-    s.add_dependency(%q<rcov>, [">= 0"])
-    s.add_dependency(%q<capybara>, [">= 0"])
-    s.add_dependency(%q<capybara>, [">= 0"])
-  end
+  spec.add_runtime_dependency 'capybara', '~> 2.1.0'
 end
-

data/lib/capybara-extensions/finders.rb

@@ -0,0 +1,335 @@
+require_relative 'locators'
+
+module CapybaraExtensions::Finders
+  include CapybaraExtensions::Locators
+  CapybaraExtensions::ExtensionMethods.concat [:find_article, :find_aside, :find_footer, :find_form, :find_header, :find_list_item, :find_navigation, :find_ordered_list, :find_paragraph, :find_row, :find_section, :find_table, :find_unordered_list, :first_article, :first_aside, :first_footer, :first_form, :first_header, :first_navigation, :first_ordered_list, :first_paragraph, :first_row, :first_section, :first_table, :first_unordered_list, :list_item_number, :row_number]
+
+  # Find an HTML article based on the given arguments.
+  #
+  # @param args [String] text contained within the article sought.
+  # @param args [Object] the object whose article is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_article(args)
+    find_element('article', args)
+  end
+
+  alias_method :article, :find_article
+
+  # Find an HTML aside based on the given arguments.
+  #
+  # @param args [String] text contained within the aside sought.
+  # @param args [Object] the object whose aside is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_aside(args)
+    find_element('aside', args)
+  end
+
+  alias_method :aside, :find_aside
+
+  # Find an HTML footer based on the given arguments.
+  #
+  # @param args [String] text contained within the footer sought.
+  # @param args [Object] the object whose footer is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_footer(args)
+    find_element('footer', args)
+  end
+
+  alias_method :footer, :find_footer
+
+  # Find an HTML form based on the given arguments.
+  #
+  # @param args [String] text contained within the form sought.
+  # @param args [Object] the object whose form is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_form(args)
+    find_element('form', args)
+  end
+
+  alias_method :form, :find_form
+
+  # Find an HTML img based on the src and/or alt values.
+  #
+  # @param options [Hash] Must pass a hash containing the src and/or alt of the image sought.
+  # @return [Capybara::Element] the found element
+  #
+  def find_image(options = {})
+    raise "Must pass a hash containing 'src' or 'alt'" unless options.is_a?(Hash) && (options.has_key?(:src) || options.has_key?(:alt))
+    find(:xpath, "//img#{image_locator(options)}")
+  end
+
+  # Find an HTML header based on the given arguments.
+  #
+  # @param args [String] text contained within the header sought.
+  # @param args [Object] the object whose header is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_header(args)
+    find_element('header', args)
+  end
+
+  alias_method :header, :find_header
+
+  # Find an HTML li based on the given arguments.
+  #
+  # @param args [String] text contained within the li sought.
+  # @param args [Object] the object whose li is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_list_item(args)
+    find_element('li', args)
+  end
+
+  alias_method :list_item, :find_list_item
+
+  # Find an HTML nav based on the given arguments.
+  #
+  # @param args [String] text contained within the nav sought.
+  # @param args [Object] the object whose nav is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_navigation(args)
+    find_element('nav', args)
+  end
+
+  alias_method :navigation, :find_navigation
+
+  # Find an HTML ol based on the given arguments.
+  #
+  # @param args [String] text contained within the ol sought.
+  # @param args [Object] the object whose ol is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_ordered_list(args)
+    find_element('ol', args)
+  end
+
+  alias_method :ordered_list, :find_ordered_list
+
+  # Find an HTML p based on the given arguments.
+  #
+  # @param args [String] text contained within the p sought.
+  # @param args [Object] the object whose p is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_paragraph(args)
+    find_element('p', args)
+  end
+
+  alias_method :paragraph, :find_paragraph
+
+  # Find an HTML tr based on the given arguments.
+  #
+  # @param args [String] text contained within the tr sought.
+  # @param args [Object] the object whose tr is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_row(args)
+    find_element('tr', args)
+  end
+
+  alias_method :row, :find_row
+
+  # Find an HTML section based on the given arguments.
+  #
+  # @param args [String] text contained within the section sought.
+  # @param args [Object] the object whose section is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_section(args)
+    find_element('section', args)
+  end
+
+  alias_method :section, :find_section
+
+  # Find an HTML table based on the given arguments.
+  #
+  # @param args [String] text contained within the table sought.
+  # @param args [Object] the object whose table is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_table(args)
+    if String === args
+      find_element('table', args)
+    else
+      row = find_row(args)
+      row.find(:xpath, 'ancestor::table')
+    end
+  end
+
+  alias_method :table, :find_table
+
+  # Find an HTML ul based on the given arguments.
+  #
+  # @param args [String] text contained within the ul sought.
+  # @param args [Object] the object whose ul is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def find_unordered_list(args)
+    find_element('ul', args)
+  end
+
+  alias_method :unordered_list, :find_unordered_list
+
+  # Find the first HTML article on the page matching the given arguments.
+  #
+  # @param args [String] text contained within the article sought.
+  # @param args [Object] the object whose article is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_article(args)
+    first_element('article', args)
+  end
+
+  # Find the first HTML aside on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the aside sought; if passed an object, the object whose aside is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_aside(args)
+    first_element('aside', args)
+  end
+
+  # Find the first HTML footer on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the footer sought; if passed an object, the object whose footer is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_footer(args)
+    first_element('footer', args)
+  end
+
+  # Find the first HTML form on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the form sought; if passed an object, the object whose form is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_form(args)
+    first_element('form', args)
+  end
+
+  # Find the first HTML header on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the header sought; if passed an object, the object whose header is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_header(args)
+    first_element('header', args)
+  end
+
+  # Find the first HTML nav on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the nav sought; if passed an object, the object whose nav is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_navigation(args)
+    first_element('nav', args)
+  end
+
+  # Find the first HTML ol on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the ol sought; if passed an object, the object whose ol is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_ordered_list(args)
+    first_element('ol', args)
+  end
+
+  # Find the first HTML p on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the p sought; if passed an object, the object whose p is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_paragraph(args)
+    first_element('p', args)
+  end
+
+  # Find the first HTML tr on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the tr sought; if passed an object, the object whose tr is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_row(args)
+    first_element('tr', args)
+  end
+
+  # Find the first HTML section on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the section sought; if passed an object, the object whose section is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_section(args)
+    first_element('section', args)
+  end
+
+  # Find the first HTML table on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the table sought; if passed an object, the object whose table is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_table(args)
+    first_element('table', args)
+  end
+
+  # Find the first HTML ul on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the ul sought; if passed an object, the object whose ul is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_unordered_list(args)
+    first_element('ul', args)
+  end
+
+  # When scoped to an ol or ul, find the first HTML li on the page matching the given arguments.
+  #
+  # @param number [Integer] the nth li element sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def list_item_number(number)
+    all('li')[number.to_i - 1]
+  end
+
+  # When scoped to a table, find the first HTML tr on the page matching the given arguments.
+  #
+  # @param number [Integer] the nth tr element sought 
+  # @return [Capybara::Element] the found element.
+  #
+  def row_number(number)
+    find('tbody').all('tr')[number.to_i - 1]
+  end
+
+  private
+
+  # Find an element matching the given arguments
+  #
+  # @param tag [String] the HTML tag for the element
+  # @param args [String] the text used to find the element
+  # @param args [Object] the object used to find the element. Designed to work with the `content_tag_for` method in Rails, which creates an HTML element with the class and id parameters that relate to the specified Active Record object.
+  #
+  def find_element(tag, args)
+    if String === args
+      find(tag, text: args)
+    else
+      klass = args.class.to_s.downcase
+      find("#{tag}##{klass}_#{args.id}", "#{tag}.#{klass}")
+    end
+  end
+
+  # Find the first element on the page matching the given arguments.
+  #
+  # @param args [String, Object] if passed a string, the text contained within the element sought; if passed an object, the object whose element is sought.
+  # @return [Capybara::Element] the found element.
+  #
+  def first_element(tag, args)
+    if String === args
+      first(tag, text: args)
+    else
+      klass = args.class.to_s.downcase
+      first("#{tag}##{klass}_#{args.id}", "#{tag}.#{klass}")
+    end
+  end
+end

data/lib/capybara-extensions/locators.rb

@@ -0,0 +1,28 @@
+# Locators for xpath.
+module CapybaraExtensions::Locators
+
+  # Builds a locator via the given src or alt.
+  #
+  # @param options[Hash] must pass a hash containing src and/or alt to match against.
+  # @return [String] string formatted for finding an attribute with xpath.
+  #
+  def image_locator(options)
+    locator = String.new
+    locator.concat "[@alt='#{options[:alt]}']" if options[:alt]
+    locator.concat "[@src='#{options[:src]}']" if options[:src]
+    locator
+  end
+
+  # Builds a locator via the given name and content.
+  #
+  # @params name[String] the name of the meta tag sought.
+  # @params content [String] the content of the meta tag sought.
+  # @return [String] string formatted for finding a meta tag with xpath.
+  #
+  def meta_tag_locator(name, content)
+    locator = String.new
+    locator.concat "[@name='#{name}']"
+    locator.concat "[@content='#{content}']"
+    locator
+  end
+end