Mike Mayo

Deploying Jekyll sites to Heroku with Rack-Jekyll

2012-02-08T00:00:00-06:00

Note: Check out my article on the Twin Engine Labs engineering blog for some Jekyll highlights and a mini-guide on creating your first blog post.

This will just a quick guide to show how to get your Jekyll site going on Heroku. I’m going to be working off the assumption that you’ve already got a Heroku account setup, so I won’t be going through any of that here.

First you need to install Bundler and add a Gemfile to your project if you don’t already have one. The gem we need is called Rack-Jekyll. It basically just provides a little Rack middleware to serve your statically-generated site to Heroku’s thins. Unfortunately the latest version in Rubygems depends on some very old versions of gems so you’ll need to install from git.

Add the following line to your Gemfile:

gem 'rack-jekyll', :git => 'https://github.com/adaoraul/rack-jekyll.git', :require => 'rack/jekyll'

Next create a file named config.ru in your project, if it doesn’t already exist, add the following to it:

require 'bundler'
Bundler.require(:default, :production)

run Rack::Jekyll.new

The guide on GitHub is different than the above advice, but I kept getting errors when it tried to require ‘rack/jekyll’ until I modified my config.ru to look like this.

Now you should be clear to deploy to Heroku as usual (git push heroku master).

An interesting sidenote

Up until recently I was deploying my site with rack-jekyll version 0.3.5 (current version in RubyGems is 0.3.7). For a long time I was experiencing an issue where any images I uploaded (after switching to this deploy method) had the bottom 10% or so cut off when served from Heroku. At first it was just a single image and I thought it just a fluke (and I hadn’t written a new blog post in a long time), so I didn’t mess with it. But then with my latest blog post I ran into the same issue again.

I finally contacted Heroku support, and after a bit of back-and-forth they determined that Rack-Jekyll was responding with an incorrect Content-Length header. I tried upgrading to 0.3.7 immediately, but the RubyGems version called a whole new slew of headaches, so I gave up and dug into the code. Turned out that the old version was reading in the file, turning the body into a string, calling .length off that string, and passing that as the content length. This is the incorrect way to handle this, and there are a couple of better ways to do it. Since we’re reading the file in anyways, an easy way is just to use file.size. Another option, if you’re using a string, is to call "string".bytesize.

Anyways, I eventually discovered that the version of Rack-Jekyll on GitHub had been updated to current versions of the important gems, and already had the fix in place, so I just switched over to using that instead.

Cool story bro.

How I learned to stop worrying and love REST

2012-02-04T00:00:00-06:00

Buzzwords can be a funny thing. I’ve been writing (what I thought were) ‘RESTful’ web apps and APIs for five years now, and it wasn’t until a couple of weeks ago that I really began to understand what that meant. I’d like to share my ‘AHA’ moment, and give a concrete example of why following the REST style correctly can save you headaches in the long run.

TL;DR: A RESTful API should provide hypertext links to drive traversal through itself, instead of forcing the client to craft their own URIs.

Many have complained about the font on my site, but I personally like it. If you’re having trouble with it though, just click here.

A little backstory

At Twin Engine Labs, we develop iOS apps that are generally backed by Rails REST APIs. We’ve been doing this for a little over a year now, and are constantly refining our process. A few weeks ago I built my first iOS app (which got approved this week) as well as the JSON API backend for it. I take a lot of pride in my code, and I have to say I was quite pleased with how everything turned out. The project felt clean, things were refactored as I felt they needed to be, and nothing was overly complex or ugly. However, at the end of the project lifecycle, I started looking to increase performance by adding basic Rails caching where it was appropriate, and things took an unhappy turn.

At this point, the iOS app was complete and had been submitted to the app store. If you’ve ever gone through this process, you know the delays can be…annoying, and resubmitting is essentially out of the question if you have a deadline to worry about. None of this should have been a problem, since the API was frozen and I was just making internal performance changes, but then I started looking at caching one of the main actions of the application.

