h1. Combustion

Combustion is a library to help you test your Rails Engines in a simple and effective manner, instead of creating a full Rails application in your spec or test folder.

It allows you to write your specs within the context of your engine, using only the parts of a Rails app you need.

h2. Usage

Get the gem into either your gemspec or your Gemfile, depending on how you manage your engine's dependencies:

<pre><code># gemspec
gem.add_development_dependency 'combustion', '~> 0.3.1'
# Gemfile
gem 'combustion', '~> 0.3.1`, :group => :development</code></pre>

In your @spec_helper.rb@, get Combustion to set itself up - which has to happen before you introduce @rspec/rails@ and - if being used - @capybara/rspec@. Here's an example within context:

<pre><code>require 'rubygems'
require 'bundler'

Bundler.require :default, :development

require 'capybara/rspec'

Combustion.initialize!

require 'rspec/rails'
require 'capybara/rails'

RSpec.configure do |config|
  config.use_transactional_fixtures = true
end</code></pre>

You'll also want to run the generator that creates a minimal set of files expected by Rails - run this in the directory of your engine:

<pre><code>combust
# or, if bundling with the git repo:
bundle exec combust</code></pre>

What Combustion is doing is setting up a Rails application at @spec/internal@ - but you only need to add the files within that directory that you're going to use. Read on for some detail about what that involves.

h3. Configuring a different test app directory

If you want your app to be located somewhere other than @spec/internal@, then make sure you configure it before you call @Combustion.initialize!@:

<pre><code>Combustion.path = 'spec/dummy'
Combustion.initialize!</code></pre>

h3. Configuring which Rails modules should be loaded.

By default, Combustion assumes you want the full Rails stack. You can customise this though - just pass in what you'd like loaded to the @Combustion.initialize!@ call:

<pre><code>Combustion.initialize! :active_record, :action_controller,
  :action_view, :sprockets</code></pre>

ActiveSupport is always loaded, as it's an integral part of Rails.

h3. Using Models and ActiveRecord

If you're using ActiveRecord, then there's two critical files within your internal Rails app at @spec/internal@ that you'll need to modify:

* config/database.yml
* db/schema.rb

Both follow the same structure as in any normal Rails application - and the schema file lets you avoid migrations, as it gets run whenever the test suite starts. Here's a quick sample (note that tables are overwritten if they already exist - this is necessary):

<pre><code>ActiveRecord::Schema.define do
  create_table(:pages, :force => true) do |t|
    t.string :name
    t.text   :content
    t.timestamps
  end
end</code></pre>

Any models that aren't provided by your engine should be located at @spec/internal/app/models@.

h3. Using ActionController and ActionView

You'll only need to add controllers and views to your internal Rails app for whatever you're testing that your engine doesn't provide - this may be nothing at all, so perhaps you don't even need @spec/internal/app/views@ or @spec/internal/app/controllers@ directories.

However, if you're doing any testing of your engine's controllers or views, then you're going to need routes set up for them - so modify @spec/internal/config/routes.rb@ accordingly:

<pre><code>Rails.application.routes.draw do
  resources :pages
end</code></pre>

Just like in a standard Rails app, if you have a mounted engine, then its routes are accessible through whatever it has been loaded as.

h3. Environment and Logging

Your tests will execute within the test environment for the internal Rails app - and so logs are available at @spec/internal/log/test.log@. You should probably create that log directory so Rails doesn't complain.

h3. Rack it up

Once you've got this set up, you can fire up your test environment quite easily with Rack - a @config.ru@ file is provided by the generator. Just run @rackup@ and visit "http://localhost:9292":http://localhost:9292.

h3. Get your test on!

Now you're good to go - you can write specs within your engine's spec directory just like you were testing a full Rails application - models in @spec/models@, controllers in @spec/controllers@. If you bring Capybara into the mix, then the standard helpers helpers from that will be loaded as well.

<pre><code>require 'spec_helper'

describe Page do
  describe '#valid' do
    it 'requires a name' do
      # This is just an example. Go write your own tests!
    end
  end
end</code></pre>

h2. Compatibility

Developed for Rails 3.1 and Ruby 1.9. It should work on any other Ruby, and possibly Rails 3.0, but will not work neatly with earlier versions of Rails.

h2. Limitations and Known Issues

Combustion is currently written with the expectation it'll be used with RSpec. I'd love to make this more flexible - if you want to give it a shot before I get around to it, patches are very much welcome.

I've not tried using this with Cucumber, but it should work in theory without too much hassle. Let me know if I'm wrong!

h2. Contributing

Contributions are very much welcome - but keep in mind the following:

* Keep patches in a separate branch
* Don't mess with the version or history file. I'll take care of that when the patch is merged in.

There are no tests - partly because Combustion was extracted out from the tests of HyperTiny's Dobro, and partly because there's not much code. Still, if you can find a clean way of testing this, that'd be fantastic.

h2. Credits

Copyright (c) 2011, Combustion is developed and maintained by Pat Allan, and is released under the open MIT Licence. Many thanks to HyperTiny for encouraging its development, and "all who have contributed patches":https://github.com/freelancing-god/combustion/contributors.