The Quest Continues: Introducing capybara-webkit

We recently blogged about our experiences and ongoing efforts to discover and improve tools for Javascript testing. In closing, we mentioned that we were fairly happy with Akephalos, but we didn’t believe the quest was over. Today, the quest continues.

Akephalos

Akephalos is a well-written driver that integrates soundly with the htmlunit virtual browser. However, as well-integrated as Akephalos is into both Capybara and htmlunit, it can only ever be as strong as htmlunit. As our applications became more sophisticated and large, we began to run into issues with htmlunit.

• Bugs: as previously mentioned, there are bugs in htmlunit, specifically with jQuery’s live. Although all browser implementations have bugs, it’s more useful if tests experience the same bugs as actual browsers.
• Compatibility: htmlunit doesn’t fully implement the feature set that modern browsers do. For example, it doesn’t fully handle DOM ranges or Ajax file uploads.
• Rendering: htmlunit doesn’t actually render the page, so tests that depend on CSS visibility or positioning won’t work.
• Performance: when most of your tests use Javascript, test suites with htmlunit start to crawl. It takes a while to start up a test with Akephalos, and a large test suite can easily take 10 or 15 minutes.

These issues made us realize that virtual browsers like envjs and htmlunit are never going to keep pace with actual browsers. If we want to write applications using features from the latest and greatest browsers, we’re going to need to test with them, too.

Selenium

That brought us back to the old mirage: Selenium. Selenium is well-supported, well-maintained, and works with real browsers. Integration with Ruby tests has improved considerably since the old Webrat days, and speed is better in some cases, as real browsers have been heavily optimized.

However, Selenium still has some ongoing issues that aren’t easy to solve:

• Timing: because Selenium uses a real browser, it doesn’t have as much control as a virtual browser does. This leads to issues with timing, causing erratic test failures.
• Overhead: real browsers come with features we don’t need, like a UI and plugins. This slows things down a bit.
• Gotchas: real browsers come with strange edge cases. Using Selenium and Firefox, sometimes the tests crash because Firefox tries to update the browser. Firefox doesn’t allow more than one instance to run at once. These gotchas are inevitable, because real browsers weren’t designed to be driven programatically.

We were forced to use Selenium because we needed all the capabilities of a real browser, but all these issues kept us looking for something better.

capybara-webkit

What we need was a real rendering engine coupled with a full Javascript and DOM implementation, but without all the cruft of a GUI browser. What we really wanted was a headless implementation of WebKit’s rendering engine that could be driven by Capybara tests. After Tristan “Websockets” Dunn showed me PhantomJs, I realized this might be possible using Qt’s WebKit implementation.

It was possible. I’d like to introduce a headless WebKit driver for capybara: capybara-webkit.

capybara-webkit has the following benefits:

• Compatibility: uses a real rendering engine (WebKit)
• Simplicity: runs headlessly, and designed to be controlled programatically
• Performance: faster than htmlunit - the test suites we’ve tried it on so far yielded 15-25% speed increases

The holy grail?

We designed capybara-webkit to solve the problems we had with other solutions, and so far it fits the bill nicely. We believe the quest is far from over, but we invite you to try out capybara-webkit on your own and see if this latest tool can take you a little further on your quest for the perfect testing solution.

Please keep in mind that this is a new driver and isn’t battle-tested as well as Akephalos or Selenium. If you discover any bugs, please report them in Github Issues. We’d also be happy to accept tested patches.

Next Steps & Related Reading

End-to-end testing with RSpec integration tests and Capybara

Unit and Functional Tests are as Useful as 100% Code Coverage

Detect emerging problems in your codebase with. We’ll deliver solutions for fixing them, and demonstrate techniques for building a Ruby on Rails application that will be fun to work on for years to come.

Grab a free sample of Ruby Science today!

Recipe: Google Calendar

A recipe for accessing Google Calendar data from Ruby.

Why?

Google Calendar is a great interface for a few people to share management of events. You might have a client that has this need. Neither you nor the client want to spend time or money duplicating an ‘admin interface’ for managing events. You want to focus development time on displaying those events in a custom way.

Ingredients

• icalendar gem
• open-uri from the standard library

Google Calendar

For a Google Calendar you own, navigate to the “Calendar Details” page:

Your calendar has an address and can be accessed as XML/RSS, iCalendar, or HTML.

A good example of the Google Calendar embed option is Betahouse’s calendar.

iCalendar

For this recipe, we’ll use the iCalendar format. I tried GET’ing the XML version and parsing it with Nokogiri but found the iCalendar version more manageable.

Copy the “ICAL” button’s value. Save it in a comment in your code for now. Also download it. We’ll use it for our spec:

describe Tour do
  before do
    ics   = File.join(File.dirname(__FILE__), 'local_copy.ics')
    @tour = Tour.new(ics)
  end

  it "should find upcoming gigs" do
    @tour.upcoming_gigs.all? { |gig| gig.dtstart.should > DateTime.now }
  end
end

Make it go:

require 'open-uri'
class Tour
  GOOGLE_ICS = "http://google.com/calendar/ical/you@gmail.com/public/basic.ics"

  attr_accessor :cal

  def initialize(ics = GOOGLE_ICS)
    self.cal = Icalendar.parse(open(ics).read).first
  rescue *HTTP_ERRORS => error
    HoptoadNotifier.notify(error)
  end

  def upcoming_gigs
    cal.events.select  { |event| event.dtstart > DateTime.now }.
               sort_by { |event| event.dtstart }
  end
end

The default behavior uses the remote Google ics file, but we set up a constructor to allow us to easily replace the file in our specs.

The rescue is optional. HTTP_ERRORS is an Array from Suspenders I use in these circumstances in combination with Hoptoad to be notified if the HTTP calls to a remote service stop working for some reason.