It’s a fairly simple index action that returns a list of JSON objects, but the rub comes in that it’s paginated. This action is consumed by a TableView that has infinite scrolling on it, so we only load 25 at a time to make things snappier on the iPhone. We handle all of our pagination using the wonderful will_paginate gem, where page information is passed as query params like: www.myapi.com/index_action?page=1&per_page=25. Unfortunately default Rails page caching doesn’t store query params, so you’ll always cache the first page a user hits. The suggested means of dealing with this is to, instead of using query params, pass your pagination params through the URI, transforming the above example to this: www.myapi.com/index_action/page/1/per_page/25.

This would be trivial to implement on the Rails side, but since my iOS application was crafting these paginated URIs it would mean a change to the iOS code and a resubmission to the app store. The action was fast enough that I moved caching it to a lower priority, but it ate at me that I hadn’t known about the pitfall earlier.

The AHA moment

It wasn’t until several weeks later that I came upon the perfect solution to my problem…at least it would have been had I used it from the beginning as I should have.

I’ve got about a 30 minute bike commute every morning, and I find the best use of that time is to listen to tech podcasts. More specifically I’ve been listening to the Ruby Rogues podcast for the past few weeks; catching up on the backlog as well as keeping up with the latest episodes as they come out. Recently I listened to the REST Done Right episode where they had Steve Klabnik on as a guest panelist. If you follow Steve on twitter or read his blog, you’ll know he’s a big proponent of REST and does a lot to educate developers on its proper usage.

In that podcast they mentioned that one of the core points of REST is that the resources should provide the means to traverse the API. Think of it like links on a webpage; we don’t expect the user to know our URL format and manually type it in when they want to view the next link. Instead we provide them hyperlinks so they can easily traverse our sites. A REST API should function the same way; when you provide someone a list of JSON objects, you should also provide the URI to access each of those objects, or, in the case of my pagination example, the URI to retrieve the next page of results. To quote Roy Fielding:

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. ¹

Steve Klabnik also talks about this very issue in his wonderful article titled Haters gonna HATEOAS. (HATEOAS stands for ‘Hypertext As The Engine Of Application State’ and refers to using hypertext to direct an API consumer through the application). You should definitely read his article to get a great explanation of how it should work and how/why most people aren’t currently doing it.

So while listening to this podcast, somewhere on the bike path between the office and home, it hit me: Instead of crafting the paginated URI in my iOS client, I should have been crafting that URI on the Rails side and sending it through along with my list of JSON objects. I’d actually dealt with this exact format on the iOS side when I was consuming the Facebook search API. Here is an example of how the Facebook Graph API handles pagination:

#http://graph.facebook.com/search?type=Page&q=dcuocentral
{
  "data": [
    {
      "name": "DCUO Central",
      "category": "Website",
      "id": "141968085865824"
    }
  ],
  "paging": {
    "next": "http://graph.facebook.com/search?type=Page&q=dcuocentral&limit=25&offset=25"
  }
}

All you have to do is pluck the paging key out of the JSON and hit that URI for your next page (though they annoyingly provide that URI even if there are no more records to be returned).

By following the REST style, I would have saved myself either A) having to alter my iOS code and resubmit to the store, or B) time spent researching alternate caching methods and implementing them in Rails. As it stands, my partially-RESTful API is going to cost me (and possibly the client) more time before we can call the project finished.

All of that said, I think that Rails does an amazing job of making it easy to implement REST. I’ve been doing a large part of it without even really understanding it. I’m not sure how well it works when you want to go all the way, but that’s something I intend to explore as I learn more about REST and build APIs in the months to come. I’m also eagerly awaiting Steve Klabnik’s book Get Some Rest, which looks to be a great resource on developing RESTful applications in Rails as well as explaining the details of REST in a more approachable way.

Footnotes

REST APIs must be hypertext-driven, Roy Fielding

Rendering a collection of partials with layouts and content_for

