Customizing RSpec

Nick Sieger — Tue, 02 Jan 2007 05:32:00 +0000

Update/Disclaimer: I refer to parts of RSpec that are not blessed as an extension API. Redefining before_context_eval and using the @context_eval_module variable directly may change in the future. I’ll keep this article updated to coincide with the changes. For now, these techniques should work fine with RSpec versions up to 0.7.5.

RSpec seems to be getting more attention lately as a viable, nay, preferred, alternative to Test::Unit. It’s possible that it’s just my personal feed-reader-echo-chamber, but consider this: Rubinius has started using RSpec alongside Test::Unit as an another way to test the alternate Ruby implementation. They’re even in the midst of building some snazzy extensions to allow the same specs to be run under a Ruby implementation of your choice. (Perhaps this will point the way to a new round of executable specs to accompany the fledgling community spec? Let’s wait and see how they do and leave that topic for another day.)

But extending and customizing RSpec to add a DSL on top of RSpec’s context/specify framework doesn’t have to be the realm of experts. Here are some templates for how you can DRY up your specs by adding your own helper methods in such a way that they will be available to all your specs. But first, a little background.

Spec Helper

Most usages of RSpec that I’ve seen in the wild use a “spec helper” (spec_helper.rb). This file, following the pattern of Rails’ test_helper.rb, minimally contains require statements to pull in the RSpec code and any supporting code for running specs. By requiring the spec helper via a path relative to your spec (usually with require File.dirname(__FILE__) + '/spec_helper' or similar), it also allows you the convenience of running your specs one at a time from anywhere (say, by launching from your editor) or with rake or spec. This file is where your shared helper methods will go, and where they’ll get registered to be pulled into the contexts.

What Context in `context`?

context "A new stack" do
  # <== What is the value of "self" here?
  specify "should be empty" do
  end
end

How do those contexts work anyway? The context method that defines a context in which specs can be defined and run takes a block to define the individual specs, but what can really go in that block?

It turns out that RSpec jumps through metaprogramming hoops (using class_eval) to make the block behave like a class definition. This means you can do things like put method definitions inside your context:

context "A new stack" do
  def a_new_stack
    Stack.new
  end
  specify "should be empty" do
    a_new_stack.should_be_empty
  end
end

Which is nice, but the reason we’re here is to hide that away in spec_helper.rb. So, to get back to the point of the comment in the first example above, the self inside the context block is an anonymous Module object. It’s constructed in the initialize method of a Context (condensed from spec/runner/context.rb in the RSpec codebase):

class Spec::Runner::Context
  def initialize(name, &context_block)
    @name = name

    @context_eval_module = Module.new
    @context_eval_module.extend ContextEval::ModuleMethods
    @context_eval_module.include ContextEval::InstanceMethods
    before_context_eval
    @context_eval_module.class_eval(&context_block)
  end

  def before_context_eval
  end
end

(Take note of that empty before_context_eval method and the fact that it’s invoked during context initialization; that’s where we can plug in our custom extensions.)

The object held by the @context_eval_module instance variable is being augmented in two ways: extension and inclusion. The object is extended with the ContextEval::ModuleMethods module; these methods are being added to the object’s singleton class. This has the effect of making these methods visible within the context block, functioning similar to “class” methods.

The object also has the ContextEval::InstanceMethods module included. This has the effect of adding these as instance methods, making them visible from within specify blocks, which are made to behave like instance methods on the same object.

Putting it together

Technique	Visibility	Use
@context_eval_module.extend	Context block	Custom setup, shared state declaration
@context_eval_module.include	Specify block	Shared actions/functions, stub/expectation modification, encapsulate instance variables

Adding specialized setup methods

spec_helper.rb snippet:

module SharedSetupMethods
  def setup_new_stack
    setup do
      @stack = Stack.new
    end
  end
end

class Spec::Runner::Context
  def before_context_eval
    @context_eval_module.extend SharedSetupMethods
  end
end

Example spec:

