Ruby Concordion on Rails - Getting Started

UPDATE: The Ruby Concordion Project is pretty much inactive. This blog post is here for my own ego.

There aren't many tutorials out there about Ruby's version of Concordion so I figured that I would help you get started. In this post, I will give you some guidance on how to get started working with Rails 2.0+. The artifacts that concordion requires are:

1. Directories for your specifications
2. Directories for your instrumentation code, a.k.a. fixtures
3. Directories to output your test results
4. An easy way to include concordion functionality into your test suite
5. Provide Rake tasks to run with your build

Create a directory to store your specifications:
$APP_ROOT/test/specs

Create a directory to store your instrumentation code:
$APP_ROOT/test/fixtures

Add a $APP_ROOT/test/fixtures/concordion_test_helper.rb that will make it easy to use Concordion:
==============================================================

#I guess you don't really need this line
ENV["RAILS_ENV"] = "test"

#This adds your specification directory to the Ruby load path
$:.unshift File.join(File.dirname(__FILE__),'..','specs')

#Lazily assign the output directory that concordion will write to
ENV['RCOR_OUTPUT_DIR'] ||= File.join(File.expand_path(File.dirname( __FILE__)),'..','spec-output')

#Load the existing Rails test helper
require File.join(File.dirname(__FILE__),"..","..","test_helper")

#The Concordion main module
require 'concordion/test_methods'

#Decorates all classes that inherit from TestCase class with concordion functionality
class Test::Unit::TestCase

def self.inherited(child)
child.send(:include, Concordion::TestMethods)
end
end

===============================================================
Create a Rake task to run your fixtures as part of your application code:
$APP_ROOT/lib/tasks/concordion.rake
===============================================================

require 'rake/clean'

#Set the directory where all of the test results will go
ENV['RCOR_OUTPUT_DIR'] ||= File.join 'test','concordion','spec-output'

#Task will create the output directory on demand
directory ENV['RCOR_OUTPUT_DIR']

#Add the output directory to the clean task
CLEAN.include ENV['RCOR_OUTPUT_DIR']

namespace :test do
namespace :concordion do
desc "Prepares the environment for running tests"
task :prepare => ['clean','db:test:prepare', ENV['RCOR_OUTPUT_DIR']]
end
end

Rake::TestTask.new('test:concordion' => 'test:concordion:prepare') do |t|
t.libs << "test"
t.libs << Dir[File.join('test','concordion','specs'),File.join('test','concordion','specs','**','*')].select{|item| File.directory?(item)}
t.test_files = FileList[File.join('test','concordion','fixtures','**','*.rb')]
t.verbose = true
end

============================================================================ Now you can create your specification here: $APP_ROOT/test/concordion/spec/order_state_rules.html Then the instrumentation: $APP_ROOT/test/concordion/fixtures/order_state_rules_test.rb ============================================================================

require File.join(File.dirname(__FILE__),"concordion_test_helper")

class OrderStateRulesTest < Test::Unit::TestCase; end

That's pretty much it. In future posts I will go over how to write your first set of examples and some of the mistakes spec authors make while working with Concordion.