Active Explorer gem - easier Ruby on Rails debugging

Let me introduce to you our new Ruby gem that I have been working on recently.

It is called Active Explorer https://github.com/rascasone/active_explorer.

It works like “awesome_print with associations” (in console mode) and like “railroady for runtime data” (in image graph version).

It prints your object data with all associated object in a nice way and with one command. It “explores” your object and its surroundings.

In this blog I will discuss following topics:

• what the gem does
• why did I created it
• how to use it
• future plans

TL; DR

In case you don’t have time to read it all:

1. Add this to your Gemfile.

 gem `active_explorer`

2. Set a breakpoint and when the program stop, try this in console:

 # Console output ex my_object

 # Image output (install GraphViz software first) exf my_object

3. See what happens ;)

Find more examples and complete guide on Github: https://github.com/rascasone/active_explorer

What does it do?

The gem prints out attributes of your object and of all objects associated with itby `has_many` or `belongs_to`. It prints the output:

• either to console (like awesome_print)
• to an image file (like railroady)

It works only with model objects — i.e. instances of Active Record.

Why did I created it?

When project gets to a certain size I sometimes encounter situations when I am a little bit lost during debugging. I am inspecting many objects that are connected by associations, using several breakpoints. And I need to quickly explore the data — see values of objects and connections to other objects.

For example on our recent project we are working with these classes that describe flow of Customer interactions with Emails and Web forms.

 # Customer is someone either addressed by email or a visitor on a web page class Customer < ActiveRecord::Base has_many :greetings has_many :requests end

 # Greeting email is received by Customer and might lead to Request class Greeting < ActiveRecord::Base belongs_to :customer has_many :requests, through: greeting_to_request end

 # Association Model that connects Greeting and Request class GreetingToRequest < ActiveRecord::Base belongs_to :greeting belongs_to :request end

 # Request is created by Customer (either directly through web page or based on Greeting email) class Request < ActiveRecord::Base belongs_to :customer has_many :greetings, through: greeting_to_request has_many :offers end

 # Offer is created in response to Request and consists of several Calculations class Offer < ActiveRecord::Base belongs_to :request has_many :calculations end

 # Calculation is a part of Offer class Calculation < ActiveRecord::Base belongs_to :offer has_many :orders end

 # Order is created by Customer based on Calculation class Order < ActiveRecord::Base belongs_to :offer has_many :calculations end

You see that there are many associations and they go deeper and deeper. At several moments when I was examining creation of Calculations I wanted to see what associations to other objects it has. And what the data (attributes) of all the objects look like.

For example I wanted to know about Calculation:

• what Request it came from
• what Customer was associated with it
• whether that Request originated from a Greeting
• what Orders were created based on it

I needed to do:

 calculation.offer.request calculation.offer.request.customer calculation.offer.request.greetings calculation.orders

A lot of typing. Of course, some things like getting a `customer` can be handled by delegation. Also, in Console, you can easily repeat last commands. But all this adds up and when I repeated it several times I really wished to have it all in one command and in a clear view.

Now I can do the same with just one command:

 ex calculation

And that is just great ;)

I am not saying that you would use it every day or as much as you use Awesome Print’s `ap` but it is a nice feature to have. I use it from time to time when I want to "explore surroundings" of my object and be sure "where I am".

Also, It comes handy when you want to discuss something with your colleague and want to have a clear view of the situation. Now `exf` comes to play.

How to use it

First of all, you need to use it only with Active Record objects. You have two options how to use the gem.

• Console output
• Image output (using GraphViz library)

Console output

The Console output just uses IRB to display the output.

Command:

 ex <your_object>

Example output:

 ex calculation

 # => Console output: 

 Calculation(1232) {:offer_id=>554142781, :company_id=>7} -> belongs to Offer(554142781) {:request_id=>980190974, :created_at=>Wed, 22 Jun 2016 14:36:57 CEST +02:00} -> belongs to Request(980190974) {:car_cylinder_capacity=>1500, :car_performance=>160} -> belongs to Customer(980190974) {:name=>"Marry", :surname=>"Helpful"} -> belongs to ZipCode(7828) {:zip_code=>"51101", :city_id=>97942}

Image output

Image output generates a graph of connected objects using the GraphViz software (here is how to install it) and saves it to a file.

Command:

 exf <your_object>

Example output:

The file is by default saved in your root.

Plans

Community

First of all I would like to get this gem to community so that it can be thoroughly tested and new ideas can appear. Please if you like or dislike the gem or have suggestions get in touch with me.

Bug hunt

I know about some minor bugs so the bug hunt is necessity. I would also really like to support older versions of Ruby on Rails. Currently the gem works only for version 4.2. I would like to support all 4.x version and soon-to-be released version 5.

Enhancements

I want to make the output nicer and more usable:

• colorize
• interactive graph
• export to other formats? (SVG)
• export to online service for sharing possibility? (yuml.me)

Gem creation hints

If you are thinking about creating your own gem — do it. To finish some library and tune it out will help you to be better at coding and you can also help others = Karma!!! ;)

And here is short list of “How to create new gem” guides:

• https://www.sitepoint.com/creating-your-first-gem
• http://stackoverflow.com/questions/2194547/ruby-how-to-write-a-gem

To see my problems and solutions during gem development (and some tips) visit my post Gem development — troubles and solutions.

Thanks for reading.

What is your opinion about the gem? Please leave a comment. Thanks!