xmpfilter: automagic Test::Unit assertions/RSpec expectations and code annotations

Overview

xmpfilter is a small tool*1 that can be used to

• generate Test::Unit assertions and RSpec expectations semi-automatically
• annotate source code with intermediate results (a bit like irb --simple-prompt but only for the lines explicitly marked with # =>) Very useful for example code (such as postings to ruby-talk).

Download

As of 0.4.0, xmpfilter has been included in rcodetools.

The online darcs repository with the development version can be found at http://eigenclass.org/repos/rcodetools .

Usage

xmpfilter takes its input from stdin and writes to stdout. It can run in several modes (annotation, Test::Unit assertion expansion, RSpec expectation generation, marker insertion); see

xmpfilter -h 

README.emacs and README.vim describe how to use xmpfilter from your editor.

Examples

Code annotation

Just add "# =>" markers to the lines whose values you want to be shown:

a = 1
10.times do |i|
  i ** 2                                           # =>
  a += i
end
A = 1
A = 1

will be expanded to (in one keypress in a decent editor, see README.emacs and README.vim)

a = 1
10.times do |i|
  i ** 2                                           # => 0, 1, 4, 9, 16, 25, 36, 49, 64, 81
  a += i
end
A = 1
A = 1 # !> already initialized constant A

This saves much cut&pasting when you're posting to ruby-talk/ruby-core (I use it all the time).

Assertion generation

xmpfilter.rb can generate assertions based on the current behavior of the code to be tested (iow. the current behavior is assumed to be correct and is used to generate assertions which won't be modified by further runs of xmpfilter.rb), making it quite useful for regression testing.

Imagine you have a ComplexClass you want to test. You might start with

   class TestComplexClass < Test::Unit::TestCase
     def setup; @o = ComplexClass.new("foo", false) end
   end

and then want to add some tests:

 def test_insertion
   @o.insert "bar"
   @o.insert "baz"
   # ... assertions here
 end

At this point, you want to add several assertions to verify that the values returned by @o.size, @o.last, @o.first, @o.complex_computation and @o.last(2) are correct. You can just write the following and feed the file to xmpfilter in -u mode (the # => markers can also be inserted by xmpfilter, see README.vim for more information:

 def test_insertion
   @o.insert "bar"
   @o.insert "baz"
   @o.size                                        # =>
   @o.last                                        # =>
   @o.first                                       # =>
   @o.complex_computation                         # =>
   @o.last(2)                                     # =>
 end

xmpfilter will run the test and remember what happened in each marked line, and then rewrite the code so that it looks for instance like

 def test_insertion
   @o.insert "bar"
   @o.insert "baz"
   assert_equal(2, @o.size)
   assert_equal("baz", @o.last)
   assert_equal("bar", @o.first)
   assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
   assert_equal(["baz", "bar"], @o.last(2))
 end

As you can see, it can save some typing.

You can edit the generated assertions as you want: xmpfilter will not modify lines without the "# =>" marker. xmpfilter.rb can be used repeatedly as you add more assertions. Imagine you want to verify that @o.last(3) raises an ArgumentError. You can simply add one line marked with # => :

 
 ...
   assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
   assert_equal(["baz", "bar"], @o.last(2))
   @o.last(3)                                     # =>
 end

and have it expanded by xmpfilter:

 ...
   assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
   assert_equal(["baz", "bar"], @o.last(2))
   assert_raise(ArgumentError){ @o.last(3) } 
 end

RSpec expectations and use with vim

This animation shows how xmpfilter generates RSpec expectations semi-automatically:

emacs/vim integration

See README.emacs and README.vim for information on how to use xmpfilter.rb from your editor.

License

xmpfilter is licensed under the same terms as Ruby.