cranky 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c7f6c5a28b743f350225d95efa1a42db23f299aa
-  data.tar.gz: 8713bef7ea202b009f97c89625403af0d00fd7d4
+  metadata.gz: fbcde86a6a73ee0148b12ed591e978d21521f5ba
+  data.tar.gz: 61a43c0743b8b333f85e3ec26f6604197086741b
 SHA512:
-  metadata.gz: 6f172f48edbf5686465205c5df9254a3b68b74cc47761d78c8d623511975e0dfc2141bd295c59a1af09ee250eaec743a317cbb14aec3ddb251ed80f58dc36ce7
-  data.tar.gz: 1b3f2af3d7bc85e6a25742aecf10cb27ef635cb4c78622d9e4ddb7bfe4361ad8bb9c8adbd5ed02b602aa921895b25759ab282b20b93d536f66f19b8897e5e5d8
+  metadata.gz: bf660e5eb16c325dc12f2c6f52839f6b2c5268a0d647729d5cb7b11f5bd9dcd55eb464609d57ffc3ef671b0def15abba10571c141e383e30029d59bd4696e5b6
+  data.tar.gz: ce11711bca5aa5de02f02d33305074e025147727ef13f425837e0182522cf119330bd38d19eb2e8bd5b46e3a23e44fd1d3a136e9a9b2486fc63bbfcd25848a70

data/README.md

@@ -70,7 +70,7 @@ Cranky allows you to build factories via std Ruby methods, like this...
 # factories/my_factories.rb
 class Cranky::Factory     # Your factory must reopen Cranky::Factory
 
-  # Simple factory method to create a user instance, you would call this via Factory.build(:user)
+  # Simple factory method to create a user instance, you would call this via crank(:user)
   def user
     # Define attributes via a hash, generate the values any way you want
     define :name    => "Jimmy",               
@@ -79,7 +79,7 @@ class Cranky::Factory     # Your factory must reopen Cranky::Factory
            :address => default_address         # Call your own helper methods to wire up your associations
   end
 
-  # Easily create variations via the inherit helper, callable via Factory.build(:admin)
+  # Easily create variations via the inherit helper, callable via crank(:admin)
   def admin
     inherit(:user, :role => "admin")
   end
@@ -89,12 +89,12 @@ class Cranky::Factory     # Your factory must reopen Cranky::Factory
     @default_address ||= create(:address) 
   end
   
-  # Alternatively loose the DSL altogether and define the factory yourself, still callable via Factory.build(:address)
+  # Alternatively loose the DSL altogether and define the factory yourself, still callable via crank(:address)
   def address
     a = Address.new
     a.street = "192 Broadway"
     a.city = options[:city] || "New York"   # You can get any caller overrides via the options hash
-    a                                       # Only rule is the method must return the generated object 
+    a                                       # Only rule is that the method must return the generated object 
   end
 
 end
@@ -109,8 +109,8 @@ This is where Cranky really shines, if you can create Ruby methods you can prett
 The only rules are:
 
 1. Your factory must reopen the Cranky::Factory class
-2. Your factory method must return the object you wanted to create
-3. You can access the overrides passed in via options[:key]. (not really a rule!) 
+2. Your factory method must return the object you wanted to create (or an array containing a collection of them)
+3. You can access the overrides passed in via `options[:key]` or `fetch(:key)`. (not really a rule!)
 
 So for example to create a simple user factory...
 
@@ -118,13 +118,16 @@ So for example to create a simple user factory...
 # factories/my_factories.rb
 class Cranky::Factory
 
-  # Simple factory method to create a user instance, you would call this via Factory.build(:user)
+  # Simple factory method to create a user instance, you would call this via crank(:user)
   def user
-    u       = User.new
-    u.name  = options[:name] || "Jimmy"                 # Use the passed in name if present, or the default
-    u.email = options[:email] || "jimmy#{n}@home.com"   # Give each user a unique email address
-    u.role  = options[:role] || "pleb"
-    u
+    User.new do |u|
+      u.name  = options[:name] || "Jimmy"                 # Use the passed in name if present, or the default
+      u.nickname  = fetch(:nickname, 'Silencer')          # Use the passed in nickname if present, or the default
+      u.phone  = fetch(:phone, 'phoneless')               # Use the passed in phone if present, or the default
+
+      u.email = fetch(:email) { "jimmy#{n}@home.com" }    # Give each user a unique email address
+      u.role  = fetch(:role, 'pleb')
+    end
   end
 
 end
@@ -144,12 +147,12 @@ class Cranky::Factory
   end
 
   def user
