Permalink
Browse files

Merge pull request #23 from wapcaplet/docstrings

Added method docstrings
  • Loading branch information...
2 parents 3cc52ba + 17704bc commit 250d83d3f8c11cec3552999b83d535ce54866047 @jnicklas jnicklas committed Aug 10, 2011
Showing with 109 additions and 0 deletions.
  1. +109 −0 lib/xpath/html.rb
View
109 lib/xpath/html.rb
@@ -3,30 +3,70 @@ module HTML
include XPath
extend self
+ # Match an `a` link element.
+ #
+ # @param [String] locator
+ # Text, id, title, or image alt attribute of the link
+ # @option options [String] :href
+ # `href` attribute of the link
+ #
def link(locator, options={})
href = options[:href]
link = descendant(:a)[href ? attr(:href).equals(href) : attr(:href)]
link[attr(:id).equals(locator) | string.n.is(locator) | attr(:title).is(locator) | descendant(:img)[attr(:alt).is(locator)]]
end
+
def content(locator)
child(:"descendant-or-self::*")[current.n.contains(locator)]
end
+
+ # Match a `submit`, `image`, or `button` element.
+ #
+ # @param [String] locator
+ # Value, title, id, or image alt attribute of the button
+ #
def button(locator)
button = descendant(:input)[attr(:type).one_of('submit', 'image', 'button')][attr(:id).equals(locator) | attr(:value).is(locator) | attr(:title).is(locator)]
button += descendant(:button)[attr(:id).equals(locator) | attr(:value).is(locator) | string.n.is(locator) | attr(:title).is(locator)]
button += descendant(:input)[attr(:type).equals('image')][attr(:alt).is(locator)]
end
+
+ # Match anything returned by either {#link} or {#button}.
+ #
+ # @param [String] locator
+ # Text, id, title, or image alt attribute of the link or button
+ #
def link_or_button(locator)
link(locator) + button(locator)
end
+
+ # Match any `fieldset` element.
+ #
+ # @param [String] locator
+ # Legend or id of the fieldset
+ #
def fieldset(locator)
descendant(:fieldset)[attr(:id).equals(locator) | descendant(:legend)[string.n.is(locator)]]
end
+
+ # Match any `input`, `textarea`, or `select` element that doesn't have a
+ # type of `submit`, `image`, or `hidden`.
+ #
+ # @param [String] locator
+ # Label, id, or name of field to match
+ # @option options [Bool] :checked
+ # Match only if the input has a `checked` attribute
+ # @option options [Bool] :unchecked
+ # Match only if the input does not have a `checked` attribute
+ # @option options [String] :with
+ # Text that matches only elements with this value
+ # (`value` attribute or contained text)
+ #
def field(locator, options={})
xpath = descendant(:input, :textarea, :select)[~attr(:type).one_of('submit', 'image', 'hidden')]
xpath = locate_field(xpath, locator)
@@ -36,13 +76,32 @@ def field(locator, options={})
xpath
end
+
+ # Match any `input` or `textarea` element that can be filled with text.
+ # This excludes any inputs with a type of `submit`, `image`, `radio`,
+ # `checkbox`, `hidden`, or `file`.
+ #
+ # @param [String] locator
+ # Label, id, or name of field to match
+ # @option options [String] :with
+ # Text that matches only elements with this value
+ # (`value` attribute or contained text)
+ #
def fillable_field(locator, options={})
xpath = descendant(:input, :textarea)[~attr(:type).one_of('submit', 'image', 'radio', 'checkbox', 'hidden', 'file')]
xpath = locate_field(xpath, locator)
xpath = xpath[field_value(options[:with])] if options.has_key?(:with)
xpath
end
+
+ # Match any `select` element.
+ #
+ # @param [String] locator
+ # Label, id, or name of the field to match
+ # @option options [Array] :options
+ # @option options [Array] :selected
+ #
def select(locator, options={})
xpath = locate_field(descendant(:select), locator)
@@ -57,32 +116,76 @@ def select(locator, options={})
xpath
end
+
+ # Match any `input` element of type `checkbox`.
+ #
+ # @param [String] locator
+ # Label, id, or name of the checkbox to match
+ #
def checkbox(locator, options={})
xpath = locate_field(descendant(:input)[attr(:type).equals('checkbox')], locator)
end
+
+ # Match any `input` element of type `radio`.
+ #
+ # @param [String] locator
+ # Label, id, or name of the radio button to match
+ #
def radio_button(locator, options={})
locate_field(descendant(:input)[attr(:type).equals('radio')], locator)
end
+
+ # Match any `input` element of type `file`.
+ #
+ # @param [String] locator
+ # Label, id, or name of the file field to match
+ #
def file_field(locator, options={})
locate_field(descendant(:input)[attr(:type).equals('file')], locator)
end
+
+ # Match an `optgroup` element.
+ #
+ # @param [String] name
+ # Label for the option group
+ #
def optgroup(name)
descendant(:optgroup)[attr(:label).is(name)]
end
+
+ # Match an `option` element.
+ #
+ # @param [String] name
+ # Visible text of the option
+ #
def option(name)
descendant(:option)[string.n.is(name)]
end
+
+ # Match any `table` element.
+ #
+ # @param [String] locator
+ # Caption or id of the table to match
+ # @option options [Array] :rows
+ # Content of each cell in each row to match
+ #
def table(locator, options={})
xpath = descendant(:table)[attr(:id).equals(locator) | descendant(:caption).contains(locator)]
xpath = xpath[table_rows(options[:rows])] if options[:rows]
xpath
end
+
+ # Match content in consecutive table rows.
+ #
+ # @param [Array] rows
+ # Array of arrays of strings containing cell content to match
+ #
def table_rows(rows)
row_conditions = descendant(:tr)[table_row(rows.first)]
rows.drop(1).each do |row|
@@ -91,6 +194,12 @@ def table_rows(rows)
row_conditions
end
+
+ # Match content in consecutive table cells.
+ #
+ # @param [Array] cells
+ # Array of strings to match against consecutive cell contents.
+ #
def table_row(cells)
cell_conditions = child(:td, :th)[string.n.equals(cells.first)]
cells.drop(1).each do |cell|

0 comments on commit 250d83d

Please sign in to comment.