<commit_before>= genspec

Simple, expressive Rails generator testing for RSpec.

== Installation

  sudo gem install genspec

...then, in your config/environments/test.rb...

  config.gem 'genspec'
  
== Usage

Just like rspec-rails uses the structure of your spec/ directory to infer which test is being run (controllers,
helpers, lib, etc.), you just need to create a spec/generators directory and put your generator specs in there.
A basic generator spec might look something like this:

  # in spec/generators/custom_controller_spec.rb
  require 'spec_helper'
  
  describe :custom_controller do
    context "with no arguments or options" do
      it "should generate a help message" do
        subject.should output("A Help Message")
      end
    end
    
    context "with a name argument" do
      with_args :users
      
      it "should generate a UsersController" do
        subject.should generate("app/controllers/users_controller.rb")
      end
    end
  end
  
=== Specifying Arguments and Options

You may have noticed in the example above that we used _with_args_ to set up arguments passed into the generator. We
can also use _with_options_ to set up runtime options. For instance, to pretend the _--verbose_ option was passed, we
could use the following spec:

  describe :custom_controller do
    context "with --verbose option" do
      with_options :verbose => true
      
      # . . .
    end
  end
  
Here is another example using _with_args_:

  describe :custom_controller do
    context "with a users controller and index, new, edit actions" do
      with_args :users, :index, :new, :edit
      
      # . . .
    end
  end

Note that no matter what you specify as arguments, they'll be converted to an array of Strings -- because this is what
gets passed into the generator if you run it from the command line. The options are expected to be a hash, which is
how Rails generators read their options from the command line.


=== Checking for Output

If you need to test the generator's feedback rather than the generator's results, you can use the _output_ matcher to
assert that your generator has produced some specific content in its output (which would be either a logger of some
sort or $stdout). This is helpful for making sure your help message is accurate, for instance.

  # Ex 1: String
  it "should generate a help message" do
    subject.should output("A Help Message")
  end
  
  # Ex 2: Regular Expression
  it "should generate a help message" do
    subject.should output(/A [hH]elp Message/)
  end


=== Checking Generated Files

This is the preferred way to test which files were actually generated, because this matcher checks your
generator's *behavior*. That means it won't care _how_ a file is generated, as long as it _is_ generated. It's as simple
as passing the name of the file you expected to be generated:

  it "should generate a readme file" do
    subject.should generate("README")
  end
  
You can also check the generated file's content by simply passing a block. The argument in the block is the plaintext
content of the file:

  it "should generate a model called 'user'" do
    subject.should generate("app/models/user.rb") { |content|
      content.should =~ /class User < ActiveRecord\:\:Base/
    }
  end

=== Checking Generation Methods

This is the most intrusive form of generation matching, and should be avoided where possible. However, in some cases
you just can't check behavior directly (migrations are a case in point, because the version number is unpredictable).
In that case, you can verify that a particular method is called within the generator's manifest like so:

  it "should generate a user migration template" do
    subject.should generate(:migration_template, "migration_template.erb", "db/migrate", :migration_file => "create_users")
  end
  
You can stop passing arguments at any time. This has the effect of widening the range of acceptable parameters. For
instance, the following example does the same thing but will accept _any_ migration file name in _any_ destination
directory, as long as the "migration_template.erb" file is used for the source:

  it "should generate a migration template" do
    subject.should generate(:migration_template, "migration_template.rb")
  end

Any method that is normally available to Rails generators can be tested in this way:

  it "should test one of each generation type" do
    subject.should generate(:directory, "db/migrate")
    subject.should generate(:file, "input_file", "output_file")
    subject.should generate(:template, "input_template", "output_template")
    subject.should generate(:class_collisions, 'ActionController::Base')
    subject.should generate(:migration_template, "file", "directory", :migration_file_name => "filename")
    subject.should generate(:resource_routes, 'model_name')
    subject.should generate(:readme, "README")
  end
  
But again... Use these as last resorts, for the most part. Technically, you will probably need this for
:migration_template and :resource_routes, but anything else should really be tested for _behavior_. Like any other
class, you should really only care about how the generator interacts with other objects -- in this case, your file
system -- and not so much about what it's doing on the inside.

  
== 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 <NAME>. See LICENSE for details.
<commit_msg>Readme updates for Rails 3<commit_after>= genspec

Simple, expressive Rails generator testing for RSpec.

== Installation

  sudo gem install genspec

...then, in your config/environments/test.rb...

  config.gem 'genspec'
  
