# RSpec 2 library for specifying and testing generators

This project contains RSpec 2 matchers, helpers and various utilities to assist in writing Rails 3 generator specs.

Rails 3 has a Rails::Generators::TestCase class for use with Test-Unit, to help test generators, containing specific assertion methods that can be used to assert generator behavior. Theres was no RSpec 2 equivalent, so I wrapped Rails::Generators::TestCase for use with RSpec 2 and created some RSpec 2 matchers that mimic the assertion methods
of TestCase and also added some extra goodies to the mix. It should now be pretty easy to test your Rails 3 generators with RSpec 2 :)

Please advice if you find any issues or have suggestions for improvements. The code is not as pretty as it could be, so feel free to refactor and improve it to your hearts desire!

## Install

<code>gem install rspec_for_generators</code>

The gem is a jewel (using jeweler), so to install the gem from the code - simply use the jeweler rake task:

<code>rake install</code>

## Usage

The following demonstrates an example usage. There are many more options and DSL convenience methods.

### Configuration

First setup the *spec_helper.rb*. Here is an example configuration.

<pre># spec/spec_helper.rb
  
require 'rspec'
require 'rspec_for_generators'

# configure it like this to use default settings
RSpec::Generator.configure_root_dir __FILE__

# or customize the location of the temporary Rails 3 app dir used
RSpec::Generator.configure_root_dir '~/my/rails/folder', :custom
</pre>

### Specs for generators

I recommend having a separate spec for each generator. A generator spec can include *this* file to ensure all generators are loaded.
Put a *require_generator* statement in each spec file, to ensure that particular generator is loaded and thus available for the spec.

<pre>require_generator :canable</pre>

This will load the generator : `generators/canabale_generator.rb`

If the generator is namespaced, use a nested approach like this:

<pre>require_generators :canable => ['model', 'user']</pre>

This will load the generators: `generators/canable/model_generator.rb` and `generators/canable/user_generator.rb`

If you have multiple generators in a shared namespace, the following approach can be used. 
Create a file that loads all the generators in the namespace. Include this file for each spec that tests a particular generator in that namespace:
  
<pre># spec/generators/canable.rb
require_generators :canable => ['model', 'user']</pre>

<pre># spec/generators/canable/model_generator_spec.rb
...
# load generators to spec
require 'generators/canable'

describe 'model_generator' do
  ...   
end
</pre>

<pre># spec/generators/canable/user_generator_spec.rb
...
# load generators to spec
require 'generators/canable'

describe 'user_generator' do
  ...   
end
</pre>



### Example of full generator spec

<pre># spec/generators/model_generator_spec.rb  

require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')

# list of generators to spec are loaded
require 'generators/canable'

describe 'model_generator' do
  # include Rails model helpers for ActiveRecord
  # available: MongoMapper, Mongoid and DataMapper
  
  include RSpec::Rails::Orm::ActiveRecord
  
  before :each do              
    # define generator to test
    setup_generator 'model_generator' do
      tests Canable::Generators::ModelGenerator
    end    
    # ensure clean state before run
    remove_model 'account'    
  end

  after :each do              
    # ensure clean state after run  
    remove_model 'account'    
  end
    
  it "should not work without an existing Account model file" do            
    with_generator do |g|   
      name = 'account'
      g.run_generator %w{account}
      g.should_not generate_file name, :model
    end
  end

  it "should decorate an existing Account model file with 'include Canable:Ables'" do            
    with_generator do |g|  
      name = 'account'
      create_model name     
      g.run_generator %w{account}
      g.should generate_model name do |content|
        content.should have_class name do |klass|
          klass.should include_module 'Canable::Ables'
        end
      end
    end
  end
end</pre>

## TODO

Need to create specs to test matchers/helpers for generated:
* migration
* controller
* helper
* view
* ...

## Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

## Copyright

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.