sample_models 0.9.0

data/.gitignore

@@ -0,0 +1,4 @@
+*~
+*.log
+spec/*.log
+pkg/*

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Francis Hwang
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+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

@@ -0,0 +1,345 @@
+SampleModels
+============
+
+A library for making it extremely fast for Rails developers to set up and save ActiveRecord instances when writing test cases. It aims to:
+
+* meet all your validations automatically
+* only make you specify the attributes you care about
+* give you a rich set of features so you can specify associations as concisely as possible
+* do this with as little configuration as possible
+
+Feature overview
+================
+
+Let's say you've got a set of models that look like this:
+
+    class BlogPost < ActiveRecord::Base
+      has_many   :blog_post_tags
+      has_many   :tags, :through => :blog_post_tags
+      belongs_to :user
+      
+      validates_presence_of :title, :user_id
+    end
+
+    class BlogPostTag < ActiveRecord::Base
+      belongs_to :blog_post
+      belongs_to :tag
+    end
+
+    class Tag < ActiveRecord::Base
+      validates_uniqueness_of :tag
+      
+      has_many :blog_post_tags
+      has_many :blog_posts, :through => :blog_post_tags
+    end 
+
+    class User < ActiveRecord::Base
+      has_many :blog_posts
+    
+      validates_inclusion_of    :gender, :in => %w(f m)
+      validates_uniqueness_of   :email, :login
+      # from http://github.com/alexdunae/validates_email_format_of
+      validates_email_format_of :email
+    end
+
+You can get a valid instance of a BlogPost by calling BlogPost.sample in a test environment:
+
+    blog_post1 = BlogPost.sample
+    puts blog_post1.title             # => some non-empty string
+    puts blog_post1.user.is_a?(User)  # => true
+
+    user1 = User.sample
+    puts user1.email                  # => will be a valid email 
+    puts user1.gender                 # => will be either 'f' or 'm'
+
+Since SampleModels figures out validations and associations from your ActiveRecord class definitions, it can usually fill in the required values without any configuration at all.
+    
+If you care about specific fields, you can specify them like so:
+
+    blog_post2 = BlogPost.sample(:title => 'What I ate for lunch')
+    puts blog_post2.title             # => 'What I ate for lunch'
+    puts blog_post2.user.is_a?(User)  # => true
+
+You can specify associated records in the sample call:
+
+    bill = User.sample(:first_name => 'Bill')
+    bills_post = BlogPost.sample(:user => bill)
+    
+    funny = Tag.sample(:tag => 'funny')
+    sad = Tag.sample(:tag => 'sad')
+    funny_yet_sad = BlogPost.sample(:tags => [funny, sad])
+    
+You can also specify associated records by passing in hashes or arrays:
+
+    bills_post2 = BlogPost.sample(:user => {:first_name => 'Bill'})
+    puts bills_post2.user.first_name  # => 'Bill'
+    
+    funny_yet_sad2 = BlogPost.sample(
+      :tags => [{:tag => 'funny'}, {:tag => 'sad'}]
+    )
+    puts funny_yet_sad2.tags.size     # => 2
+    
+You can also specify associated records by passing them in at the beginning of the argument list, if there's only one association that would work with the record's class:
+
+    jane = User.sample(:first_name => 'Jane')
+    BlogPost.sample(jane, :title => 'What I ate for lunch')
+
+Instance attributes
+=========================
+
+By default, SampleModels sets each attribute on a record to a non-blank value that matches the database type. They'll often be nonsensical values like "first_name 5", but the assumption is that if you didn't specify a value, you don't really care what it is as long as it validates. Non-trivial codebases routinely end up having models with many attributes, and when you find yourself writing a test with that model, you may only care about one or two attributes in that test case. SampleModels aims to let you specify only those important attributes while letting SampleModels take care of everything else.
+
+SampleModels reads your validations to get hints about how to craft an instance that will be valid. The current supported validations are:
+
+validates_email_format_of
+-------------------------
+
+If you use the validates_email_format_of plugin at [http://github.com/alexdunae/validates_email_format_of](http://github.com/alexdunae/validates_email_format_of), SampleModels will ensure that the attribute in question is a valid email address.
+
+validates_presence_of
+---------------------
+
+SampleModels already sets values to be non-blank, but this validation comes in handy if you have an `attr_accessor`:
+
+    class UserWithPassword < ActiveRecord::Base
+      attr_accessor :password
+      
+      validates_presence_of :password
+    end
+    
+    user_with_password = UserWithPassword.sample
+    puts user_with_password.password  # => Some non-blank string
+
+
+validates_inclusion_of
+----------------------
+
+SampleModels will set the attribute to one of the specified values.
+
+
+validates_uniqueness_of
+-----------------------
+
+SampleModels will ensure that new instances will have different values for attributes where uniqueness is required, as discussed below under "New records vs. old records."
+
+
+New records vs. old records
+===========================
+
+Most of the time, consecutive calls to `sample` will return the same record, because this is marginally faster, and the design assumption is that if you're calling `sample` you don't care which instance you get as long as it satisfies the attributes you specified.
+
+    user1 = User.sample
+    user2 = User.sample
+    puts (user1 == user2)   # probably true
+    
+    rick1 = User.sample(:first_name => 'Rick')
+    puts (user1 == rick1)   # probably false, but you never know
+    
+    rick2 = User.sample(:first_name => 'Rick')
+    puts (rick1 == rick2)   # probably true
+    
+If having a distinct record is important to the test, you should call `create_sample`, which always saves a new record in the DB and returns it.
+
+    blog_post1 = BlogPost.sample
+    blog_post2 = BlogPost.create_sample
+    puts (blog_post1 == blog_post2)   # will always be false
+
+If the class validates the uniqueness of a field, that field will always be distinct for every new instance returned by `create_sample`.
+
+    tag1 = Tag.sample
+    tag2 = Tag.create_sample
+    puts (tag1 == tag2)           # will always be false
+    puts (tag1.tag == tag2.tag)   # will always be false, because Tag validates
+                                  # the uniqueness of the `tag` attribute
+
+Associations
+============
+
+If your application has an extensive data model, setting up associations for a test case can be an extremely tedious endeavor. SampleModels aims to make this process easy on the programmer and easy on the reader with a number of features.
+
+Belongs-to associations
+-----------------------
+As demonstrated above, belongs_to associations are automatically set like any other attribute:
+
+    blog_post = BlogPost.sample
+    puts blog_post.user.is_a?(User)   # => true
+    
+You can also specify these associations as if you were calling `new` or `create!`:
+
+    kelley = User.sample(:first_name => 'Kelley')
+    BlogPost.sample(:user => kelley)
+    BlogPost.sample(:user_id => kelley.id)
+
+If you want, you can simply specify the record at the beginning of the argument list for `sample` or `create_sample`, and SampleModels will assign them to the appropriate association, as long as there's only one association that fits the class.
+
+    kim = User.sample(:first_name => 'Kim')
+    BlogPost.sample(kim, :title => 'funny')
+   
+You can do this with multiple belongs-to associations:
+    
+    class Network < ActiveRecord::Base
+    end
+    
+    class Show < ActiveRecord::Base
+      belongs_to :network
+    end
+        
+    class Video < ActiveRecord::Base
+      belongs_to :show
+      belongs_to :network
+    end
+    
+    amc = Network.sample(:name => 'AMC')
+    mad_men = Show.sample(:name => 'Mad Men')
+    video = Video.sample(amc, mad_men, :name => 'The Suitcase')
+    
+If you want, you can simply specify the important attributes of the associated value, and SampleModels will stitch it all together for you:
+
+    blog_post = BlogPost.sample(:user => {:first_name => 'Bill'})
+    puts blog_post.user.first_name  # => 'Bill'
+
+You can combine the two syntaxes in deeper associations:
+
+    bb_episode = Video.sample(:show => [amc, {:name => 'Breaking Bad'}])
+    puts bb_episode.show.network.name  # => 'AMC'
+    puts bb_episode.show.name     # => 'Breaking Bad'
+
+Polymorphic belongs-to associations
+-----------------------------------
+
+In the case of a polymorphic belongs-to association, SampleModels will attach any record it can find, of any model class.
+
+    class Bookmark < ActiveRecord::Base
+      belongs_to :bookmarkable, :polymorphic => true
+    end
+    
+    bookmark = Bookmark.sample
+    puts bookmark.bookmarkable.class  # could be any model class
+    
+Of course, you can specify the polymorphic association yourself if that's important to the test.
+
+    blog_post = BlogPost.sample(:title => 'Read me later')
+    Bookmark.sample(:bookmarkable => blog_post)
+    
+You can also configure the default class of this polymorphic association with `default_class`, explained below under "Configuration".    
+
+Has-many associations
+---------------------
+
+You can set a has-many association with an array of instances, as you'd do with `new` or `create!`:
+
+    funny = Tag.sample(:tag => 'funny')
+    sad = Tag.sample(:tag => 'sad')
+    funny_yet_sad1 = BlogPost.sample(:tags => [funny, sad])
+    
+You can also pass hashes to specify the records:
+
+    funny_yet_sad2 = BlogPost.sample(
+      :tags => [{:tag => 'funny'}, {:tag => 'sad'}]
+    )
+    
+Or you can combine the two if that's more convenient:
+    
+    funny_yet_sad3 = BlogPost.sample(:tags => [{:tag => 'sad'}, funny])
+
+Configuration
+=============
+
+The aim of SampleModels is to require as little configuration as possible -- you'll typically find that most of your models won't need any configuration at all. However, there are a few hooks for when you're trying to accommodate advanced creational behavior.
+
+before_save
+-----------
+
+With `before_save` you can specify a block that runs before the record is saved. For example, let's say you've got Users, Appointments, and Calendars, and an Appointment should have the same User as the Calendar it belongs to. You can set this behavior with `before_save`:
+
+    # app/models/appointment.rb
+    class Appointment < ActiveRecord::Base
+      belongs_to :calendar
+      belongs_to :user
+      
+      def validate
+        if user_id != calendar.user_id
+          errors.add_to_base("Calendar has a different user than me")
+        end
+      end
+    end
+    
+    # app/models/calendar.rb
+    class Calendar < ActiveRecord::Base
+      has_many    :appointments
+      belongs_to  :user
+    end
+    
+    # test/test_helper.rb
+    SampleModels.configure(Appointment) do |appt|
+      appt.before_save do |appt_record|
+        appt_record.user_id = appt_record.calendar.user_id
+      end
+    end
+
+You can also take a second argument, which will pass in the hash that was used during the call to `sample` or `create_sample`.
+
+    SampleModels.configure(Appointment) do |appt|
+      appt.before_save do |appt_record, sample_attrs|
+        unless sample_attrs.has_key?(:user) or sample_attrs.has_key?(:user_id)
+          appt_record.user_id = appt_record.calendar.user_id
+        end
+      end
+    end
+
+default
+-------
+`default` will set default values for the field in question.
+
+    SampleModels.configure(Category) do |category|
+      category.parent.default nil
+    end
+
+    SampleModels.configure(Video) do |video|
+      video.view_count.default 0
+    end
+    
+A word to the wise: Be sparing with these global defaults. It's easy to tell yourself "Oh, this should be the default value everywhere" -- and then a day later find yourself wanting to override the default all over the place. In many cases you many want to used named samples (see below) instead.
+
+default_class
+-------------
+By default, SampleModels fills polymorphic associations with any record, chosen practically at random. You may want to specify this to a more sensible default:
+
+    SampleModels.configure(Bookmark) do |bookmark|
+      bookmark.bookmarkable.default_class BlogPost
+    end
+
+force_unique
+------------
+Use `force_unique` if you want to ensure that for every newly created instance, the field will be unique. This has the same effect as `validates_uniqueness_of`, but won't change how production code behaves.
+
+    SampleModels.configure(BlogPost) do |bp|
+      bp.published_at.force_unique
+    end
+
+
+Named samples
+=============
+Named samples can be used to pre-set values for commonly used combinations of attributes.
+
+    SampleModels.configure(BlogPost) do |bp|
+      bp.funny_sample :title => 'Laugh already', :average_rating => 3.0
+      bp.sad_sample :title => 'Boo hoo', :average_rating => 2.0
+    end
+    
+    bp1 = BlogPost.sample(:funny)
+    puts bp1.title   # => 'Laugh already'
+
+    bp2 = BlogPost.create_sample(:funny)
+    puts bp2.title      # => 'Laugh already'
+    puts (bp1 == bp2)   # => false
+    
+You can override individual attributes, as well:
+
+    bp3 = BlogPost.sample(:funny, :average_rating => 4.0)
+    puts bp3.average_rating   # => 4.0
+
+About
+=====
+
+Copyright (c) 2010 Francis Hwang, released under the MIT license.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rubygems'
+gem 'rspec'
+require 'spec/rake/spectask'
+
+desc 'Default: run specs.'
+task :default => [:test, :spec]
+
+desc "Run all specs"
+task :spec do
+  cmd = "spec spec/sample_models_spec.rb"
+  puts cmd
+  puts `#{cmd}`
+end
+
+desc "Run all tests"
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*.rb']
+end
+
+desc 'Generate documentation for the sample_models plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SampleModels'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sample_models"
+    gem.summary = %Q{A library for making it extremely fast for Rails developers to set up and save ActiveRecord instances when writing test cases}
+    gem.description = %Q{
+A library for making it extremely fast for Rails developers to set up and save ActiveRecord instances when writing test cases. It aims to:
+
+* meet all your validations automatically
+* only make you specify the attributes you care about
+* give you a rich set of features so you can specify associated values as concisely as possible
+* do this with as little configuration as possible
+}
+    gem.email = "francis.hwang@profitably.com"
+    gem.homepage = "http://github.com/fhwang/sample_models"
+    gem.authors = ["Francis Hwang"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/init.rb

@@ -0,0 +1,2 @@
+# Include hook code here
+require 'sample_models'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/sample_models/creation.rb

@@ -0,0 +1,116 @@
+module SampleModels
+  class Creation
+    def initialize(sampler, attrs)
+      @sampler = sampler
+      @orig_attrs = HashWithIndifferentAccess.new attrs
+      @attrs = Attributes.new(@sampler, attrs)
+    end
+    
+    def model
+      SampleModels.models[@sampler.model_class]
+    end
+    
+    def polymorphic_assoc_value(assoc)
+      if klass = @sampler.polymorphic_default_classes[assoc.name]
+        klass.sample
+      else
+        SampleModels.samplers.values.map(&:model_class).detect { |m|
+          m != @sampler.model_class
+        }.sample
+      end
+    end
+    
+    def run
+      @instance = @sampler.model_class.new @attrs
+      save!
+      update_associations
+      @instance
+    end
+    
+    def save!
+      @sampler.save!(@instance, @orig_attrs)
+    end
+    
+    def update_associations
+      needs_another_save = false
+      model.belongs_to_associations.each do |assoc|
+        unless @instance.send(assoc.name) || @attrs.has_key?(assoc.name) ||
+               @attrs.has_key?(assoc.association_foreign_key)
+          if assoc.options[:polymorphic]
+            needs_another_save = true
+            @instance.send "#{assoc.name}=", polymorphic_assoc_value(assoc)
+          elsif @sampler.model_class != assoc.klass
+            needs_another_save = true
+            @instance.send "#{assoc.name}=", assoc.klass.sample
+          end
+        end
+      end
+      save! if needs_another_save
+    end
+    
+    class Attributes < HashWithIndifferentAccess
+      def initialize(sampler, hash)
+        @sampler = sampler
+        hash = Sampler.reify_association_hashes model, hash
+        super(hash)
+        fill_based_on_validations
+        fill_based_on_configured_defaults
+        model.columns.each do |column|
+          unless has_key?(column.name)
+            fill_based_on_column_type column
+          end
+        end
+      end
+    
+      def model
+        SampleModels.models[@sampler.model_class]
+      end
+    
+      def fill_based_on_column_type(column)
+        case column.type
+        when :string
+          fill_based_on_string_column_type(column)
+        when :integer
+          unless model.belongs_to_associations.any? { |assoc|
+            assoc.primary_key_name == column.name
+          }
+            self[column.name] = 1
+          end
+        when :datetime
+          self[column.name] = Time.now.utc
+        when :float
+          self[column.name] = 1.0
+        end
+      end
+    
+      def fill_based_on_configured_defaults
+        @sampler.configured_default_attrs.each do |attr, val|
+          self[attr] = val unless has_key?(attr)
+        end
+      end
+    
+      def fill_based_on_string_column_type(column)
+        unless model.belongs_to_associations.any? { |assoc|
+          assoc.options[:polymorphic] &&
+            assoc.options[:foreign_type] = column.name
+        }
+          self[column.name] = "#{column.name}"
+        end
+      end
+    
+      def fill_based_on_validations
+        model.validation_collections.each do |field, validation_collection|
+          assoc_key = nil
+          if assoc = model.belongs_to_associations.detect { |a|
+            a.association_foreign_key == field.to_s
+          }
+            assoc_key = assoc.name
+          end
+          unless has_key?(field) || (assoc_key && has_key?(assoc_key))
+            self[field] = validation_collection.satisfying_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sample_models/finder.rb

@@ -0,0 +1,81 @@
+module SampleModels
+  class Finder
+    def initialize(model, attrs)
+      @model = model
+      attrs = Sampler.reify_association_hashes @model, attrs.clone
+      @attrs = HashWithIndifferentAccess.new attrs
+      @ar_query = ARQuery.new
+    end
+    
+    def add_empty_has_many_subselect(assoc)
+      value = @attrs[assoc.name]
+      not_matching_subselect = @model.construct_finder_sql(
+        :select => "#{@model.table_name}.id", :joins => assoc.name,
+        :group => "#{@model.table_name}.id"
+      )
+      @ar_query.condition_sqls << "id not in (#{not_matching_subselect})"
+    end
+    
+    def add_non_empty_has_many_subselect(assoc)
+      @ar_query.condition_sqls << has_many_matching_subselect(assoc)
+      value = @attrs[assoc.name]
+      not_matching_subselect = @model.construct_finder_sql(
+        :select => "#{@model.table_name}.id", :joins => assoc.name,
+        :conditions => [
+          "#{assoc.klass.table_name}.id not in (?)", value.map(&:id)
+        ],
+        :group => "#{@model.table_name}.id"
+      )
+      @ar_query.condition_sqls << "id not in (#{not_matching_subselect})"
+    end
+    
+    def attach_belongs_to_associations_to_query
+      @model.belongs_to_associations.each do |assoc|
+        if @attrs.keys.include?(assoc.name.to_s)
+          @ar_query.conditions[assoc.primary_key_name] = if @attrs[assoc.name]
+            @attrs[assoc.name].id
+          else
+            @attrs[assoc.name]
+          end
+        end
+      end
+    end
+    
+    def attach_non_associated_attrs_to_query
+      @attrs.each do |k,v|
+        if @model.column_names.include?(k.to_s)
+          @ar_query.conditions[k] = v
+        end
+      end
+    end
+    
+    def has_many_matching_subselect(assoc)
+      value = @attrs[assoc.name]
+      matching_inner_subselect = @model.construct_finder_sql(
+        :select =>
+          "#{@model.table_name}.id, count(#{assoc.klass.table_name}.id) as count",
+        :joins => assoc.name,
+        :conditions => [
+          "#{assoc.klass.table_name}.id in (?)", value.map(&:id)
+        ],
+        :group => "#{@model.table_name}.id"
+      )
+      "id in (select matching.id from (#{matching_inner_subselect}) as matching where matching.count = #{value.size})"
+    end
+
+    def instance
+      attach_non_associated_attrs_to_query
+      attach_belongs_to_associations_to_query
+      @model.has_many_associations.each do |assoc|
+        if @attrs.keys.include?(assoc.name.to_s)
+          if @attrs[assoc.name].empty?
+            add_empty_has_many_subselect assoc
+          else
+            add_non_empty_has_many_subselect assoc
+          end
+        end
+      end
+      @model.first @ar_query.to_hash
+    end
+  end
+end