If you wanted to get really fancy, you could have a nightly cron job that downloads a new copy of the .ics file and runs the spec on CI.

Example web app

I happened to be doing this in order to style the calendar nicely in a web app. He’s my Sinatra route…

get '/tour' do
  erb :tour, :locals => { :gigs => Tour.new.upcoming_gigs }
end

.. and the relevant portion of the view:

<ul class="gigs">
  <% gigs.each do |gig| %>
    <li>
      <%= gig.dtstart.strftime("%B %d, %Y %I:%M %p") %>
      <a href="http://maps.google.com/maps?hl=en&q=<%= gig.location %>"><%= gig.summary %></a>
    </li>
  <% end %>
</ul>

Check out the live example.

Bon appétit!

Clearance: Rails authentication with email and password

Authentication is a common pattern in Rails apps. Thus, there have been many authentication plugins. We’ve tried acts_as_authenticated and restful_authentication over the years.

We found that user authentication is hard to generalize. Most abstracted authentication plugins had both too much and too little for us.

We then tried writing authentication from scratch on our clients’ Rails apps for about a year. We felt better about test coverage but it was still a pain to re-write similar code. App after app, we talked about extracting common code into a library. Each time we resisted.

After a while, we thought that maybe 60% of authentication could be re-used. We extracted Hoptoad’s authentication, then merged code from two of our clients’ apps. We named the gem Clearance.

On the first attempt, we went overboard on re-use. We backed off and wrote hooks in places we were finding logical extension points. For the past few months, patches have trickled in from Github and we’ve carefully included code that fits in the “60%”.

We recently started a new project. In the process, we’ve polished the gem and are happy to announce its official release.

Clearance

• Sign up
• Confirm email
• Sign in
• Sign out
• Reset password

Get it on Github.

Modules, Shoulda, and Factory Girl

Clearance is focused on maintainability of your application’s authentication code.

• Include comprehensive Shoulda and Factory Girl tests in your Rails app’s test suite
• Encapsulate authentication logic in modules which are included in your controllers, models, and tests.

This approach keeps your Rails application’s code clean and alerts you if you ever break your authentication code.

Due to the work we’ve been doing to make Shoulda test framework-agnostic, you will be able to use RSpec in the 0.5.0 release of Clearance.

Test::Unit and Cucumber features are also supported:

script/generate clearance
script/generate clearance_features

Conventions

To keep our approach simple, we made a series of design decisions:

• User model required.
• User model uses attr_accessible.
• Authenticate by email (not username) and password.
• Vocabulary restricted to a trinity: “sign up”, “sign in”, “sign out”

Beyond

Clearance does not try to be a Swiss Army knife but it does have some hooks if you want admin roles, sign up and sign in by username in addition to email, or something else.

Please report bugs and request features on GitHub Issues.

Written by Dan Croak.

Speculating with Shoulda

Shoulda used RSpec?

Shoulda’s users have long enjoyed the brevity and simple, declaritive nature of macros. These test-generating methods cut the most common ActiveRecord and ActionPack tests down to one beautiful, readable line. However, it doesn’t seem fair in this time of unity to leave our RSpec brothers and sisters out in the cold. If you like RSpec and Shoulda, but would just as soon never use the word “Test::Unit::TestCase” again, you have some good news in store.

Shoulda’s ActiveRecord macros have been rewritten to use RSpec-like matcher classes under the hood. That means that, providing you’re using at least version 1.1.12 of RSpec, you can write model specs like this:

describe User do
  it { should belong_to(:account) }
  it { should have_many(:posts) }
  it { should validate_presence_of(:email) }
  it { should allow_value("test@example.com").for(:email) }
  it { should_not allow_value("test").for(:email) }
end

You can see more examples in the Shoulda rdoc. We’ve also added a dash of detection so that RSpec users can just require ‘shoulda’ and be on their way – the ActiveRecord matchers will be mixed into your model examples automatically.

The ActionPack macros haven’t been converted yet, but that process is already under way, so stay tuned for those. By Shoulda 3.0, we plan to have every macro in Shoulda to RSpec users.

For all your loyal Test::Unit users out there, you can keep using the same syntax you’ve always used:

class UserTest < ActiveRecord::TestCase
  should_belong_to :account
  should_have_many :posts
  should_validate_presence_of :email
  should_allow_values_for :email, "test@example.com"
  should_not_allow_values_for :email, "test"
end

Whether you like to TDD, BDD, test, or spec, Shoulda macros are available for a framework near you!

Thanks go out to David Chelimsky for helping to make integration with RSpec a possibility.

Update: if you’re having issues with undefined methods when using Shoulda with RSpec via config.gem, try updating to Shoulda 2.9.1.

Consistent Naming

Those of you familiar with Shoulda may have noticed the new names in the examples above. If you’ve ever had to dive into the Shoulda documentation to figure out if the method you were looking for was “should_require_attributes” or “should_require_presence_of” or “should_need_to_have_a,” the latest version will bring some peace to your mind. Shoulda macros that directly corresponded to an ActiveRecord validation macro have been renamed to follow the fine example set by Rails:

# Before:
should_require_attributes :name
should_require_unique_attributes :email
should_only_allow_numeric_values_for :age
should_require_acceptance_of :terms_of_service

# After:
should_validate_presence_of :name
should_validate_uniqueness_of :email
should_validate_numericality_of :age
should_validate_acceptance_of :terms_of_service

We’ve also renamed should_protect_attributes and added a new macro for consistency:

# Before:
should_protect_attributes :password

# After:
should_allow_mass_assignment_of :name, :email
should_not_allow_mass_assignment_of :password

The old names still work for now, but you’ll see deprecation warnings in your tests.