Cucumber Tip: IRB From Inside a Step Definition

Most Ruby programmers know about Ruby’s interactive console, IRB. (If you don’t, stop right here, open up a command window and run irb. Type some Ruby code. See how it returns the result of each line right away.) IRB is great for poking around with unfamiliar libraries.

Suppose you’re using Capybara with Cucumber for the first time. It would be nice to use IRB to experiment with what Capybara can do on a particular page. You could launch an IRB session and duplicate all the Capybara setup from your Cucumber support/env.rb file. But wouldn’t it be nice if you could just fire up IRB in the context of a step definition so you know everything in your IRB session matches what you’d get in the step def? Turns out you can. Here’s how…

Install the ruby-debug gem. If you’re using Ruby 1.9 like me, you need the ruby-debug19 gem. In Rails 3, just add gem ruby-debug19 to your Gemfile, probably in the test group, and run bundle install.

Require ruby-debug in support/env.rb.

Add breakpoint where you want to jump into IRB. For example:

Given /^I am on the advanced search page$/ do
visit 'http://'

(Note the extra line after breakpoint with 0 on it. breakpoint breaks before executing the next line, so if it’s the last thing in a block, you won’t jump into the debugger in the context you expect; 0 is a dummy line to keep us in the right context.)

Run Cucumber like normal. When it reaches breakpoint, ruby-debug will take over, and you’ll see a prompt like this: (rdb:1).

You can do a lot of different things at this prompt, but we only care about one right now: type irb and hit Enter. Now you should see a an IRB prompt. You’re in the context of a Cucumber step definition. Type self and hit Enter. You’ll see that self is an instance of Cucumber’s World with various things mixed in. From here, you can do anything you would do inside that step definition.

When you’re done, run quit to get out of IRB and continue to get out of the debugger. Cucumber execution will continue like normal. Keep in mind, though, that if you change the state of your system from IRB, you might not get the test results you expect.

Enhancements and variations for you to explore:

  • Make IRB nicer to use with gems such as irbtools
  • Create a step definition just for launching the debugger
  • Create a tagged scenario just for launching the debugger

Related Articles


  1. This is an excellent tip! I’ve always had difficulty writing cucumber tests because I couldn’t recreate the scenarios easily in irb. Thanks a lot!

  2. Hi,

    ruby 2.3.1p112 (2016-04-26 revision 54768) [x64-mingw32]

    Any idea what I could do for having it installed?

    Failing for me when trying to install ‘ruby-debug19′:

    C:\Users\SUPJosec>gem install ruby-debug19
    Fetching: archive-tar-minitar-0.5.2.gem (100%)
    Successfully installed archive-tar-minitar-0.5.2
    Fetching: ruby_core_source-0.1.5.gem (100%)
    Successfully installed ruby_core_source-0.1.5
    Fetching: linecache19-0.5.12.gem (100%)
    Temporarily enhancing PATH to include DevKit…
    Building native extensions. This could take a while…
    ERROR: Error installing ruby-debug19:
    ERROR: Failed to build gem native extension.

    current directory: C:/Ruby23-x64/lib/ruby/gems/2.3.0/gems/linecache19-0.5.12/ext/trace_nums
    C:/Ruby23-x64/bin/ruby.exe -r ./siteconf20161130-11928-1dm9odz.rb extconf.rb
    checking for vm_core.h… no
    *** extconf.rb failed ***
    Could not create Makefile due to some reason, probably lack of necessary
    libraries and/or headers. Check the mkmf.log file for more details. You may
    need configuration options.

    Provided configuration options:
    C:/Ruby23-x64/lib/ruby/gems/2.3.0/gems/ruby_core_source-0.1.5/lib/ruby_core_source.rb:39:in `create_makefile_with_core’: uninitialized constant Ruby_core_sourc
    ::Config (NameError)
    Did you mean? RbConfig
    from extconf.rb:19:in `’

    To see why this extension failed to compile, please check the mkmf.log which can be found here:


    extconf failed, exit code 1

    Gem files will remain installed in C:/Ruby23-x64/lib/ruby/gems/2.3.0/gems/linecache19-0.5.12 for inspection.
    Results logged to C:/Ruby23-x64/lib/ruby/gems/2.3.0/extensions/x64-mingw32/2.3.0/linecache19-0.5.12/gem_make.out

    1. Hi Michael,

      It’s been several years since I’ve tried to do this, so I can’t provide much help. A couple alternatives:

      The advice from an earlier commenter to try Pry seems good. That’s probably what I’d do today.

      You could also reach out to the cukes Google Group to find out how people do this sort of thing today.

      Hope that helps,