manufactory 0.0.1 → 0.0.2

data/LICENSE

@@ -1,3 +1,6 @@
+Manufactory was originaly imported from Machinist by Peter Yandell
+which is under MIT license as well, so the copyrights are:
+Copyright (c) 2008 Peter Yandell
 Copyright (c) 2009 Jakub Stastny
 
 Permission is hereby granted, free of charge, to any person obtaining

data/README.textile

@@ -1,12 +1,12 @@
 h1. About
 
-Manufactory is a minimalistic and clean rewrite of machinist with some improvements.
+Manufactory is a minimalistic and clean rewrite of manufactory with some improvements.
 
 h1. What is different?
 
 h2. Real DataMapper Support
 
-Machinist doesn't work with DataMapper right now. It's not a machinist problem, it's DataMapper issue, but who cares, it just doesn't work.
+Manufactory doesn't work with DataMapper right now. It's not a manufactory problem, it's DataMapper issue, but who cares, it just doesn't work.
 
 h2. Initialization
 
@@ -29,3 +29,288 @@ PaymentType.blueprint(:paypel, PaymentType.blueprint)
   name "PayPal"
   shortcut nil
 end
+
+
+
+
+
+
+
+Manufactory 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)
+      end
+    end
+
+You tell Manufactory how to do this with blueprints:
+
+    require 'manufactory/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
+    end
+  
+    Post.blueprint do
+      title
+      author
+      body
+    end
+  
+    Comment.blueprint do
+      post
+      author_name  { Sham.name }
+      author_email { Sham.email }
+      body
+    end
+    
+
+Download & Install
+==================
+
+### Installing as a Rails plugin
+
+    ./script/plugin install git://github.com/botanicus/manufactory.git
+      
+### Installing as a Gem
+
+    sudo gem install manufactory
+
+### Setting up your project
+
+Create a `blueprints.rb` file to hold your blueprints in your test (or spec) directory. It should start with:
+
+    require 'manufactory/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`):
+
+    require File.expand_path(File.dirname(__FILE__) + "/blueprints")
+
+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:
+
+    config.before(:all)    { Sham.reset(:before_all)  }
+    config.before(:each)   { Sham.reset(:before_each) }
+
+    
+Documentation
+=============
+
+Sham - Generating Attribute Values
+----------------------------------
+
+Sham lets you generate random but repeatable unique attributes values.
+
+For example, you could define a way to generate random names as:
+
+    Sham.name { (1..10).map { ('a'..'z').to_a.rand }.join }
+
+Then, to generate a name, call:
+
+    Sham.name
+
+So why not just define a helper method to do this? Sham ensures two things for you:
+
+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.
+
+    Sham.name {|index| "Name #{index}" }
+    
+If you want to allow duplicate values for a sham, you can pass the `:unique` option:
+
+    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
+
+
+Blueprints - Generating Objects
+-------------------------------
+
+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.
+
+A simple blueprint might look like this:
+
+    Post.blueprint do
+      title  { Sham.title }
+      author { Sham.name }
+      body   { Sham.body }
+    end
+
+You can then construct a Post from this blueprint with:
+    
+    Post.make
+    
+When you call `make`, Manufactory 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.
+
+You can override values defined in the blueprint by passing a hash to make:
+
+    Post.make(:title => "A Specific Title")
+    
+If you don't supply a block for an attribute in the blueprint, Manufactory 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:
+
+    Post.blueprint do
+      title
+      author { Sham.name }
+      body   { "Post by #{author}" }
+    end
+        
+
+### 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
+    end
+
+    User.blueprint(:admin) do
+      name  { Sham.name + " (admin)" }
+      admin { true }
+    end
+
+Calling:
+
+    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.
+
+
+### Belongs\_to Associations
+
+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 }
+    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)
+    
+Manufactory will not call the blueprint block for the post attribute, so this won't generate two posts.
+    
+Manufactory 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
+
+    
+### Other Associations
+
+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:
+
+    def make_post_with_comments(attributes = {})
+      post = Post.make(attributes)
+      3.times { post.comments.make }
+      post
+    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:
+
+    def make_post_with_comments
+      Post.make(attributes) do |post|
+        3.times { post.comments.make }
+      end
+    end
+
+
+### Using Blueprints in Rails Controller Tests
+
+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.)
+
+
+### Blueprints on Plain Old Ruby Objects
+
+Manufactory also works with plain old Ruby objects. Let's say you have a class like:
+
+    class Post
+      attr_accessor :title
+      attr_accessor :body
+    end
+    
+You can then do the following in your `blueprints.rb`:
+
+    require 'manufactory/object'
+    
+    Post.blueprint do
+      title "A title!"
+      body  "A body!"
+    end
+
+
+Thanks to Thoughtbot's [Factory Girl](http://github.com/thoughtbot/factory_girl/tree/master). Manufactory 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/lib/manufactory.rb

