Clone wiki

rcrunner / Home



RCRunner is a Mac GUI for running unit tests written with MacRuby for Cocoa code. It allows you to easily multiple or single tests and inspect their results and outputs. Because it works by running an executable, you can add breakpoints to your code and use the debugger to investigate problems. And thanks to RCRunner and your tests being written in Ruby, you can reload your test code without relaunching the app.


Main screen

Version History

  • 0.3 (2011-01-13):
    • Measure and display time taken by tests
    • Don't allow editing of table columns
    • Show suite names in bold
    • Clean up the menus
    • Hide RCRunner specific parts of backtrace by default
    • Remember non-minimized error frame size
    • Make it possible to disable log capture
    • Added an example Xcode with tests
    • Distribute as DMG
  • 0.2 (2010-12-01):
    • Show tests in alphabetical order
    • Catch errors in loaded test modules and show them to the user
    • Show working directory in window title
    • Save window size and position
  • 0.1 (2010-11-30): First release


RCRunner requires MacRuby version 0.7 or later. It has been tested to work with all versions up to 0.10.

Supported Test Targets

At the moment RCRunner supports unit tests written with the MiniTest version bundled with MacRuby or one installed with rubygems. You can test MacRuby code or anything else that can be compiled into a Framework MacRuby is able to load. Basically this means classes that use Cocoa and Objective-C garbage collection.

RCRunner is a Mac app and requires Objective-C garbage collection, but it can be used with iOS code that doesn't depend on UIKit and that doesn't break with GC. You just need to create a Mac framework in your iOS project and include the classes you want to test there.

Known Limitations

The backtraces aren't terribly useful as you can't see the Objective-C stack if you're testing Objective-C code. This is a MacRuby limitation that will hopefully be fixed in a future revision.

For other problems, see the list of issues.

Using in a Cocoa Project with Xcode 3

  • Install MacRuby
  • Install RCRunner
  • Set up a test target in your Xcode project. If you're working on a garbage collected Framework project, you're all set. Otherwise you need to create a new Framework target:
    • Create a new target, using the Cocoa Framework template. You can name it what you want, but in this example I'll call it TestFramework
    • In the Build tab of the target info window, specify Required as the value for Objective-C Garbage Collection if the option is available. Sometimes Xcode doesn't provide the option, in which case you should just specify it at the project level.
    • Add the source files you want to test to the TestFramework target, along with their dependencies
  • Add a new file called my_example_tests.rb to the project with the Ruby File template installed by MacRuby. In it write a test case, looking something like this:
framework "TestFramework"
require "minitest/unit"

class TestClass < MiniTest::Unit::TestCase
  def test_method
    assert_equal "foo", "bar"
  • Add the file to the Copy Bundle Resources build phase of the TestFramework target
  • Add a new Custom Executable called RCRunner to your project. Make it point to to where you installed RCRunner. Make sure the working directory is Build Products directory.
  • Add a new argument to your custom executable, in the info window for the executable, under Arguments tab: TestFramework.framework/Resources/*tests.rb
  • Now with TestFramework as your Target and RCRunner as your Active Executable, build and run your project. RCRunner should launch and you should see the top level element TestClass in the test list with one subitem, test_method.

Note that none of the names above are hard coded: you can name the test target what you want, you can name the Ruby file containing the tests what you want (as long as you give RCRunner a command line argument that matches it), etc.

If you specify --autorun as an argument to RCRunner, it'll automatically run all the tests it can find after starting up.

Using with Xcode 4

With Xcode 4, it's not quite as simple as creating a custom executable.

  • Create a new target.
  • Create a new scheme for the target you created above.
  • In the run phase, specify as the executable.
  • There doesn't seem to be a way to specify the built products directory as the working directory. What you can do is in the Arguments tab of your scheme edit panel's run phase select your framework target in the "Base Expansions On" popup and add "$(BUILD_PRODUCTS_DIR)/NameOfYourFramework.framework/Resources/*tests.rb" (without the quotes) as an argument.
  • Add my_example_tests.rb as above. Include it in the new target.
  • Select your new scheme.
  • Build and run.


RCRunner is available under the terms of the MIT license. For details, see the file COPYING .