-    u         = User.new
-    u.name    = options[:name] || "Jimmy"
-    u.email   = options[:email] || "jimmy#{n}@home.com"
-    u.role    = options[:role] || "pleb"
-    u.address = default_address
-    u
+    User.new do |u|
+      u.name    = fetch(:name, "Jimmy")
+      u.email   = fetch(:email) { "jimmy#{n}@home.com" }
+      u.role    = fetch(:role, "pleb")
+      u.address = fetch(:address) { default_address }
+    end
   end
 
   # Create the address factory in the same way
@@ -172,30 +175,30 @@ end
 You can pass additional arguments to your factories via the overrides hash...
 
 ~~~ruby
-Factory.build(:user, :new_address => true)
+crank(:user, :new_address => true)
 
 def user
-  u         = User.new
-  u.name    = options[:name] || "Jimmy"
-  u.email   = options[:email] || "jimmy#{n}@home.com"
-  u.role    = options[:role] || "pleb"
-  u.address = options[:new_address] ? create(:address) : default_address
-  u
+  User.new do |u|
+    u.name    = fetch(:name, "Jimmy")
+    u.email   = fetch(:email) { "jimmy#{n}@home.com" }
+    u.role    = fetch(:role, "pleb")
+    u.address = options[:new_address] ? create(:address) : default_address
+  end
 end
 ~~~
 
 You can use traits...
 
 ~~~ruby
-Factory.build(:user, traits: [:admin, :manager])
+crank(:user, traits: [:admin, :manager])
 
 def user
-  u         = User.new
-  u.name    = options[:name] || "Jimmy"
-  u.email   = options[:email] || "jimmy#{n}@home.com"
-  u.role    = options[:role] || "pleb"
-  u.address = options[:new_address] ? create(:address) : default_address
-  u
+  User.new do |u|
+    u.name    = fetch(:name, "Jimmy")
+    u.email   = fetch(:email) { "jimmy#{n}@home.com" }
+    u.role    = fetch(:role, "pleb")
+    u.address = options[:new_address] ? create(:address) : default_address
+  end
 end
 
 def apply_trait_admin_to_user(user)
@@ -210,13 +213,73 @@ end
 You can create collections...
 
 ~~~ruby
-Factory.create(:users_collection)
+crank(:users_collection)
 
 def users_collection
   3.time.map { build(:user) }
 end
 ~~~
 
+## Linting Factories
+
+Cranky allows for linting known factories:
+
+~~~ruby
+Factory.lint!
+~~~
+
+`Factory.lint!` creates each factory and catches any exceptions raised during the creation process. `Cranky::Linter::InvalidFactoryError` is raised with a list of factories (and corresponding exceptions) for factories which could not be created.
+
+Recommended usage of `Factory.lint!` is to run this in a task before your test suite is executed. Running it in a `before(:suite)`, will negatively impact the performance of your tests when running single tests.
+
+Example Rake task:
+
+~~~ruby
+# lib/tasks/factory_girl.rake
+namespace :cranky do
+  desc "Verify that all factories are valid"
+  task lint: :environment do
+    if Rails.env.test?
+      begin
+        DatabaseCleaner.start
+        Factory.lint!
+      ensure
+        DatabaseCleaner.clean
+      end
+    else
+      system("bundle exec rake cranky:lint RAILS_ENV='test'")
+    end
+  end
+end
+~~~
+
+After calling `Factory.lint!`, you'll likely want to clear out the database, as records will most likely be created. The provided example above uses the database_cleaner gem to clear out the database; be sure to add the gem to your Gemfile under the appropriate groups.
+
+You can lint factories selectively by passing only factories you want linted:
+
+~~~ruby
+factories_to_lint = Factory.factory_names.reject do |name|
+  name =~ /^old_/
+end
+
+Factory.lint! factories_to_lint
+~~~
+
+This would lint all factories that aren't prefixed with `old_`.
+
+Traits can also be linted. This option verifies that each
+and every trait of a factory generates a valid object on its own. This is turned on by passing traits: true to the lint method:
+
+~~~ruby
+Factory.lint! traits: true
+~~~
+
+This can also be combined with other arguments:
+
+~~~ruby
+Factory.lint! factories_to_lint, traits: true
+~~~
+
 ## Helpers
 
 Of course its nice to get some help...
@@ -244,7 +307,7 @@ If you like you can generate attributes with a block:
 ~~~ruby
 def user
   define :name    => "Jimmy",
