---
title: Test::Unit Migration
inMenu: true
---
h2. Overview of test2spec

RSpec's test2spec command line tool translates existing Test::Unit classes to RSpec.  

Before you can use test2spec you must gem install ParseTree (and RubyInline).
RubyInline only works on systems that have a C compiler - i.e. most anything except Windows.

If you're stuck on Windows, ask a friend who has a POSIX system to translate your specs.
Once translated they can run on any Ruby platform (including Windows). After all, it's
just Ruby.

h2. The test2spec command line

<pre>
test2spec --help
{execute: ruby ../bin/test2spec --help}
</pre>

A typical invocation might look like this:

<pre>
test2spec --template spec/test2spec.erb --specdir spec test
</pre>

Where spec/test2spec.erb contains the following:

<pre>
{includeFile: {filename: ../../../spec/test2spec.erb, processOutput: false}}
</pre>


h2. Sample translation

<notextile>
<table>
  <thead>
    <tr>
      <td>Test::Unit (input)</td>
      <td>RSpec (output)</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <ruby file="../test/spec/test_to_spec/testfiles/test_unit_api_test.rb"/>
      </td>
      <td>
        <ruby file="../spec/translated/test_unit_api_spec.rb"/>
      </td>
    </tr>
  </tbody>
</table>
</notextile>

h2. What's translated?

test2spec only translates classes that extend from Test::Unit - and their methods. It will not bring over any 
code that isn't inside a Test::Unit class. This means that require statements at the top of your file, any other
classes in the same file as the test class etc *will not be translated*.

So, there is a fair chance that you will have to do some manual editing after test2spec has run. We're only
aiming to get most of the translation job done for you - not all of it.

h2. Troubleshooting

In some cases, test2spec will not be able to translate a test class. In that case, please submit a bug report
at RSpec's bug report system  along with some code so we can reproduce (and hopefully - fix) the problem. 
-Or better - submit a patch.

h2. Internals

The test2spec commandline 'runs' the tests with a special test runner - one that translates and writes out
the translations to disk instead of actually executing the tests.

The translation is done by the <tt>Test::Unit::TestCase#to_rspec</tt> method (which test2spec adds to all 
test classes). This method will load the parse tree for the class, transform that tree to an RSpec context 
and return the source code (using RubyToRuby).

test2spec is based directly on two other tools:

* "RubyToRuby":http://blog.zenspider.com/archives/2005/02/rubytoruby.html
* "ParseTree":http://rubyforge.org/projects/parsetree/

In fact, it's based on a modified version of "George Moschovitis' RubyToRuby enhancement":http://dark.fhtr.org/ruby2ruby.rb
of "Ryan Davis' original RubyToRuby":http://blog.zenspider.com/archives/2005/02/rubytoruby.html.

It has been modified to fix some subtle bugs that were not found by Gerorge's tests. The modified RubyToRuby
currently lives in RSpec's subversion repository.