Screencast: Debugging With Byebug

There are a few different approaches to hunting down bugs.

There’s the change things at random and see what happens approach, which is popular with beginners, but not very effective.

Then there’s puts debugging, where you add code to print things out at certain points, and try to diagnose the problem based on the output. This is a fine approach, despite some annoyances. When you don’t know what the problem is yet, it can be hard to guess what you need to print out. Sometimes you have to dig through lots of unrelated output to find what you’re looking for. It often involves editing lots of different files, maybe even files inside thirdparty gems. And at the end, once you’ve solved the issue, you have to find and remove all the printing code you added.

There’s also raise debugging, which is the same as puts debugging except that you raise exceptions with messages instead of printing output.

In this screencast I want to show you a different, more sophisticated way to debug Ruby code using Byebug.

What is Byebug?

Byebug is not compatible with Ruby 1.9.x or earlier.

Byebug is a debugger for Ruby 2. Debuggers allow you to pause execution at any given line of code, inspect the state of the running app, and run code one line at a time. You can step through code as it runs, observing everything that happens.

I used Byebug to investigate Rails internals for a previous article.

I’ve found that debuggers are good for diagnosing nasty, complicated bugs, and bugs in unfamiliar codebases. For simple problems in your own code, it’s often quicker just to print out a variable or two. But when the problem is deep within a thirdparty gem, and you have no idea what’s happening, a debugger can save you a lot of time and effort.

Installing And Starting Byebug

Byebug is super easy to install. Just add it to your Gemfile, bundle install, and you’re ready to go.

source 'https://rubygems.org'

group :development, :test do
  gem 'byebug'
end

You probably don’t want it available in production, so put it in the :development or :test group. Depending on your setup, you may need to require 'byebug' somewhere as well.

To start the debugger, just call the byebug method from anywhere in your code. It will pause execution of the app, present a prompt like this:

   1: def add(a, b)
   2:   byebug
=> 3:   a + b
   4: end
(byebug) █

Demo: Debugging A Failing Test

This part of the screencast demonstrates:

• Evaluate any Ruby code by typing it straight into the prompt, and the result will be displayed
• next, n – steps over the current line of code (runs the whole current line)
• step, s – steps into the current line of code (runs the current line, stopping inside any called methods)
• continue, c, control-d – exit the debugging prompt, and continue running the code

These are just the basics, and I encourage you to use the help command to look through all the available features.

Links

• Byebug on Github.
• The pry-byebug gem adds Byebug commands to Pry.
• The Debugging Rails Applications Guide includes a section about Byebug.