combustion 0.1.1 → 0.2.0

data/HISTORY

@@ -1,3 +1,8 @@
+0.2.0 - August 30th 2011
+* Documentation.
+* Allow developers to choose which Rails modules they wish to be loaded.
+* Load Rails routes and Capybara helpers into RSpec examples when appropriate.
+
 0.1.1 - August 24th 2011
 * Support assets properly by loading ActionView and Sprockets railties.
 

data/README.textile

@@ -1,7 +1,128 @@
 h1. Combustion
 
-More information/documentation coming soon.
+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.2.0'
+# Gemfile
+gem 'combustion', '~> 0.2.0`, :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
+
+Combustion.initialize!
+
+require 'rspec/rails'
+require 'capybara/rspec'
+
+RSpec.configure do |config|
+  config.use_transactional_fixtures = true
+end</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 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 create:
+
+* 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 create a standard routes file at @spec/internal/config/routes.rb@:
+
+<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 - here's an example @config.ru@ file that could live in the root of your engine folder:
+
+<pre><code>require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize!
+run Combustion::Application</code></pre>
+
+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'm also keen to have a generator that adds the standard set of files and folders (@config/database.yml@, @config/routes.rb@, @db/schema.rb@, @log@) into @spec/internal@, just to make it even easier to get going. Again, patches are welcome for this, but I'll likely get to it pretty soon.
+
+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.
+* Write tests - look at the existing tests (particularly in @spec/acceptance@)
+
+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
 
-Combustion is developed and maintained by Pat Allan, and is released under the open MIT Licence.
+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.

data/lib/combustion.rb

@@ -1,17 +1,27 @@
 require 'rails'
 require 'active_support/dependencies'
-require 'active_record/railtie'
-require 'action_controller/railtie'
-require 'action_view/railtie'
-require 'sprockets/railtie'
 
 module Combustion
-  def self.initialize!
+  Modules = %w( active_record action_controller action_view action_mailer
+    sprockets )
+
+  def self.initialize!(*modules)
+    modules = Modules if modules.empty? || modules == [:all]
+    modules.each { |mod| require "#{mod}/railtie" }
+
+    Combustion::Application.configure_for_combustion
     Combustion::Application.initialize!
 
     silence_stream(STDOUT) do
       load "#{Rails.root}/db/schema.rb"
     end
+
+    RSpec.configure do |config|
+      config.include(Capybara) if defined?(Capybara)
+
+      config.include(Combustion::Application.routes.url_helpers)
+      config.include(Combustion::Application.routes.mounted_helpers)
+    end if defined?(RSpec) && RSpec.respond_to?(:configure)
   end
 end
 

data/lib/combustion/application.rb

@@ -12,15 +12,23 @@ class Combustion::Application < Rails::Application
   # ActiveSupport Settings
   config.active_support.deprecation = :stderr
 
-  # Action Controller and Action Dispatch
-  config.action_dispatch.show_exceptions            = false
-  config.action_controller.perform_caching          = false
-  config.action_controller.allow_forgery_protection = false
+  # Some settings we're not sure if we want, so let's not load them by default.
+  # Instead, wait for this method to be invoked (to get around load-order
+  # complications).
+  def self.configure_for_combustion
+    if defined?(ActionController) && defined?(ActionController::Engine)
+      config.action_dispatch.show_exceptions            = false
+      config.action_controller.perform_caching          = false
+      config.action_controller.allow_forgery_protection = false
+    end
 
-  # Action Mailer Settings
-  # config.action_mailer.delivery_method      = :test
-  # config.action_mailer.default_url_options  = {:host => 'www.example.com'}
+    if defined?(ActionMailer) && defined?(ActionMailer::Engine)
+      config.action_mailer.delivery_method     = :test
+      config.action_mailer.default_url_options = {:host => 'www.example.com'}
+    end
 
-  # Asset Settings
-  config.assets.enabled = true
+    if defined?(Sprockets)
+      config.assets.enabled = true
+    end
+  end
 end

data/lib/combustion/version.rb

@@ -1,3 +1,3 @@
 module Combustion
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: combustion
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-08-24 00:00:00.000000000 Z
+date: 2011-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &2156734700 !ruby/object:Gem::Requirement
+  requirement: &2152591540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 3.1.0.rc5
   type: :runtime
   prerelease: false
-  version_requirements: *2156734700
+  version_requirements: *2152591540
 description: Test your Rails Engines without needing a full Rails app
 email:
 - pat@freelancing-gods.com