Skip to content


Repository files navigation


This project aims to reduce the difficulties involved in writing selenium tests in cucumber environments for webapps that use jQuery.

The project contains several methods to help you with writing javascript commands for selenium and javascript based tests for cucumber or maybe even rSpec.

What does the name stand for:

  • r - rspec

  • S - Selenium

  • query - jQuery


The project’s origin lies in a project we work on at which makes use of jQuery for most of its tasks. Selenium tests were the only way to test this application (as webrat isn’t an option to test js actions) and writing these tests were taking all the speed and fun out of the project. Testing with jquery matchers instead of those provided by selenium sounded very handy and after some hours of frustration we hacked these few lines together and because we noticed enormous speed enhancements in writing tests, I decided to wrap things up in a gem and release it to whoever would like to use jQuery matchers in an easy way to handle tests.

How it works

The source code is so short it should speak for itself but let me explain the concept.

Everything works around a central jquery matcher you call with ‘jquery(matcher)’. If you leave out ‘matcher’ the matcher returns the whole document.

The matcher must match exactly one element or it will raise an error. This behaviour makes testing easier for me, but I’m still in search for a better idea here. For now it does the job.

You can call methods upon the matched jquery object: ‘wait_for_element(matcher)’, ‘wait_for_no_element(matcher), ’wait_for_text(text)‘, ’wait_for_visible’, ‘wait_for_invisible’.

Other methods will call that same method upon the jQuery wrapper. Example: jquery(“#content”).html will call ‘$(“#content”).html()’ in the page you’re testing and return whatever that method returns as a string.


Using the gem in a project with jQuery enables stuff like:

  • jquery(“#content”).wait_for_visible

  • jquery(“#dialog button:contains(Ok)”).click

  • jquery.wait_for_text(“User saved…”)

  • jquery.wait_for_element(“.some_element”)

  • jquery(“#dialog div”).text.should have_text(/some_text/)

  • jquery(“#dialog”).find(“.warning”)

  • jquery(“#dialog”).html.should have_tag(“button”, “Ok”)

  • jquery(“#dialog”).should be_visible

  • jquery(“#dialog”) # page must have an element with id ‘dialog’


  • if you didn’t run this allready: gem sources -a

  • sudo gem install caifara-rSquery

  • in features/support/selenium_env.rb add ‘require “rSquery”`


  • rSquery only works if jquery is activated on the page you test (obviously).

  • rSquery can only do tests that are purely javascript based. Clicking links will not work, use normal selenium commands for triggering js-less events (just like jQuery itself).


  • rspec (gem)

  • cucumber (gem)

  • webapp using jQuery

  • selenium-client (gem)


In order to run the tests as described you’ll need:

  • selenium-client >= 1.2.14

  • thin

  • rack

  • jeweller (sudo gem install technicalpickles-jeweler -s

A directory called test contains the html page on which the features will run. To start a webserver in this directory you can use thin. cd to the test-dir and run ‘thin -R ../features/support/ -p 3002 start’.

Run selenium in another terminal. ‘selenium -singleWindow -browserSessionreuse’ should be ideal.

Run the features (rake features)

Copyright © 2009 Ivo Dancet & Wouter Vancraeynest, See LICENSE for details.