Interactive debug sessions in RSpec with Capybara

Jumping right into your feature specs

Tom Dracz
3 min readApr 11, 2018

In Rails, I like to replicate the conditions of the user clicking through and interacting with the website through the RSpec feature specs. Modern websites more often than not mean Javascript-enabled functionality which adds further complexity to already non-trivial task.

This is where I rely on capybara gem coupled with headless Chrome browser to achieve the required functionality. Great tools, navigating through the pages in an automated test is a breeze with the clear DSL, all is dandy.

Then you write a feature spec to test that brand new super cool thing on your website:

And it fails. Maybe the link to click cannot be found. Maybe it’s that the modal that should open is not opening. Maybe it’s something else altogether.

Debugging that can be a pain. Trial and error is one way to do it, capybara and friends also come with few tools and tricks to help you figure out what the test is “seeing”. But sometimes that’s not enough. Quite often it would be quite good to jump into the test environment and actually start clicking around the website to figure out the issues. If only there was a way…

Enter interactive debug session! ✨ 🚀

This simple snippet has been used across many of my projects. It’s not a silver bullet as it’s reliant on things like Devise for authentication but it can be a good starting point for implementing something similar.

What it does is simply:

  • log in the user if needed to access an authenticated resource
  • grab the current URL to access and use launchy gem to open it in a new browser window to get into the server session spun up by feature spec
  • stop the execution using pry to keep the server running and be able to navigate through pages (plus actually use pry to call the test methods to debug results of various calls)

To use it (after loading it in RSpec), in a test just drop the method where needed:

The above will open a new browser window at admin_messages_path, already logged in as a created admin user. From there, you can click around, inspect HTML source and hunt down that pesky bug. Ace!


The interactive debug sessions snippet works for me, but your mileage may vary. Some things I’ve encountered while getting this to work:

  • The test server instance was not responding, as the threads were being blocked. This has been the problem when using byebug instead of pry
  • Database connections are finicky and you might need to use the well-known hack for everything to work. If using system tests in Rails 5.1 (and recently supported in RSpec), those issues should be less prevalent

As mentioned above, it’s not a silver bullet, it’s heavily dependant on my preferred setup, but it should be enough of a starting point of figuring out a suitable solution for yourself!

Got any good Rails testing tricks and snippets? TDD secret weapons? Let me know!



Tom Dracz

Expatriate culture vulture with an unhealthy love of Cyrillic, cats and loose leaf tea. Also a web developer