context "A new stack" do
  setup_new_stack

  specify "should be empty" do
    @stack.should_be_empty
  end
end

Adding shared accessors

spec_helper.rb snippet:

module StackMethods
  attr_accessor :stack

  def push_an_object
    stack << mock("some object")
  end
end

class Spec::Runner::Context
  def before_context_eval
    @context_eval_module.include StackMethods
  end
end

Example spec:

context "A stack with an object pushed" do
  setup do
    @stack = Stack.new
  end

  specify "should not be empty" do
    stack.should_be_empty
    push_an_object
    stack.should_not_be_empty
  end
end

The examples are simple, but hopefully illustrate the techniques. For an example of some code that’s actually useful, check out my sample RSpec Selenium RC integration project, in particular the spec helper and the example spec. (More on this in the future if it proves useful, but for now if you check it out and run rake on it, it should launch Selenium RC and run the example spec in a Firefox browser.)

By mixing and matching these techniques, you can layer a mini-DSL on top of RSpec and achieve DRY-er and even more readable and intention-revealing specs. Let me know if you’re able to find uses for these tips!

Metaprogramming Pattern No. 1: Self-specialize

Nick Sieger — Tue, 11 Jul 2006 03:48:00 +0000

One of the biggest aspects of Ruby that I’ve been digging are the metaprogramming facilities, many of which draw from the “code as data” philosophy that comes from Lisp. Metaprogramming has become somewhat of a buzzword in the Ruby community, about as popular as “domain specific language” in terms of its presence in the titles of conference presentations and the like.

So it seems to me that, while a good many smart people are talking and writing about metaprogramming, that we haven’t yet started cataloguing all the different techniques in a shareable way. Is it time to start writing a catalog of metaprogramming patterns? Or do I risk being taken to trial for attempting to unveil the rubyist’s magic tricks?

No, what I am really looking for is the metaprogramming ubiquitous language. Ruby has a lot of language-level features that facilitate metaprogramming, but without a strong jargon to describe what’s going on. Sorry, but module_eval, instance_eval, metaclass vs. singleton class vs. eigenclass, method_missing etc. just don’t cut it. So here’s a first shot at re-invigorating the conversation and taking it to the “HNL” (‘hole nuther level). So herewith begins Metaprogramming Pattern No. 1: Self-specialize.

Why is this one number 1? No reason, pretty arbitrary. I haven’t taken the time to document any more yet. This will be an ongoing project for me.

Self-specialize

You have an algorithm or a “method object” that you wish to make flexible by parameterizing with additional code and/or data that isn’t known at the time you wrote the original class definition.

Therefore, write a method that redefines itself in the singleton class of the currently instantiated object, then re-sends the message to the customized method. In a way, this is simply memoizing the method body itself as a speed-up.

Trivial example:

class Foo
  def initialize(p)
    @prefix = p
  end

  def result(val)
    specialize_result
    result val # send the message again
  end

  private
  def specialize_result
    method_decl = "def result(val); "#{@prefix}: #{val}"; end"
    instance_eval method_decl, "generated code (#{__FILE__}:#{__LINE__})"
  end
end

f = Foo.new("foo")
f.result("hi") # => "foo: hi"
g = Foo.new("bar")
g.result("hi") # => "bar: hi"

Why would you do this rather than writing the logic into the original method? It’s hard to justify use of the technique in the example above. But it could be used to DRY up tedious, redundant code that for performance reasons you would prefer to have inlined rather than invoking an additional instance method.

OK, so honestly I can’t come up with a decent reason to do this yet; I haven’t done enough metaprogramming to have had the need for it. Still, it seems like a nifty enough trick and maybe it will come in handy for you. This does show you just how dynamic Ruby’s method resolution is, that you can suddenly define and call a different method implementation inside of the method itself!

This technique was spotted in the rewritten routes implementation for Rails 1.2 (currently on the trunk) -- see the #write_generate and #write_recognize methods.

Update: Good timing. _why just posted much more succinct description of the same phenomenon, with better examples.

Nick Sieger: Tag metaprogramming