Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Headless HTMLUnit powered browser for Capybara
Branch: master
Failed to load latest commit information.
bin Add 'ku' to JRuby options. This make JRuby works in UTF-8 mode
docs Add configuration section to documentation
lib Use new registration name in bin/akephalos
spec Flag failing capybara specs as pending
src/htmlunit Version bump for htmlunit-2.8
tasks Update rake and requirements for rspec2
.rspec Migrating to Capybara 0.4: updated Capybara and RSpec dependencies in…
.watch Adding general usage documentation for github page
Gemfile Add rubygems source to Gemfile
MIT_LICENSE Adding general usage documentation for github page Add configuration section to documentation
Rakefile Fix rake release task
TODO.txt Version bump to 0.0.5
VERSION Version bump to 0.0.5
akephalos.gemspec Lock capybara dependency to 0.4 series


Akephalos is a full-stack headless browser for integration testing with Capybara. It is built on top of HtmlUnit, a GUI-less browser for the Java platform, but can be run on both JRuby and MRI with no need for JRuby to be installed on the system.


gem install akephalos


Configuring akephalos is as simple as requiring it and setting Capybara's javascript driver:

require 'akephalos'
Capybara.javascript_driver = :akephalos

Basic Usage

Akephalos provides a driver for Capybara, so using Akephalos is no different than using Selenium or Rack::Test. For a full usage guide, check out Capybara's DSL documentation. It makes no assumptions about the testing framework being used, and works with RSpec, Cucumber, and Test::Unit.

Here's some sample RSpec code:

describe "Home Page" do
  before { visit "/" }
  context "searching" do
    before do
      fill_in "Search", :with => "akephalos"
      click_button "Go"
    it "returns results" { page.should have_css("#results") }
    it "includes the search term" { page.should have_content("akephalos") }


There are now a few configuration options available through Capybara's new register_driver API.

Using a different browser

HtmlUnit supports a few browser implementations, and you can choose which browser you would like to use through Akephalos. By default, Akephalos uses Firefox 3.6.

Capybara.register_driver :akephalos do |app|
  # available options:
  #   :ie6, :ie7, :ie8, :firefox_3, :firefox_3_6, :browser => :ie8)

Ignoring javascript errors

By default HtmlUnit (and Akephalos) will raise an exception when an error is encountered in javascript files. This is generally desireable, except that certain libraries aren't supported by HtmlUnit. If possible, it's best to keep the default behavior, and use Filters (see below) to mock offending libraries. If needed, however, you can configure Akephalos to ignore javascript errors.

Capybara.register_driver :akephalos do |app|, :validate_scripts => false)


  • bin/akephalos allows you to start an interactive shell or DRb server, as well as perform other maintenance features.

  • Filters allows you to declare mock responses for external resources and services requested by the browser.


Something went wrong with that request. Please try again.