Roadkill

Automated testing for web apps written in any language.

TL;DR:

This gem lets you easily install Capybara with PhantomJS and easily use them from any web application project directory so that you can start writing tests for your web application's pages right away.

If you're new to acceptance testing, it even includes sample tests and a tiny app to get you started playing with it!

Description:

Testing the web pages that your application displays to your users is important, no matter how the technology you work with creates and serves them. Whether its a dynamic database-driven application or a blog being statically generated from time to time, any site can benefit from tests that will spot problems before your visitors see them.

When it comes to writing acceptance tests, Rails developers have excellent gems that make using tools like Capybara or Cucumber easy when keeping the page-level behavior of their features well covered and up-to-date. But what about PHP, Python, JavaScript, or Java devs? Heck, what about plain old static HTML?

The purpose of this gem is to bring a similar level of ease in adding acceptance tests to any web development project, regardless of the stack being used. The gem painlessly brings together Capybara for headless Webkit testing with PhantomJS for JavaScript support through the Poltergeist driver. It includes a tiny example web app for trying out the tools with a couple of sample test specs.

After installing the gem and pointing the spec_helper file to the address and/or port number of your web application, you'll easily be able to start adding your own test specs that can navigate your site, detect content on a page, click on links, and interact with your UI elements. Sleep better at night, knowing that your site is wrapped up in a warm security blanket of automated scrutiny.

Installation:

gem install roadkill

Roadkill uses the headless browser phantomjs to run your tests. If you need to install phantomjs, you can do so directly with roadkill:

roadkill install_phantomjs

The installer will ask whether you want to use the 32 or 64 bit version of phantomjs.

Sample Application:

Roadkill contains a sample rack application to show you how to use an acceptance test suite with a live application. Although we used rack for the application, please keep in mind that the app could be written in anything - node, PHP, or even ...(cringe java).

To see the sample app, run:

roadkill sample_app

This will create a directory called sample_app. To run the acceptance tests for this app, you will first need to bundle install the gems:

cd sample_app/tests && bundle install && cd ..

The gems necessary to test your site are now installed. Let's start the rack application.

rackup config.ru

Awesome! We now have a simple application running. You should be able to visit http://localhost:9292 , and see a simple application.

We have some basic acceptance tests already written for the app. Let's run these tests.

cd tests

rspec spec

Yay! Passing tests! Roadkill is actually interacting with the app through the phantomjs browser.

Usage:

Once you're ready to create tests for your own project, it's as simple as running a generator within the project directory of your choice. Enter your project directory:

cd your_project

Let's ask roadkill to generate the tests directory, where everything will be contained. The command will ask you for some information about your site in order to start testing properly.

roadkill generate

Excellent. We now have a place to store acceptance tests. Let's get all the gems installed:

bundle install

Go ahead and create some capybara tests in the acceptance directory. Anything in the "acceptance" directory that ends with "_spec.rb" will be run. You can now run the tests against your site:

rspec spec

You now have a method for running simple, powerful tests against your site.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request