Debugging Cucumber Tests With Ruby-Debug

Today I ran into a scenario where I needed to step through some ruby code and examine the state of various objects in my rails app. I’ve used the ruby-debug gem a number of times to do exactly this. However, this scenario was being run via cucumber. After some quick googling, I found a number of blog posts saying that you should be able to stick a ‘debugger’ statement anywhere in your code (including your feature step definitions) and it should work. An hour after I started trying, I finally got it working thanks to Tim Tyrrell.

Getting It To Work

Here’s the first things that I did to get ruby-debug to work with cucumber.

# Gemfile
group :development, :test do
  # ... other gems here
  gem 'ruby-debug19'

# features/support/env.rb
require 'ruby-debug'

# features/step_definitions/some_definitions.rb
Then /^I debug$/ do

The first chunk of code in my Gemfile ensures that I have the ruby debugger loaded up. I’ve had this line in my Gemfile for some time now, since I’ve done debugging of my rails apps.

The second chunk of code in the cucumber env.rb file is the magic sauce that I needed to get this working. Once I added that line to this file, I was able to place a ‘debugger’ or ‘breakpoint’ statement anywhere I wanted and ruby-debug attached correctly.

The last chunk should go in some cucumber step definition file. It’s a convenience step that Tim also suggested adding. That way, you can just add “Then I debug” as a step to any cucumber feature file, and step into the code at that point. This is useful when you don’t know exactly where the code is failing and you want to attach the debugger prior to the failing step.

Doing It Right With Bundler’s :require Option

I’m a little surprised that I had to add the require ‘ruby-debug’ to my env.rb file, honestly. Bundler usually handles the ‘require’ for you, when you include a gem … except that the gem is named ‘ruby-debug19′ and the require statement is ‘ruby-debug’, which breaks the convention that bundler uses to do the include.

Fortunately,  we can fix the Gemfile to specify by specifying the :require option.

# Gemfile
group :development, :test do
  # ... other gems here
  gem 'ruby-debug19', :require => 'ruby-debug'

Now that I have my Gemfile properly loading ‘ruby-debug’, I can get rid of the require “ruby-debug” line in my env.rb file. Re-run the cucumber suite, and the debugger attaches correctly.

About Derick Bailey

Derick Bailey is an entrepreneur, problem solver (and creator? :P ), software developer, screecaster, writer, blogger, speaker and technology leader in central Texas (north of Austin). He runs - the amazingly awesome podcast audio hosting service that everyone should be using, and where he throws down the JavaScript gauntlets to get you up to speed. He has been a professional software developer since the late 90's, and has been writing code since the late 80's. Find me on twitter: @derickbailey, @mutedsolutions, @backbonejsclass Find me on the web: SignalLeaf, WatchMeCode, Kendo UI blog, MarionetteJS, My Github profile, On Google+.
This entry was posted in Cucumber, Debugging, Ruby. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • if all you need is an irb(ish) console within your cucumber environment you could alternatively use pry (

    In both cases make sure you disable environment preloaders like spork.

  • Anonymous

    Worked like a charm! Thanks for the post.

  • Anonymous

    Worked like a charm! Thanks for the post.

  • great information you write it very clean. I am very lucky to get this tips from you.

  • Very useful information about Remove Blue Shadows from
    Desktop Icons is provided by this blog and i like to visit such blog which
    always provides new things to learn.

  • l3x

    Thanks for the writeup! You may want to check out JazzHands. It comes bundled with Hirb, Pry Rails, Pry Debugger, etc.:

  • Sandra

    hi. Thank for the article.
    But when i did this step and run the feature i had the error:
    INTERNAL ERROR!!! undefined method `line_at’ for Debugger:Module
    /home/alex/.rvm/gems/ruby-1.9.3-p374@blog/gems/ruby-debug19-0.11.6/cli/ruby-debug/processor.rb:99:in `print_location_and_text’
    Can u help me?