Gentlemen, Test Your Engines

9 Feb 2009

In my rails application, I’ve got an engine. I built it myself. It’s more than just a regular plugin, some external library that I trust will plug along by itself: it’s an integral part of my app. It’s got controllers and models, and even routes. It’s a first-class citizen.

When I develop my rails app, I run autotest. It runs my tests automatically when I change code, beeps at me angrily when I break something, and plays a soothing noise when all my tests pass.

So that’s all great. Except autotest wouldn’t run the tests I’ve included in my engine plugin. I had to do all that separately, even though I often work on the app and plugin together, as a unit. So I spent a couple hours and fixed that.

Briefly, to get autotest to test your Engines too:

Update autotest and the Engines plugin
Put an updated .autotest file in your Rails root
Run autotest in your Rails root

I made minor modifications to autotest, so until (unless?) those changes get pulled into the main streams, you’ll have to use my autotest fork (or pull in my last commits to your own forks). You also may need an updated version of the Engines plugin (see below).

Autotest/Zentest — this is released as a gem; I was able to use my version just by copying the lib/ directory from my fork right into my ruby/gems/zentest directory. I’m not sure what’s the accepted method of patching gems on your system, but I’m pretty sure that’s not it. (Coral can’t get here fast enough.)
Engines plugin You need a recent (after Feb 11) version of the engines plugin. This just patches the copy-fixtures-to-temporary-directory behavior; if you don’t have fixtures in your engines, you don’t need these changes.

After you’ve got those libraries in place, you just need this custom .autotest. Put it in your rails root.

The custom autotest adds hooks to run tests for all your vendor/plugins with app/ directories. It detects changes in your plugins/your_engine/app/ code, as well as in your plugin tests, and runs tests appropriately.
It also auto-copies changed fixtures into a temporary directory, combining fixtures from your engines with fixtures from your app — you still need to do a rake test:plugins:setup_plugin_fixtures to prime the pump, and include the Engines::Testing.set_fixture_path line in your test_helper. (See below for details.) It’s not 100% smart yet — if you’re overriding some engine fixtures with new ones in your app directory, you might run into some issues.

Ok, that’s it: just run autotest in your rails root, and your engines tests should be first class citizens. Depending on your project, you might need to tweak the autotest hooks. Adding more .autotest exceptions will make autotest faster (and not eat up your CPU) — I’ve included enough examples that it should be easy to figure out what’s going on.

Please contact me with changes or comments — just ping me with github magic, or contact me through one of the sites in my footer.

Addendum: Engine plugin testing general hints

There are a couple things that tripped me up when setting up my Engines tests.

test_helpers

I’ve got a test_helper.rb under vendor/plugins/my_engine/test/test_helper.rb , where I can add helper methods specific to testing my Engine. From there, I require my main test_helper: require File.expand_path(File.dirname(__FILE__) + '/../../../../test/test_helper'), so I get all the other setup (user login methods, fixtures, etc) I need for my tests.

This way, both your Engine and your main Rails tests have the same require line: require File.dirname(__FILE__) + '/../test_helper'. I find myself generating scaffolds/models and their associated tests in my main Rails application, and then moving controllers and tests between the main app and the Engine.

Fixtures

You can put fixtures under yourplugin/test/fixtures/. Unfortunately, they’ll just sit there and look pretty until you:

Add Engines::Testing.set_fixture_path to your test_helper.rb, and
Run rake test:plugins:setup_plugin_fixtures when you create or update your fixtures.

This way, fixtures from your main application, together with all your Engine plugin fixtures, are copied to a temporary folder and used for your tests.