@@ -1,8 +1,12 @@
 # encoding: utf-8
 
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
+
+require "manufactory/dsl"
 require "manufactory/sham"
 
 module Manufactory
+  VERSION ||= "0.0.2"
   # ActiveRecord::Base.extend(Manufactory::Blueprints)
   # Post.blueprint(&block)
   module Blueprints
@@ -18,12 +22,24 @@ module Manufactory
     end
   end
 
+  module ManufactoryMixin
+    include Manufactory::Blueprints
+    def make(adapter, name = :default, attributes = Hash.new, &block)
+      name, attributes = :default, name if name.is_a?(Hash) && attributes.empty?
+      callables = self.blueprints[name]
+      adapter = adapter.new(self, name, callables)
+      instance = adapter.run(attributes)
+      instance.instance_eval(&block) if block_given?
+      return instance
+    end
+  end
+
   # Adapter.new(User, :admin, age: 24)
   class Adapter
     attr_reader :klass, :name, :callables
     def initialize(klass, name, callables)
-      @klass   = klass
-      @name    = name
+      @klass     = klass
+      @name      = name
       @callables = callables
     end
 
@@ -31,102 +47,25 @@ module Manufactory
       blueprint = klass.blueprints[name.to_sym]
       raise "No blueprint #{name} for class #{klass}" if blueprint.nil?
       default_attributes = Hash.new
+      object = klass.new(default_attributes) # will be discarded at the end
       self.callables.each do |callable|
-        default_attributes.merge!(DSL.new(self, callable).run)
+        default_attributes.merge!(DSL.new(self, object, callable).run)
       end
       self.initialize_object(klass, default_attributes, attributes)
     end
 
-    protected
-    def initialize_object(klass, default_attributes, attributes)
-      klass.new(default_attributes.merge(attributes))
-    end
-  end
-
-  # DSL is used to execute the blueprint and construct an object.
-  # The blueprint is instance_eval'd against the Lathe.
-  class DSL
-    attr_reader :adapter, :blueprint
-    def initialize(adapter, blueprint)
-      @adapter   = adapter
-      @blueprint = blueprint
-    end
-
-    def run
-      self.instance_eval(&self.blueprint)
-      assigned_attributes
-    end
-
-    def object
-      yield @object if block_given?
-      @object
-    end
-    
-    def method_missing(symbol, *args, &block)
-      if attribute_assigned?(symbol)
-        # If we've already assigned the attribute, return that.
-        @object.send(symbol)
-      elsif @adapter.has_association?(@object, symbol) && !nil_or_empty?(@object.send(symbol))
-        # If the attribute is an association and is already assigned, return that.
-        @object.send(symbol)
-      else
-        # Otherwise generate a value and assign it.
-        assigned_attributes[symbol] = generate_attribute_value(symbol, *args, &block)
-      end
-    end
-
-    def assigned_attributes
-      @assigned_attributes ||= {}
-    end
-    
-    # Undef a couple of methods that are common ActiveRecord attributes.
-    # (Both of these are deprecated in Ruby 1.8 anyway.)
-    undef_method :id   if respond_to?(:id)
-    undef_method :type if respond_to?(:type)
-    
-  private
-    
-    def nil_or_empty?(object)
-      object.respond_to?(:empty?) ? object.empty? : object.nil?
-    end
-    
-    def attribute_assigned?(key)
-      assigned_attributes.has_key?(key.to_sym)
+    def has_association?(object, attribute)
+      false
     end
     
-    def generate_attribute_value(attribute, *args)
-      if block_given?
-        # If we've got a block, use that to generate the value.
-        yield
-      else
-        # Otherwise, look for an association or a sham.
-        if @adapter.has_association?(object, attribute)
-          @adapter.class_for_association(object, attribute).make(args.first || {})
-        elsif args.empty?
-          Sham.send(attribute)
-        else
-          # If we've got a constant, just use that.
-          args.first
-        end
+    protected
+    def initialize_object(klass, default_attributes, attributes)
+      attributes = default_attributes.merge(attributes)
+      instance   = klass.new
+      attributes.each do |attribute, value|
+        instance.send("#{attribute}=", value)
       end
+      return instance
     end
-    
-  end
-
-  # This sets a flag that stops make from saving objects, so
-  # that calls to make from within a blueprint don't create
-  # anything inside make_unsaved.
-  def self.with_save_nerfed
-    begin
-      @@nerfed = true
-      yield
-    ensure
-      @@nerfed = false
-    end
-  end
-
-  @@nerfed = false
-  def self.nerfed?
-    @@nerfed
   end
 end