machinist 1.0.6 → 2.0

data/.gitignore

@@ -1,4 +1,7 @@
-coverage
-doc
-*.gem
-*.project
+.DS_Store
+/.bundle
+/.rvmrc
+/coverage
+/doc
+/pkg
+/tags

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    machinist (2.0.0.beta2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.9)
+      activesupport (= 3.0.9)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.9)
+      activemodel (= 3.0.9)
+      activesupport (= 3.0.9)
+      arel (~> 2.0.10)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.9)
+    arel (2.0.10)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    i18n (0.5.0)
+    mysql (2.8.1)
+    rake (0.9.2)
+    rcov (0.9.9)
+    rdoc (3.6.1)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    tzinfo (0.3.28)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord
+  machinist!
+  mysql
+  rake
+  rcov
+  rdoc
+  rspec

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Peter Yandell
+Copyright (c) 2008-2010 Peter Yandell
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -18,3 +18,4 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.markdown

@@ -1,295 +1,266 @@
-Machinist
-=========
+# Machinist 2
 
 *Fixtures aren't fun. Machinist is.*
-  
-Machinist makes it easy to create test data within your tests. It generates data for the fields you don't care about, and constructs any necessary associated objects, leaving you to only specify the fields you *do* care about in your tests. For example:
-
-    describe Comment do
-      before do
-        # This will make a Comment, a Post, and a User (the author of
-        # the Post), and generate values for all their attributes:
-        @comment = Comment.make(:spam => true)
-      end
-    
-      it "should not include comments marked as spam in the without_spam named scope" do
-        Comment.without_spam.should_not include(@comment)
+
+Machinist 2 is **still in beta**!
+
+If you're using Rails 3, you'll want to give Machinist 2 a go, but be aware
+that the documentation is still patchy.
+
+That said, have a look at [the
+specs](https://github.com/notahat/machinist/tree/master/spec), starting with
+[the spec for
+Machinable](https://github.com/notahat/machinist/blob/master/spec/machinable_spec.rb).
+No, really, have a look. I wrote this code to be read, and the specs do a
+pretty clean job of documenting what it all does.
+
+If, on the other hand, you want the tried, tested, and well-documented official
+release version of Machinist, [then go with Machinist
+1](http://github.com/notahat/machinist/tree/1.0-maintenance).
+
+- [Home page](http://github.com/notahat/machinist)
+- [Google group](http://groups.google.com/group/machinist-users), for support
+- [Bug tracker](http://github.com/notahat/machinist/issues), for reporting Machinist bugs
+
+
+## Introduction
+
+Machinist makes it easy to create objects for use in tests. It generates data
+for the attributes you don't care about, and constructs any necessary
+associated objects, leaving you to specify only the fields you care about in
+your test. For example:
+
+    describe Comment, "without_spam scope" do
+      it "doesn't include spam" do
+        # This will make a Comment, a Post, and a User (the author of the
+        # Post), generate values for all their attributes, and save them:
+        spam = Comment.make!(:spam => true)
+
+        Comment.without_spam.should_not include(spam)
       end
     end
 
 You tell Machinist how to do this with blueprints:
 
     require 'machinist/active_record'
-    require 'sham'
-    require 'faker'
-  
-    Sham.name  { Faker::Name.name }
-    Sham.email { Faker::Internet.email }
-    Sham.title { Faker::Lorem.sentence }
-    Sham.body  { Faker::Lorem.paragraph }
-  
+
     User.blueprint do
-      name
-      email
+      username { "user#{sn}" }  # Each user gets a unique serial number.
     end
-  
+
     Post.blueprint do
-      title
       author
-      body
+      title  { "Post #{sn}" }
+      body   { "Lorem ipsum..." }
     end
-  
+
     Comment.blueprint do
       post
-      author_name  { Sham.name }
-      author_email { Sham.email }
-      body
+      email { "commenter#{sn}@example.com" }
+      body  { "Lorem ipsum..." }
     end
-    
 
-Download & Install
-==================
 
-### Installing as a Rails plugin
+## Installation
 
-    ./script/plugin install git://github.com/notahat/machinist.git
-      
-### Installing as a Gem
+### Upgrading from Machinist 1
 
-    sudo gem install machinist --source http://gemcutter.org
+See [the wiki](http://wiki.github.com/notahat/machinist/machinist-2).
 
-### Setting up your project
+### Rails 3
 
-Create a `blueprints.rb` file to hold your blueprints in your test (or spec) directory. It should start with:
+In your app's `Gemfile`, in the `group :test` section, add:
 
-    require 'machinist/active_record'
-    require 'sham'
-    
-Substitute `data_mapper` or `sequel` for `active_record` if that's your weapon of choice.
-    
-Require `blueprints.rb` in your `test_helper.rb` (or `spec_helper.rb`):
+    gem 'machinist', '>= 2.0.0.beta2'
 
-    require File.expand_path(File.dirname(__FILE__) + "/blueprints")
+Then run:
 
-Set Sham to reset before each test. In the `class Test::Unit::TestCase` block in your `test_helper.rb`, add:
-    
-    setup { Sham.reset }
-    
-or, if you're on RSpec, in the `Spec::Runner.configure` block in your `spec_helper.rb`, add:
+    bundle
+    rails generate machinist:install
 
-    config.before(:all)    { Sham.reset(:before_all)  }
-    config.before(:each)   { Sham.reset(:before_each) }
+If you want Machinist to automatically add a blueprint to your blueprints file
+whenever you generate a model, add the following to your `config/application.rb`
+inside the Application class:
 
-    
-Documentation
-=============
+    config.generators do |g|
+      g.fixture_replacement :machinist
+    end
 
-Sham - Generating Attribute Values
-----------------------------------
+### Rails 2
 
-Sham lets you generate random but repeatable unique attributes values.
+See [the wiki](http://wiki.github.com/notahat/machinist/rails-2).
 
-For example, you could define a way to generate random names as:
 
-    Sham.name { (1..10).map { ('a'..'z').to_a.rand }.join }
+## Usage
 
-Then, to generate a name, call:
+### Blueprints
 
-    Sham.name
+A blueprint describes how to generate an object. The blueprint takes care of
+providing attributes that your test doesn't care about, leaving you to focus on
+just the attributes that are important for the test.
+ 
+A simple blueprint might look like this:
+ 
+    Post.blueprint do
+      title  { "A Post" }
+      body   { "Lorem ipsum..." }
+    end
+ 
+You can then construct a Post from this blueprint with:
 
-So why not just define a helper method to do this? Sham ensures two things for you:
+    Post.make!
+ 
+When you call `make!`, Machinist calls `Post.new`, then runs through the
+attributes in your blueprint, calling the block for each attribute to generate
+a value. It then saves and reloads the Post. (It throws an exception if the
+Post can't be saved.)
 
-1. You get the same sequence of values each time your test is run
-2. You don't get any duplicate values
-    
-Sham works very well with the excellent [Faker gem](http://faker.rubyforge.org/) by Benjamin Curtis. Using this, a much nicer way to generate names is:
-    
-    Sham.name { Faker::Name.name }
-    
-Sham also supports generating numbered sequences if you prefer.
+You can override values defined in the blueprint by passing a hash to make:
+ 
+    Post.make!(:title => "A Specific Title")
 
-    Sham.name {|index| "Name #{index}" }
-    
-If you want to allow duplicate values for a sham, you can pass the `:unique` option:
+If you want to generate an object without saving it to the database, replace
+`make!` with `make`.
 
-    Sham.coin_toss(:unique => false) { rand(2) == 0 ? 'heads' : 'tails' }
-    
-You can create a bunch of sham definitions in one hit like this:
 
-    Sham.define do
-      title { Faker::Lorem.words(5).join(' ') }
-      name  { Faker::Name.name }
-      body  { Faker::Lorem.paragraphs(3).join("\n\n") }
-    end
+### Unique Attributes
 
+For attributes that need to be unique, you can call the `sn` method from
+within the attribute block to get a unique serial number for the object.
 
-Blueprints - Generating Objects
--------------------------------
+    User.blueprint do
+      username { "user-#{sn}" }
+    end
+      
 
-A blueprint describes how to generate an object. The idea is that you let the blueprint take care of making up values for attributes that you don't care about in your test, leaving you to focus on the just the things that you're testing.
+### Associations
 
-A simple blueprint might look like this:
+If your object needs associated objects, you can generate them like this:
 
-    Post.blueprint do
-      title  { Sham.title }
-      author { Sham.name }
-      body   { Sham.body }
+    Comment.blueprint do
+      post { Post.make }
     end
+ 
+Calling `Comment.make!` will construct a Comment and its associated Post, and
+save both.
 
-You can then construct a Post from this blueprint with:
-    
-    Post.make
-    
-When you call `make`, Machinist calls `Post.new`, then runs through the attributes in your blueprint, calling the block for each attribute to generate a value. The Post is then saved and reloaded. An exception is thrown if Post can't be saved.
+Machinist is smart enough to look at the association and work out what sort of
+object it needs to create, so you can shorten the above blueprint to:
+ 
+    Comment.blueprint do
+      post
+    end
 
-You can override values defined in the blueprint by passing a hash to make:
+If you want to override the value for post when constructing the comment, you
+can do this:
+ 
+    post = Post.make(:title => "A particular title)
+    comment = Comment.make(:post => post)
 
-    Post.make(:title => "A Specific Title")
-    
-If you don't supply a block for an attribute in the blueprint, Machinist will look for a Sham definition with the same name as the attribute, so you can shorten the above blueprint to:
 
-    Post.blueprint do
-      title
-      author { Sham.name }
-      body
-    end
-    
-If you want to generate an object without saving it to the database, replace `make` with `make_unsaved`. (`make_unsaved` also ensures that any associated objects that need to be generated are not saved - although not if you are using Sequel. See the section on associations below.)
-
-You can refer to already assigned attributes when constructing a new attribute:
+For `has_many` and `has_and_belongs_to_many` associations, you can create
+multiple associated objects like this:
 
     Post.blueprint do
-      title
-      author { Sham.name }
-      body   { "Post by #{author}" }
+      comments(3)  # Makes 3 comments.
     end
-        
 
-### Named Blueprints
 
-Named blueprints let you define variations on an object. For example, suppose some of your Users are administrators:
+### Named Blueprints
 
+Named blueprints let you define variations on an object. For example, suppose
+some of your Users are administrators:
+ 
     User.blueprint do
-      name
-      email
+      name  { "User #{sn}" }
+      email { "user-#{sn}@example.com" }
     end
-
+ 
     User.blueprint(:admin) do
-      name  { Sham.name + " (admin)" }
+      name  { "Admin User #{sn}" }
       admin { true }
     end
-
+ 
 Calling:
-
-    User.make(:admin)
-
+ 
+    User.make!(:admin)
+ 
 will use the `:admin` blueprint.
+ 
+Named blueprints call the default blueprint to set any attributes not
+specifically provided, so in this example the `email` attribute will still be
+generated even for an admin user.
+ 
+You must define a default blueprint for any class that has a named blueprint,
+even if the default blueprint is empty.
 
-Named blueprints call the default blueprint to set any attributes not specifically provided, so in this example the `email` attribute will still be generated even for an admin user.
 
+### Blueprints on Plain Old Ruby Objects
 
-### Belongs\_to Associations
+Machinist also works with plain old Ruby objects. Let's say you have a class like:
+ 
+    class Post
+      extend Machinist::Machinable
 
-If you're generating an object that belongs to another object, you can generate the associated object like this:
-    
-    Comment.blueprint do
-      post { Post.make }
+      attr_accessor :title
+      attr_accessor :body
     end
-    
-Calling `Comment.make` will construct a Comment and its associated Post, and save both.
-
-If you want to override the value for post when constructing the comment, you can do this:
 
-    post = Post.make(:title => "A particular title)
-    comment = Comment.make(:post => post)
-    
-Machinist will not call the blueprint block for the post attribute, so this won't generate two posts.
-    
-Machinist is smart enough to look at the association and work out what sort of object it needs to create, so you can shorten the above blueprint to:
-    
-    Comment.blueprint do
-      post
+You can blueprint the Post class just like anything else:
+ 
+    Post.blueprint do
+      title { "A title!" }
+      body  { "A body!" }
     end
 
-    
-### Other Associations
+And `Post.make` will construct a new Post.
 
-For has\_many and has\_and\_belongs\_to\_many associations, ActiveRecord insists that the object be saved before any associated objects can be saved. That means you can't generate the associated objects from within the blueprint.
 
-The simplest solution is to write a test helper:
+### Other Tricks
 
-    def make_post_with_comments(attributes = {})
-      post = Post.make(attributes)
-      3.times { post.comments.make }
-      post
+You can refer to already assigned attributes when constructing a new attribute:
+ 
+    Post.blueprint do
+      author { "Author #{sn}" }
+      body   { "Post by #{object.author}" }
     end
 
-Note here that you can call `make` on a has\_many association. (This isn't yet supported for DataMapper.)
 
-Make can take a block, into which it passes the constructed object, so the above can be written as:
+## Compatibility
 
-    def make_post_with_comments
-      Post.make(attributes) do |post|
-        3.times { post.comments.make }
-      end
-    end
+I've tested this with:
 
+Ruby versions: 1.8.7, 1.9.2
+Rails versions: 2.3, 3.0
 
-### Using Blueprints in Rails Controller Tests
+It may well be happy with other versions too, but I'm not promising anything.
+Compatibility patches are welcome.
 
-The `plan` method behaves like `make`, except it returns a hash of attributes, and doesn't save the object. This is useful for passing in to controller tests:
 
-    test "should create post" do
-      assert_difference('Post.count') do
-        post :create, :post => Post.plan
-      end
-      assert_redirected_to post_path(assigns(:post))
-    end
-    
-`plan` will save any associated objects. In this example, it will create an Author, and it knows that the controller expects an `author_id` attribute, rather than an `author` attribute, and makes this translation for you.
-    
-You can also call plan on has\_many associations, making it easy to test nested controllers:
-
-    test "should create comment" do
-      post = Post.make
-      assert_difference('Comment.count') do
-        post :create, :post_id => post.id, :comment => post.comments.plan
-      end
-      assert_redirected_to post_comment_path(post, assigns(:comment))
-    end
-    
-(Calling plan on associations is not yet supported in DataMapper.)
+## Developing
 
+The Machinist specs and source code were written to be read, and I'm pretty
+happy with them. Don't be afraid to have a look under the hood!
 
-### Blueprints on Plain Old Ruby Objects
+If you want to submit a patch:
 
-Machinist also works with plain old Ruby objects. Let's say you have a class like:
+- 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.
 
-    class Post
-      attr_accessor :title
-      attr_accessor :body
-    end
-    
-You can then do the following in your `blueprints.rb`:
 
-    require 'machinist/object'
-    
-    Post.blueprint do
-      title "A title!"
-      body  "A body!"
-    end
+## Status
 
-Community
-=========
+In active use in a number of large Rails 2 apps.
 
-You can always find the [latest version on GitHub](http://github.com/notahat/machinist).
+Development has been sporadic, but is picking up again.
 
-If you have questions, check out the [Google Group](http://groups.google.com/group/machinist-users).
 
-File bug reports and feature requests in the [issue tracker](http://github.com/notahat/machinist/issues).
-
-Contributors
-------------
+## Contributors
 
 Machinist is maintained by Pete Yandell ([pete@notahat.com](mailto:pete@notahat.com), [@notahat](http://twitter.com/notahat))
 
@@ -297,21 +268,28 @@ Other contributors include:
 
 [Marcos Arias](http://github.com/yizzreel),
 [Jack Dempsey](http://github.com/jackdempsey),
+[Jeremy Durham](http://github.com/jeremydurham),
 [Clinton Forbes](http://github.com/clinton),
 [Perryn Fowler](http://github.com/perryn),
 [Niels Ganser](http://github.com/Nielsomat),
 [Jeremy Grant](http://github.com/jeremygrant),
 [Jon Guymon](http://github.com/gnarg),
 [James Healy](http://github.com/yob),
+[Ben Hoskings](http://github.com/benhoskings),
 [Evan David Light](http://github.com/elight),
 [Chris Lloyd](http://github.com/chrislloyd),
 [Adam Meehan](http://github.com/adzap),
 [Kyle Neath](http://github.com/kneath),
 [Lawrence Pit](http://github.com/lawrencepit),
+[Xavier Shay](http://github.com/xaviershay),
 [T.J. Sheehy](http://github.com/tjsheehy),
 [Roland Swingler](http://github.com/knaveofdiamonds),
 [Gareth Townsend](http://github.com/quamen),
 [Matt Wastrodowski](http://github.com/towski),
 [Ian White](http://github.com/ianwhite)
 
-Thanks to Thoughtbot's [Factory Girl](http://github.com/thoughtbot/factory_girl/tree/master). Machinist was written because I loved the idea behind Factory Girl, but I thought the philosophy wasn't quite right, and I hated the syntax.
+Thanks to Thoughtbot's [Factory
+Girl](http://github.com/thoughtbot/factory_girl/tree/master). Machinist was
+written because I loved the idea behind Factory Girl, but I thought the
+philosophy wasn't quite right, and I hated the syntax.
+

data/Rakefile

@@ -1,37 +1,30 @@
-require 'rake'
+require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name     = "machinist"
-    gem.summary  = "Fixtures aren't fun. Machinist is."
-    gem.email    = "pete@notahat.com"
-    gem.homepage = "http://github.com/notahat/machinist"
-    gem.authors  = ["Pete Yandell"]
-    gem.has_rdoc = false
-    gem.add_development_dependency "rspec", ">= 1.2.8"
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
-end
+require 'rake'
+require 'rspec/core/rake_task'
+require 'rdoc/task'
 
 
-require 'spec/rake/spectask'
-desc 'Run the specs.'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
-end
+RSpec::Core::RakeTask.new
 
-desc 'Run the specs with rcov.'
-Spec::Rake::SpecTask.new(:rcov) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.pattern = 'spec/**/*_spec.rb'
+RSpec::Core::RakeTask.new(:rcov) do |spec|
   spec.rcov = true
+  spec.rcov_opts = ['--exclude', 'spec', '--exclude', '.rvm']
 end
 
-task :spec => :check_dependencies
-
 desc 'Run the specs.'
-task :default => :spec
+task :default => :rcov
+
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'Machinist'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('lib')
+end
+
+task :notes do
+   system "grep -n -r 'FIXME\\|TODO' lib spec"
+end

data/VERSION

@@ -1 +1 @@
-1.0.6
+2.0

data/lib/generators/machinist/install/USAGE

@@ -0,0 +1,2 @@
+Description:
+    Copy Machinist files to your application.