2012-02-02T00:00:00-06:00

While working on a Rails project recently, I ran into an interesting dilemma when trying to DRY up a big mess of partials that I had accumulated over several months. Below I’ll describe the scenario and show a way to get around some of the limitations in default Rails partial rendering.

The Problem:

You have several partials in your Rails project that are nearly identical, and you’re sick of all this un-DRY code laying around. Some (or all) of these partials can be loaded multiple times on a single page via a collection of objects. Never fear, Rails has a solution for you (sort of)!

Did you know:

Partials can be rendered with a layout? I know, my mind was blown too! The only caveat I’ve found is that the layout file needs to be in the same directory as the partial, as opposed to the layouts directory, though I’m not sure if this is a hard rule or just the default behavior.

<%= render :partial => 'my_partial_file', :layout => 'my_layout_file' %>

Another fun fact, you can call:

<%= render :partial => 'my_partial_file', :collection => @my_collection_of_objects %>

or if the objects in your collection have a class name that matches your partial name:

<%= render @my_collection_of_objects %>

and Rails will render each of those objects into the partial. Supposedly this is faster than looping over the objects and rendering manually, since Rails only has to lookup the partial once. One downside is that you can’t (as far as I can tell) also pass a layout to this method call.

Anyways on to solving the problem at hand…

The Solution:

The most obvious solution to DRY up similar partials is to use the layout parameter and move all your repetitive markup to a layout view. Sometimes things don’t get to be that simple, though. If, for instance, you want to have a named yield inside your partial layout, you’ll quickly find yourself frustrated. Here’s an example:

# _layout.html.erb
<p id="special_content">
  <%= yield :special_content %>
</p>
<div id="content">
  <%= yield %>
</div>

# _partial.html.erb
<% content_for :special_content, 'This is very special' %>
<p>This is not so special</p>

For some reason, named yields inside partial layouts don’t behave correctly. Instead of your expected output, you’ll end up with:

<p id="special_content">
  <p>This is not so special</p>
</p>
<div id="content">
  <p>This is not so special</p>
</div>

After digging around in the code, I found that you can call content_for in the place of yield with only the name argument and achieve similar results, however this has another issue which will require a little backstory to explain.

The content for views is handled by what Rails calls a ViewFlow. It exposes methods for a content hash, and yield and content_for subsequently use those methods to access and populate the content. However when you access that content, it’s not destructive; it never removes the content from that hash. This causes a problem if you’re using content_for in a loop, because every call you’re just tacking more content onto the same hash key.

What you really need for the above scenario is a way to, when accessing the content from the ViewFlow, remove it from that hash so you have a clean slate on the next iteration. This is actually trivial to accomplish because the ViewFlow, and therefore it’s content hash, are available in the view. Just add a method like this to your ApplicationHelper and use it in place of your normal named yields:

def yield_content!(content_key)
  view_flow.content.delete(content_key)
end

Now when looping through your collection and rendering your partials, your content should render as expected. My next goal is to get layouts behaving with rendering partials using the :collection param, though I think I may have different behavior expectations than the Rails designers do on that topic.

Using Decorators to improve your Inherited Resources experience

2011-12-22T00:00:00-06:00

At Twin Engine Labs we recently discovered the joy that is Jose Valim’s Inherited Resources. For the unfamiliar, it takes all those generic REST actions and views and abstracts them all out for you, so your controllers simply inherit from InheritedResources::Base and you get the basics for free. For us, that means that a large portion of our web app admins are already written for us; we just tweak as needed.

My one real gripe, thus far, has been that the generated views Inherited Resources gives you are just too generic. It defaults to displaying all the attributes for an ActiveRecord resource on the form, show, and index pages, and many of those fields are simply of no use. We use Paperclip for all of our file attachments, which adds 4 database fields to represent each attachment (for an attachment named image you end up with image_file_name, image_content_type, image_file_size, and image_updated_at). None of these fields needs to actually be displayed to the user, nor will the users ever edit them directly.

