CSS selector objects & methods for testing in Rails
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A Rails plugin to aid in application testing (with assert_select). It does this by giving you:

  • CSS selector objects (like Pathname's for filesystem paths), and
  • Additional assertion methods

Example Usage

With the plugin (see example_test.rb) rather than

assert_select 'div.some-div > form > input.an-input[text]', 'some-value'

you can say

t=DIV.css_class('some-div').child(FORM,INPUT).css_class('an-input').attribute TEXT
assert_select t, 'some-value'

Or, breaking it down further

s=DIV.css_class 'some-div'
f=s.child FORM
i=f.child(INPUT).css_class 'an-input'
t=i.attribute TEXT
assert_select t, 'some-value'


Of course, the assertion methods can be used with the above variables. For the effect of

assert_select f, 1, "#{f} count"
assert_select f.descend(i), 1, "#{f.descend i} count"

you can say, more simply

assert_descend f, i


Instead of

assert_select t, 1, "#{t} count"
assert_select t, 'some-value'

you can say

assert_single t, 'some-value'

If you have one attribute ('t') on your webpage, instead of

assert_select i, 1, "#{i} count"
assert_select "[#{t}]", 1, "#{t} count"
assert_select "#{i}[#{t}]", 1, "#{i}, #{t} count"
assert_select "[#{t}=?]", 'some-value'
assert_select "#{i}[#{t}=?]", 'some-value'

you can say

assert_single [i, t], 'some-value'

Or if you have multiple attributes ('t') on your webpage, instead of

assert_select i, 1, "#{i} count"
assert_select "#{i}[#{t}]", 1, "#{i}, #{t} count"
assert_select "#{i}[#{t}=?]", 'some-value'

you can say

assert_single [i, t], 'some-value', false

How To Install

In your Rails application, 'rails install plugin git://github.com/MarkDBlackwell/css-selector.git'.


Certain constants (e.g., DIV) useful in testing a Rails application are not brought in automatically. This avoids polluting your app namespace outside environment 'test'.

I haven't yet (fully) discovered how to include module CssSelector automatically in just that environment. Therefore, probably in (your app's) test/test_helper.rb, you should specify

include CssStringConstants
include CssSelector


Tested with Rails 3.0.9 & Ruby 1.8.7. Please let me know if you find anything wrong with it!

An example testbed is at css-selector-example

More Information

Evangelizing: CSS selector objects and methods for testing in Ruby or presentation, Rails testing with CssString (Css Selectors).

ActionDispatch::Assertions::SelectorAssertions: APIdock, RubyOnRails, RubyOnRails (old)

HTML::Selector: APIdock, RubyOnRails

Copyright (c) 2011 Mark D. Blackwell. See MIT-LICENSE for details.