-         :email   => lambda{|u| "#{u.name.downcase}@home.com"},
+         :email   => -> { |u| "#{u.name.downcase}@home.com" },
          :role    => "pleb",
          :address => default_address
 end
@@ -266,7 +329,7 @@ end
 If for any reason you want to have your factory method named differently from the model it instantiates you can pass in a :class attribute to the define method...
 
 ~~~ruby
-# Called via Factory.create(:jimmy)
+# Called via crank(:jimmy)
 def jimmy
   u = define :class   => :user, 
              :name    => "Jimmy",
@@ -281,7 +344,7 @@ end
 You can inherit from other factories via the inherit method. So for example to create an admin user you might do...
 
 ~~~ruby
-# Called via Factory.create(:admin)
+# Called via crank(:admin)
 def admin
   inherit(:user, :role => "admin")  # Pass in any attribute overrides you want
 end
@@ -308,11 +371,11 @@ end
 Sometimes it is useful to be warned that your factory is generating invalid instances (although quite often your tests may intentionally generate invalid instances, so use this with care). By turning on debug the Factory will raise an error if the generated instance is invalid...
 
 ~~~ruby
-Factory.debug(:user)   # A replacement for Factory.build, with validation warnings enabled
+Factory.debug(:user)   # A replacement for Factory.build, with validation errors enabled
 Factory.debug!(:user)  # Likewise for Factory.create
 ~~~
 
-Note that this relies on the instance having a valid? method, so in practice this may only work with Rails.
+Note that this relies on the instance having a valid? method, so in practice this may only work with models that include ActiveModel::Validations.
 
 ### Attributes For
 

data/lib/cranky.rb

@@ -1,5 +1,6 @@
 require 'cranky/version'
 require 'cranky/job'
+require 'cranky/linter'
 require 'cranky/factory'
 
 # Instantiate a factory, this enables an easy drop in for tests written for Factory Girl  

data/lib/cranky/factory.rb

@@ -1,7 +1,7 @@
 module Cranky
-  class Factory
+  class FactoryBase
 
-    attr_writer :debug
+    TRAIT_METHOD_REGEXP = /apply_trait_(\w+)_to_(\w+)/.freeze
 
     def initialize
       # Factory jobs can be nested, i.e. a factory method can itself invoke another factory method to
@@ -22,6 +22,12 @@ module Cranky
       item
     end
 
+    def create!(what, overrides={})
+      item = build(what, overrides)
+      Array(item).each(&:save!)
+      item
+    end
+
     # Reset the factory instance, clear all instance variables
     def reset
       self.instance_variables.each do |var|
@@ -57,6 +63,35 @@ module Cranky
       item
     end
 
+    # Look for errors in factories and (optionally) their traits.
+    # Parameters:
+    # factory_names - which factories to lint; omit for all factories
+    # options:
+    #   traits : true - to lint traits as well as factories
+    def lint!(factory_names: nil, traits: false)
+      factories_to_lint = Array(factory_names || self.factory_names)
+      strategy = traits ? :factory_and_traits : :factory
+      Linter.new(self, factories_to_lint, strategy).lint!
+    end
+
+    def factory_names
+      public_methods(false).reject {|m| TRAIT_METHOD_REGEXP === m  }
+    end
+
+    def traits_for(factory_name)
+      regexp = /^apply_trait_(\w+)_to_#{factory_name}$/.freeze
+      trait_methods = public_methods(false).select {|m| regexp === m  }
+      trait_methods.map {|m| regexp.match(m)[1] }
+    end
+
+    def fetch(*args)
+      if block_given?
+        options.fetch(*args, &Proc.new)
+      else
+        options.fetch(*args)
+      end
+    end
+
     private
 
       def apply_traits(what, item)
@@ -118,5 +153,7 @@ module Cranky
 
   end
 
-end
+  class Factory < FactoryBase
+  end
 
+end

data/lib/cranky/linter.rb