Then there’s default Rails fields like created_at and updated_at, plus all your foreign keys for belongs_to associations. While you may want to display the date fields, you generally don’t want those editable by a user, and I’d rather show the belongs_to association directly than the foreign key. On top of this, we use Formtastic for generating forms, so if I could build a more reliable list of attributes and associations that were editable by a user, I could just hand them off to semantic_form_for and let it works its magic.

Enter the Decorator pattern. By creating a generic decorator to wrap my ActiveRecord resource_classes, I could use Rails’ magic to get a more refined list, then just use that decorator in all the Inherited Resources views. My base Decorator looks like this:

module InheritedResources
  class Decorator
  
    def initialize(klass)
      @klass = klass
    end
  
    def form_attributes
      edit_attrs = editable_attributes.reject {|a| a.to_s =~ /created_at|updated_at/}
      edit_attrs + belongs_to_associations.map(&:name) + paperclip_attachments
    end
  
    def show_attributes
      editable_attributes
    end
  
    def index_attributes
      editable_attributes
    end

    def editable_attributes
      assocs = belongs_to_associations
      attach = paperclip_attachments
      regex = "^id$"
      regex << ('|' + assocs.map(&:foreign_key).join('|')) unless assocs.blank?
      regex << ('|' + attach_attachments.join('|')) unless attach.blank?
      @klass.attribute_names.reject { |an| an =~ /#{regex}/ }.map(&:to_sym)
    end

    def belongs_to_associations
      @klass.reflect_on_all_associations.select { |a| a.macro == :belongs_to }
    end

    def paperclip_attachments
      @klass.attachment_definitions ? @klass.attachment_definitions.keys : []
    end
  
    def method_missing(name, *args)
      @klass.send(name, *args)
    end
  
  end
end

Next I added a helper method to our ResourceController which all of our admin controllers inherit from:

helper_method :decorated_resource_class

def decorated_resource_class
  "InheritedResources::#{resource_class}Decorator".constantize.new(resource_class) 
    rescue InheritedResources::Decorator.new(resource_class)
end

As you’ll notice, I first try to instantiate a resource_class-specific version of the decorator, because I wanted to be able to subclass and override methods as needed. Finally I just went through all the generated resource views and replaced resource_class with decorated_resource_class and used the relevant methods to provide the attributes I wanted (e.g: #form_attributes in _form.html.erb, #show_attributes in show.html.erb, etc…).

What this means is that, at least for the basic, generic pages, I no longer have to override the provided views to get the desired output. And if I find these sane defaults don’t work, but I don’t need anything really custom, I can just subclass the Decorator for the specific resource_class and override the methods as needed. An example I immediately ran into was our User pages:

module InheritedResources
  class UserDecorator < Decorator
    
    def index_attributes
      [:first_name, :last_name, :email, :current_city]
    end
    
    def show_attributes
      index_attributes + [... some more attributes ...]
    end
    
    def form_attributes
      show_attributes - [... some different attributes ...]
    end
    
  end
end

Of course, this won’t cover 100% of the cases, but I found it covers 80% – 90% of the views we use in a standard admin. The rest are so customized that over-riding the views is the only option anyway. I considered gemifying this, or making it a pull request for Inherited Resources, but since it’s built around our development environment, I think for now I’ll leave it as is.

Automatically Cached Rake Routes and Annotated Models

2011-12-14T00:00:00-06:00

If you’ve spent any time developing a Rails application, you’re likely familiar with the command rake routes. If you’re not, this little marvel will greatly simplify your dev experience, as it prints out all the available routes in your application and their associated path helpers.

However, as of late it has slowed down considerably. I’m not sure if it was with the changes in Ruby 1.9.2 or Rails 3, but running that command will take a ridiculous amount of time depending on the complexity of your project.

For a base Rails project (I literally just ran rails base_rails):

  $ time rake routes
    /:controller/:action/:id           
    /:controller/:action/:id(.:format) 
  real	0m1.969s
  user	0m1.541s
  sys	0m0.200s

For a moderately-sized Rails project (a client project I’m currently working on):

  $ time rake routes
  ... lots of routes ...
  real	0m29.664s
  user	0m14.373s
  sys	0m2.039s

Nearly 30 seconds just to get a list of the available routes, completely unacceptable.

I set out yesterday with the idea of caching the output of this command in a temporary file, and to print out the cached version as long as the routes file hadn’t been updated since the last cache time. Unfortunately overwriting a Rake task isn’t as easy as it should be, so I accomplished this goal with a simple Ruby script in the project directory:

  #!/usr/bin/env ruby

  routes = ['config/routes.rb'] + Dir['config/routes/*.rb']
  temp_f = 'tmp/routes'
  if (File.exists?(temp_f)) && !routes.any? { |f| File.mtime(f) > File.mtime(temp_f) }
    File.open(temp_f).each_line { |l| puts l }
  else
    require File.expand_path('../config/application', __FILE__)
    load 'Rakefile'
    orig_stdout = $stdout
    $stdout = File.open(temp_f, 'w')
    Rake::Task["routes"].invoke
    $stdout.close
    $stdout = orig_stdout
    File.open(temp_f).each_line { |l| puts l }
  end

While this worked, I hated that I was having to adjust to running a new command, and it meant that, if I added new routes, I was still 30 seconds away from seeing what my path helpers were. The ideal was to have the routes cached automatically as soon as I changed my routes file.

Enter Guard and Guard-Annotate. Guard is a Ruby gem that wraps file observer functionality across all platforms, and Guard-Annotate is a module for Guard that hooks into Annotate. Annotate allows you to add the schema of your models as comments to the bottom of the model file, as well as add the output of rake routes to the bottom of your routes.rb.

With those 2 gems, I could just create a Guardfile in my project directory, and run guard start alongside my Rails server and have all the annotations performed automatically for me. This is a giant step in the right direction, but I also didn’t want to have to run another daemon (as undoubtedly I’d forget to run it 90% of the time).

Another issue I ran into: Guard-Annotate was simply shelling out to bundle exec annotate, which in turn was shelling out to rake routes for the routes portion of the annotation. This meant that I was still 30 seconds away from savings my routes.rb and seeing the updated annotations. Plus there was really no need to load the entire Rails stack again (via Rake) when this is all happening in the context of a running Rails app.

My solution came in a few steps:

Run Guard.start(:notify => true) in a thread that I spawn inside development.rb. That way Guard is run automatically when I launch my server in the dev environment.
I decided to cache the routes to a tempfile instead of annotating routes.rb since it can get fairly lengthy and most of the devs I work with are used to using rake routes anyways.
Create my own Guard extensions to handle Route caching. I ripped out all the code from the rake routes task and included it in the extension so no more loading another environment or shelling out unnecessarily.
Create another extension to handle Model annotations (since that was taking > 15 seconds as well due to shelling out to annotate).
Hack my Rakefile to bypass loading the environment if my cached routes file exists, and just print out its contents.

The code is a little too long to include here, so instead I’ve provided this pastie with all the relevant bits.

The final outcome: Routes are cached within 0.15 seconds of saving routes.rb, models updated within 0.25 seconds of updating schema.rb, faster than I was able to switch to the relevant file or ALT+Tab to my terminal. And rake routes? See for yourself:

  $ time rake routes
  #== Route Map
  # Generated on 13 Dec 2011 23:59
  #
  ... lots of routes ...
  real	0m0.676s
  user	0m0.249s
  sys	0m0.065s

AutoHyde 0.1.1 Released

2010-12-10T00:00:00-06:00

With the launch of this blog, I’ve recently come to enjoy the wonder that is Jekyll. For those unfamiliar, it’s a dead-simple, blog-aware, static site generator built with Ruby, and is even used by GitHub for their Pages.

My only complaint has been with automating the site regeneration and deployment. I wanted a way to easily integrate it with GitHub’s post-receive hooks so that the site is pulled and regenerated on my server after any code is pushed.

AutoHyde makes that all possible. Once installed, all you need to do is run the executable (with appropriate options) and it will start up a lightweight Sinatra server with a single route, ‘/auto-hyde.’ Then just point your GitHub post-receive hook at http://your-server.com/auto-hyde and you’re ready to go.

Here is a list of the options available from the command-line:

  $ auto-hyde -h
  Usage: auto-hyde [options]
    -e, --email EMAIL     Send email notification of failures to this email address
    -d, --jekyll-dir DIR  Location of your Jekyll project directory, defaults to this dir
    -b, --build-dir DIR   Location Jekyll will build your site to, defaults to './_site'
    -p, --port PORT       Port for Sinatra to run on, defaults to 4567
        --pygments        Turn on Pygment syntax highlighting for Jekyll, defaults to off
    -h, --help            Show this message

The most important options are -j and -b, your Jekyll blog directory and the directory you want the site generated in respectively. When the route is hit, it will cd into your blog dir, git pull, and then use the jekyll command line to regenerate the site.

The gem is already available via Gemcutter/Rubygems, just run:

  $ gem install auto-hyde

If you’re interested, the code is also up on my GitHub repo. I must admit that I haven’t tested the email functionality yet (it uses Pony), as my ISP won’t allow SMTP out. So if anyone notices a bug there, or anywhere else, please let me know.

Node.js: Socket.IO and Buffer quirks

2010-12-09T00:00:00-06:00

As of late, I’ve been bitten by the node.js bug and have become distracted by a side-project with a co-worker. I must admit this is my first time writing any Javascript outside of simple jQuery DOM manipulations, so it has been quite an experience for me.

While my co-worker has written a vast majority of the code, I finally found some free time to dive in, and one of the first things I began playing with was finding a way to stream the output of a unix process to the view. Of course the obvious choice was to use WebSockets and Socket.IO and I quickly found a couple examples that made it look like it wouldn’t be too hard.

In my evening-long codefest, I came across two interesting quirks with Socket.IO/node that took up a majority of my time, and I thought I’d detail them here in case anyone else runs into similar issues:

Node Buffer

We’re currently using a WebWorker object to handle an out-of-request process, the output of which I want to stream to the view. Inside the worker I created some code that looked like the following (just as an initial test for using spawn):

  var my_process = spawn('command/to/run'), var stdout = '', var stderr = '';

  my_process.stdout.on('data', function(data){
    stdout += data;
    console.log(data);
  });

  my_process.stderr.on('data', function(data){
    stderr += data;
    console.log(data);
  });

This isn’t quite exactly what it was doing, but suffice it to say that the output I got wasn’t what I expected; it instead was this:

  console.log('stderr: ' + data); // stderr: Expected output from my command
  
  // Logging the data in the view directly without string concat gave this:
  console.log(data); // { 0: 23, 1: 82:, 3: 15, ... 60: 10, length: 61 }

Needless to say, I was quite confused, until I logged the output on the server side and saw this:

  <Buffer 0a 1b 5b 31 6d 70 72 6f 6a 65 63 74 5f 74 65 73 74 1b 5b 32 32 6d 0a>

A short google trip later and I found this in the node.js docs so I updated my code to call data.toString('ascii') and was rewarded with the output I expected.

Socket.IO

The next time-consuming bug came when trying to stream the output from the process to the view. The build worker that handles running the process passes the output back to the controller, which then broadcasts it via the socket to the clients. My initial code looked something along these lines:

  socket.broadcast({
    'stdout': message.data.stdout, 
    'stderr': message.data.stderr
  });

However, I was unable to call stdout or stderr off the object passed in the broadcast, and when I logged to the browser console I found this odd output:

  ~j~{'stdout':'This would be stdout output.','stderr':null}

At first glance I was confused, it looked like a JSON object or an object literal, but I had no access to any of the keys inside. I thought to myself “The secret must lie in the ‘~j~’ at the beginning,” but Google returned no relevant results regarding that. Eventually, after reading several other examples, I found a simple solution:

  // Server-side
  socket.broadcast(JSON.stringify({
    'stdout': message.data.stdout, 
    'stderr': message.data.stderr
  }));
  
  //Client-side
  socket.on('message', function(msg){
    var data = JSON.parse(msg);
  });

By doing this, I was able to access stdout and stderr off the data variable. I’m still uncertain what the object originally being passed to the view was, as it was neither JSON nor an object literal, but the solution got me where I needed to be. If anyone can explain it further, please do so; I’d love to know what’s going on behind the scenes here.

I think it highly likely that I’ve made some rookie mistakes here, but, as I stated before, I’m very new to Javascript so much of this is foreign to me. I’m still trying to get past the Ruby/OO mindset and to wrap my brain around the JS way of doing things, but I’m getting there. I’ll soon be reading Javascript: The Good Parts, which I hope will get me over some of these newbie difficulties I’m running into. If you have any tips or suggestions, or if you can point me towards any good guides on the subject, I’d love to hear from you.

MiniTest Events

2010-12-05T00:00:00-06:00

A few weeks ago I made a hack to MiniTest to add Fuubar-like functionality. Unfortunately the hack was a little dirty, and I wanted to make MiniTest more extendable, at least for reporting purposes. My solution was to borrow from the Events system I wrote for Harbor (a web framework we wrote and use at Wieck Media).

The concept is very simple; you just raise an event wherever you feel you need to, and pass in a context object of some kind. Then you register an event handler, which is just a class with a call method that is executed at the time of the event raise.

For example, here I am raising an event just before all of the tests begin to run:

  event = RunAnythingEvent.new(self, type, suites, options)
  
  raise_event(:run_anything_start, event)

As you can see it’s using a special RunAnythingEvent context object, whose definition looks like so:

  class RunAnythingEvent < BaseEvent
    
    attr_reader :runner, :type, :output, :suites, :options
    attr_accessor :test_count, :assertion_count, :report, :failures, :errors, :skips
    
    def initialize(runner, type, suites, options)
      super()
      @runner = runner
      @output = runner.output
      @suites = suites
      @type = type
      @options = options
    end
    
  end

And here is an example of an event handler for this event:

  class RunAnythingStartHandler
  
    def initialize(event)
      @event = event
      @output = event.output
      @type = event.type
    end
  
    def call
      @output.puts
      @output.puts "# Running #{@type}s:"
      @output.puts
    end
  
  end

Which is registered by calling the following method off the class where the event was raised:

  register_event_handler(:run_anything_start, RunAnythingStartHandler)

This particular example illustrates an important part of my goal. I wanted to decouple the reporting of the tests from the actual tests themselves. In order to further this I have created plugins that enable and disable the required event handlers which deal with outputting results in specific ways. I have also moved all the base reporting into a plugin (MiniTest::Reporting) which is enabled by default.

The next step, which I’ve already partially completed, is to create plugins that handle alternative output options like the progress bar and instafailing. If you’re interested, the work is being done in the events branch on my Github account. Assuming Node.js doesn’t monopolize all my time, I hope to have it completed in the near future. If you have any ideas, feel free to let me know.

MiniTest ProgressBar

2010-11-19T00:00:00-06:00

I was recently inspired by a blog post I read about a new Ruby gem called Fuubar. The premise of this gem is to have your RSpec tests instafail, giving an immediate backtrace when a test fails or errors; that way you don’t have to wait for all of your tests to complete before researching a problem. It also makes use of one of my favorite gems, ProgressBar, to replace that boring standard test output of periods and letters with a progress bar. To top it off, the output color shifts as your tests fail/error (red) or are skipped (yellow), or remains green if they all pass. I find this test reporting to be much more informative and useful, but unfortunately we don’t use RSpec (actually it was written on RSpec 2), so if I wanted this I was going to have to come up with my own solution.

We’ve actually only recently started really trying to integrate testing into our projects, and we’ve chosen to use MiniTest. After upgrading to the latest version (2.0.0), I had high hopes that I could just mimic the behavior of the Pride extension, replace the default MiniTest::Unit.output with my own MiniTest::ProgressBar object that would convert the lovely periods and letters into the colored progress bar I longed for. Unfortunately I quickly discovered that MiniTest doesn’t expose any of the import things I needed, like a total count of tests being run.

I decided to start with a proof-of-concept (read: dirty override hack) just to be sure I could get the output I wanted from MiniTest. What I ended up with looked something like this:

        require "minitest/unit"
        require 'progressbar'

        class MiniTest::Unit

          COLORS = { :green =>  "\e[32m", :yellow => "\e[33m", :red => "\e[31m", :white => "\e[37m" }
          @@state = nil

          def _run_suites suites, type
            @@report_count = 0
            filter = options[:filter] || '/./'
            filter = Regexp.new $1 if filter =~ /\/(.*)\//

            self.class.progress_bar = ProgressBar.new(type.to_s.capitalize, suites.inject(0) { |i, suite| i += suite.send("#{type}_methods").grep(filter).size })
            suites.map { |suite| _run_suite suite, type }
          end

          def _run_suite(suite, type)
            header = "#{type}_suite_header"
            puts send(header, suite) if respond_to? header

            filter = options[:filter] || '/./'
            filter = Regexp.new $1 if filter =~ /\/(.*)\//

            methods = suite.send("#{type}_methods").grep(filter)

            assertions = methods.map { |method|
              inst = suite.new method
              inst._assertions = 0

              start_time = Time.now
              result = inst.run self
              time = Time.now - start_time

              print "#{suite}##{method} = %.2f s = " % time if @verbose
              print result
              puts if @verbose

              inst._assertions
            }

            return assertions.size, assertions.inject(0) { |sum, n| sum + n }
          end

          def print *a # :nodoc:
            case a
            when ["."] then
              # do nothing
            when ["E"] then
              current_state = "error"
              @@state = :red
            when ["F"] then
              current_state = "fail"
              @@state = :red
            when ["S"] then
              current_state = "skip"
              @@state ||= :yellow
            else
              # nothing
            end
            if report = @report.pop
              @@report_count += 1
              self.send("print_#{current_state}", report)
            end
            output.print COLORS[state]
            progress_bar.inc
            output.print COLORS[:white]
          end

          def state
            @@state || :green
          end

          def progress_bar
            self.class.progress_bar
          end

          def self.progress_bar
            @@progress_bar ||= ProgressBar.new("Tests")
          end

          def self.progress_bar=(bar)
            @@progress_bar = bar
          end

          private

          def print_skip(report)
            output.print COLORS[:yellow]
            print_report(report)
          end

          def print_fail(report)
            output.print COLORS[:red]
            print_report(report)
          end

          def print_error(report)
            output.print COLORS[:red]
            print_report(report)
          end

          def print_report(report)
            output.print "\e[K"
            output.puts
            output.puts "\n%3d) %s" % [@@report_count, report]
            puts
            output.flush
          end

        end

Like I said, it’s dirty, but it works. What I’m left with now is an output from running my tests that looks like this:

I feel satisfied with the output. I have a colorful progress bar as well as instafailing for efficient bug stomping.

All of this work was done in our project as a monkey-patch, but I’ve decided to try and clean this up. So I’ve forked SeattleRB’s MiniTest on my GitHub account, and am currently working to make this change a little cleaner. My intention is to make the test reporting more pluggable using an event system with events being raised upon completion of individual tests, test suites, and the entire test run, that a plugin can then hook into and report in a custom manner. As I progress further, I’ll update here with how things turn out.