# Roadkill

##TL;DR:
This gem lets you easily install [Capybara](https://github.com/jnicklas/capybara) with [PhantomJS](https://github.com/ariya/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](https://github.com/jnicklas/capybara) for headless Webkit testing with [PhantomJS](https://github.com/ariya/phantomjs) for JavaScript support through the [Poltergeist](https://github.com/jonleighton/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](http://phantomjs.org/) to run your tests.  If you need to install [phantomjs](http://phantomjs.org/), 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](https://github.com/jnicklas/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