@@ -0,0 +1,101 @@
+module Cranky
+  class Linter
+
+    def initialize(factory, factories_to_lint, linting_strategy)
+      @factory = factory
+      @factories_to_lint = factories_to_lint
+      @linting_method = "lint_#{linting_strategy}"
+      @invalid_factories = calculate_invalid_factories
+    end
+
+    def lint!
+      if invalid_factories.any?
+        raise InvalidFactoryError, error_message
+      end
+    end
+
+    attr_reader :factories_to_lint, :invalid_factories
+    private :factories_to_lint, :invalid_factories
+
+    private
+
+    def calculate_invalid_factories
+      factories_to_lint.reduce(Hash.new([])) do |result, factory|
+        errors = send(@linting_method, factory)
+        result[factory] |= errors unless errors.empty?
+        result
+      end
+    end
+
+    # Raised when any factory is considered invalid
+    class InvalidFactoryError < RuntimeError; end
+
+    class FactoryError
+      def initialize(wrapped_error, factory_name)
+        @wrapped_error = wrapped_error
+        @factory_name  = factory_name
+      end
+
+      def message
+        message = @wrapped_error.message
+        "* #{location} - #{message} (#{@wrapped_error.class.name})"
+      end
+
+      def location
+        @factory_name
+      end
+    end
+
+    class FactoryTraitError < FactoryError
+      def initialize(wrapped_error, factory_name, trait_name)
+        super(wrapped_error, factory_name)
+        @trait_name = trait_name
+      end
+
+      def location
+        "#{@factory_name}+#{@trait_name}"
+      end
+    end
+
+    def lint_factory(factory_name)
+      result = []
+      begin
+        @factory.create!(factory_name)
+      rescue => error
+        result |= [FactoryError.new(error, factory_name)]
+      end
+      result
+    end
+
+    def lint_traits(factory_name)
+      result = []
+      @factory.traits_for(factory_name).each do |trait_name|
+        begin
+          @factory.create!(factory_name, traits: trait_name)
+        rescue => error
+          result |=
+              [FactoryTraitError.new(error, factory_name, trait_name)]
+        end
+      end
+      result
+    end
+
+    def lint_factory_and_traits(factory_name)
+      errors = lint_factory(factory_name)
+      errors |= lint_traits(factory_name)
+      errors
+    end
+
+    def error_message
+      lines = invalid_factories.map do |_factory, exceptions|
+        exceptions.map(&:message)
+      end.flatten
+
+      <<-ERROR_MESSAGE.strip
+The following factories are invalid:
+
+#{lines.join("\n")}
+      ERROR_MESSAGE
+    end
+  end
+end

data/lib/cranky/version.rb

@@ -1,3 +1,3 @@
 module Cranky
-  VERSION = "0.5.0"
+  VERSION = "1.0.0"
 end

data/spec/cranky_spec.rb

@@ -2,7 +2,44 @@ require "spec_helper"
 
 describe "The Cranky factory" do
 
-  before(:each) do
+  describe '#factory_names' do
+    it 'returns an array of names of defined factories' do
+      Factory.factory_names.should eq [:user,
+                                       :address,
+                                       :users_collection,
+                                       :user_manually,
+                                       :user_by_define,
+                                       :admin_manually,
+                                       :admin_by_define,
+                                       :user_hash,
+                                       :invalid_user]
+    end
+  end
+
+  describe '#traits_for' do
+    it 'returns an array of trait names defined for the given factory' do
+      Factory.traits_for(:user_manually).should eq ['manager']
+    end
+  end
+
+  describe '#create!' do
+    context 'given invalid record' do
+      let(:factory_name) { :invalid_user }
+
+      it 'raises an error if validation failed' do
+        expect { Factory.create!(factory_name) }.to raise_error('Validation failed: {:required_attr=>["can\'t be blank"]}')
+      end
+    end
+
+    context 'given valid record' do
+      let(:factory_name) { :user }
+
+      it 'creates object' do
+        result = nil
+        expect { result = Factory.create!(factory_name) }.to_not raise_error
+        result.should be_saved
+      end
+    end
   end
 
   it "is alive" do
@@ -37,10 +74,10 @@ describe "The Cranky factory" do
   end
 
   it "clears all instance variables when reset" do
-    Factory.some_instance_variable = true
-    Factory.some_instance_variable.should == true
+    Factory.instance_variable_set('@some_instance_variable', true)
+    Factory.instance_variable_get('@some_instance_variable').should be_true
     Factory.reset
-    Factory.some_instance_variable.should == nil
+    Factory.instance_variable_get('@some_instance_variable').should be_nil
   end
 
   it "can create items using the define helper or manually" do
@@ -79,7 +116,7 @@ describe "The Cranky factory" do
   describe "debugger" do 
 
     it "raises an error if the factory produces an invalid object when enabled (rails only)" do