Warning: This is for Rails 2. For Rails 3, see the rails-3 branch at
http://github.com/sinisterchipmunk/genspec/tree/rails-3
  
== Usage

Just like rspec-rails uses the structure of your spec/ directory to infer which test is being run (controllers,
helpers, lib, etc.), you just need to create a spec/generators directory and put your generator specs in there.
A basic generator spec might look something like this:

  # in spec/generators/custom_controller_spec.rb
  require 'spec_helper'
  
  describe :custom_controller do
    context "with no arguments or options" do
      it "should generate a help message" do
        subject.should output("A Help Message")
      end
    end
    
    context "with a name argument" do
      with_args :users
      
      it "should generate a UsersController" do
        subject.should generate("app/controllers/users_controller.rb")
      end
    end
  end
  
=== Specifying Arguments and Options

You may have noticed in the example above that we used _with_args_ to set up arguments passed into the generator. We
can also use _with_options_ to set up runtime options. For instance, to pretend the _--verbose_ option was passed, we
could use the following spec:

  describe :custom_controller do
    context "with --verbose option" do
      with_options :verbose => true
      
      # . . .
    end
  end
  
Here is another example using _with_args_:

  describe :custom_controller do
    context "with a users controller and index, new, edit actions" do
      with_args :users, :index, :new, :edit
      
      # . . .
    end
  end

Note that no matter what you specify as arguments, they'll be converted to an array of Strings -- because this is what
gets passed into the generator if you run it from the command line. The options are expected to be a hash, which is
how Rails generators read their options from the command line.


=== Checking for Output

If you need to test the generator's feedback rather than the generator's results, you can use the _output_ matcher to
assert that your generator has produced some specific content in its output (which would be either a logger of some
sort or $stdout). This is helpful for making sure your help message is accurate, for instance.

  # Ex 1: String
  it "should generate a help message" do
    subject.should output("A Help Message")
  end
  
  # Ex 2: Regular Expression
  it "should generate a help message" do
    subject.should output(/A [hH]elp Message/)
  end


=== Checking Generated Files

This is the preferred way to test which files were actually generated, because this matcher checks your
generator's *behavior*. That means it won't care _how_ a file is generated, as long as it _is_ generated. It's as simple
as passing the name of the file you expected to be generated:

  it "should generate a readme file" do
    subject.should generate("README")
  end
  
You can also check the generated file's content by simply passing a block. The argument in the block is the plaintext
content of the file:

  it "should generate a model called 'user'" do
    subject.should generate("app/models/user.rb") { |content|
      content.should =~ /class User < ActiveRecord\:\:Base/
    }
  end

=== Checking Generation Methods

This is the most intrusive form of generation matching, and should be avoided where possible. However, in some cases
you just can't check behavior directly (migrations are a case in point, because the version number is unpredictable).
In that case, you can verify that a particular method is called within the generator's manifest like so:

  it "should generate a user migration template" do
    subject.should generate(:migration_template, "migration_template.erb", "db/migrate", :migration_file => "create_users")
  end
  
You can stop passing arguments at any time. This has the effect of widening the range of acceptable parameters. For
instance, the following example does the same thing but will accept _any_ migration file name in _any_ destination
directory, as long as the "migration_template.erb" file is used for the source:

  it "should generate a migration template" do
    subject.should generate(:migration_template, "migration_template.rb")
  end

Any method that is normally available to Rails generators can be tested in this way:

  it "should test one of each generation type" do
    subject.should generate(:directory, "db/migrate")
    subject.should generate(:file, "input_file", "output_file")
    subject.should generate(:template, "input_template", "output_template")
    subject.should generate(:class_collisions, 'ActionController::Base')
    subject.should generate(:migration_template, "file", "directory", :migration_file_name => "filename")
    subject.should generate(:resource_routes, 'model_name')
    subject.should generate(:readme, "README")
  end
  
But again... Use these as last resorts, for the most part. Technically, you will probably need this for
:migration_template and :resource_routes, but anything else should really be tested for _behavior_. Like any other
class, you should really only care about how the generator interacts with other objects -- in this case, your file
system -- and not so much about what it's doing on the inside.

  
== 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 <NAME>. See LICENSE for details.

{'fraction_non_alphanumeric': 0.06254786826653051, 'fraction_numerical': 0.0014466853884775764, 'mean_word_length': 3.7636805837049048, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1240947', 'n_tokens_mistral': 3125, 'n_tokens_neox': 3018, 'n_words': 1583}