-      expect { Factory.debug(:user) }.to raise_error(
+      expect { Factory.debug(:user, required_attr: nil) }.to raise_error(
         'Oops, the User created by the Factory has the following errors: {:required_attr=>["can\'t be blank"]}'
       )
     end
@@ -147,7 +184,7 @@ describe "The Cranky factory" do
   end
 
   it "returns nothing extra in the attributes" do
-    crank(:user_attrs).size.should == 5
+    crank(:user_attrs).size.should == 6
   end
 
   specify "attributes for works with factory methods using inherit" do

data/spec/linter_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe 'Factory.lint' do
+  it 'raises when a factory is invalid' do
+    error_message = <<-ERROR_MESSAGE.strip
+The following factories are invalid:
+
+* user_hash - undefined method `save!' for [:name, "Fred"]:Array (NoMethodError)
+* invalid_user - Validation failed: {:required_attr=>["can't be blank"]} (RuntimeError)
+    ERROR_MESSAGE
+
+    expect do
+      Factory.lint!
+    end.to raise_error Cranky::Linter::InvalidFactoryError, error_message
+  end
+
+  it 'does not raise when all factories are valid' do
+    expect { Factory.lint!(factory_names: [:admin_manually, :address]) }.not_to raise_error
+  end
+
+  describe "trait validation" do
+    context "enabled" do
+      it "raises if a trait produces an invalid object" do
+        error_message = <<-ERROR_MESSAGE.strip
+The following factories are invalid:
+
+* user+invalid - Validation failed: {:required_attr=>["can't be blank"]} (RuntimeError)
+* user_hash - undefined method `save!' for [:name, "Fred"]:Array (NoMethodError)
+* invalid_user - Validation failed: {:required_attr=>["can't be blank"]} (RuntimeError)
+        ERROR_MESSAGE
+
+        expect do
+          Factory.lint!(traits: true)
+        end.to raise_error Cranky::Linter::InvalidFactoryError, error_message
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -19,6 +19,13 @@ class TestClass
     @saved = true
   end
 
+  def save!
+    if invalid?
+      raise "Validation failed: #{errors.messages}"
+    end
+    save
+  end
+
   def saved?
     !!@saved
   end
@@ -38,7 +45,6 @@ class User < TestClass
   attr_accessor :address
 end
 
-
 class Address < TestClass
   attr_accessor :address
   attr_accessor :city
@@ -47,32 +53,32 @@ end
 # Some basic factory methods
 class Cranky::Factory
 
-  attr_accessor :some_instance_variable
-
   def user_manually
-    u = User.new    
-    u.name = "Fred"
-    u.role = options[:role] || :user
-    u.unique = "value#{n}"
-    u.email = "fred@home.com"
-    u.address = Factory.build(:address)
+    u = User.new
+    u.name = fetch(:name, 'Fred')
+    u.role = fetch(:role) { :user }
+    u.unique = fetch(:unique) { "value#{n}" }
+    u.email = fetch(:email) { "fred@home.com" }
+    u.address = fetch(:address) { Factory.build(:address) }
+    u.required_attr = true
     u
   end
 
   def user_by_define
-    u = define :class => :user, 
+    u = define :class => :user,
                :name => "Fred",
                :role => :user,
                :unique => "value#{n}",
                :email => "fred@home.com",
-               :address => Factory.create(:address)
+               :address => Factory.create(:address),
+               :required_attr => true
     u.argument_received = true if options[:argument_supplied]
     u
   end
   alias :user :user_by_define
 
   def admin_manually
-    inherit(:user_manually, :role => :admin)
+    inherit(:user_manually, role: :admin, required_attr: true)
   end
 
   def admin_by_define
@@ -81,7 +87,8 @@ class Cranky::Factory
 
   def address
     define :address => "25 Wisteria Lane",
-           :city => "New York"
+           :city => "New York",
+           :required_attr => true
   end
 
   def user_hash
@@ -97,4 +104,12 @@ class Cranky::Factory
   def apply_trait_manager_to_user_manually(user)
     user.role = :manager
   end
+
+  def apply_trait_invalid_to_user(user)
+    user.required_attr = nil
+  end
+
+  def invalid_user
+    inherit(:user, required_attr: false)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cranky
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-10 00:00:00.000000000 Z
+date: 2016-11-06 00:00:00.000000000 Z
 dependencies: []
 description: A very light yet powerful test factory framework with an extremely clean
   syntax that makes it very easy to define your factories.
@@ -27,8 +27,10 @@ files:
 - lib/cranky.rb
 - lib/cranky/factory.rb
 - lib/cranky/job.rb
+- lib/cranky/linter.rb
 - lib/cranky/version.rb
 - spec/cranky_spec.rb
+- spec/linter_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/ginty/cranky
 licenses: []
@@ -49,7 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.4
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.4
+rubygems_version: 2.6.7
 signing_key: 
 specification_version: 4
 summary: A very light yet powerful test factory framework.