ianwhite-pickle 0.1.1 → 0.1.2

data/History.txt

@@ -1,3 +1,14 @@
+== 0.1.2
+
+* 2 major enhancements
+  * create your pickle steps with script/generate pickle
+  * Adapter based architecture, supports Machinist, FactoryGirl, and vanilla ActiveRecord
+  
+* 1 minor enhancement
+  * model_names now defaults to subclasses of AR::Base
+  * #original_model => #created_model
+
+
 == 0.1.1
 
 * 1 major enhancement:
@@ -6,6 +17,7 @@
 * 1 minor enhancement:
   * Added intentions for pickle in README.textile
 
+
 == Prior to gems
 
 * Initial release: everything is subject to sweeping change

data/README.textile

@@ -1,67 +1,98 @@
-h1. Pickle [Experimental: In development]
+h1. Pickle
 
-Stick this in vendor/plugins to have cucumber steps that create your models easily from factory_girl/machinist
+Stick this in vendor/plugins to have cucumber steps that create your models easily from factory_girl/machinist/active_record
 
 References to the models are stored, not for the purpose of checking the db (although you could use it for
 that), but for enabling easy reference to urls, and for building complex givens which require a bunch of
 models collaborating
-
-h2. Example
-
-If you have a user model, which has admin? and moderator? predicate methods
-and let's say you have an :admin, :user, and :moderator factory, you can do this in a Scenario:
-
-  And an admin exists
-  And a moderator exists
-  
-  # the following is just to show how refs work, obviously you'd not want to test this
-  Then the moderator should be a moderator
-  And the admin should be an admin
-  And the moderator should not be an admin
   
-h2. Usage
+h2. Get Started
 
   script/generate pickle
 
+Now have a look at features/step_definitions/pickle_steps.rb
+
 h2. API
 
 h3. Regexps for us in your own steps
 
-If you want to use pickle expressions in your own steps, make sure you 
-require pickle in that file
-
-  require 'pickle'
-
-For matching english versions of model names you get 
+For capturing english versions of model names you get 
 
-  #match_model, #capture_model
+  *CaptureModel*
 
-  Given /^#{capture_model} exists$/ do |model_name|
+<pre>
+  Given /^#{CaptureModel} exists$/ do |model_name|
     model(model_name).should_not == nil
   end
 
   Then /^I should be at the (.*?) page$/ |page|
-	if page =~ /#{match_model}'s/
-	  url_for(model(page.sub("'s",''))
-	else
-	  # ...
-	end
+  if page =~ /#{CaptureModel}'s/
+    url_for(model($1))
+  else
+    # ...
   end
-  
-For matching a field string, you get
+  end
+</pre>
 
-  #match_fields, #capture_fields
+For capturing a field string, you get
+
+*CaptureFields*
   
-  Given /^#{capture_model} exists with #{capture_fields}$/ do |model_name, fields|
+<pre>
+  Given /^#{CaptureModel} exists with #{CaptureFields}$/ do |model_name, fields|
     create_model(model_name, fields)
   end
-  
+</pre>
 Take a look at features/step_definitions/pickle_steps.rb for more examples
 
 h3. Creating and tracking models
 
- #create_model(<model_name>[, <field string>])
- 
- #find_model(<model_name>[, <field string>])
- 
- #model(<model_model>) # refers to a model that has already been created/found (ie. referred to in a scenario)
+h4. create_model(_model_name_[, _field_string_])
+
+This will create a model using the factory name, and optional model label, with the field_string provided.  The created model can be later referred to via its name.
+
+For example:
+
+<pre>
+  create_model 'a user'         					# => will create a User
+  create_model 'the user: "1"'      			# => will create a User, enabling later reference to it with 'user: "1"'
+  create_model 'the user', 'name: "Fred"'	# => will create a User with attributes {:name => "Fred"}
+</pre>
+
+If you don't use Machinist or FactoryGirl, you can still create models, but you must pass in all the fields required to make them valid.
+
+However, if you do use Machinist or FactoryGirl, then just use the factory or blueprint name, and will be super sweet.
+
+h4. find_model(_model_name_, _field_string_)
+
+This will find a model of the passed class matching the passed field string.  The found model can be later referred to by its name.
+
+For example:
+
+<pre>
+  find_model('a user', 'name: "Fred'")		# => find a user matching those attributes
+</pre>
+
+h4. model(_model_name_) 
+
+Refers to a model that has already been created/found (ie. referred to in a scenario)
+
+For example:
+
+<pre>
+  create_model('a user')
+  model('the user') # => refers to above user
+  model('a user')   # => refers to above user
+
+  create_model('a car: "herbie"')  		# => herbie
+  create_model('a car: "batmobile"')	# => the batmobile
+  model('the first car') 		# => herbie
+  model('the 2nd car') 			# => batmobile
+  model('the car "herbie")	# => herbie
+</pre>
+
+h4. created_model(_model_name_)
+
+*model* always pulls from the db to get a fresh copy.  If you need to access the originally created object for some reason (perhaps it has a one-time key on it that is used in a mailer for example), you can retreive it with *created_model*
+
+h4. more [TODO]

data/Todo.txt

@@ -1,5 +0,0 @@
-* make a gem release with version number
-
-* create a generator for the pickle steps
-
-* add machinist, and fallback to no factory pattern if none available

data/lib/pickle.rb

@@ -1,47 +1,19 @@
-# Pickle == cucumber + factory
-#
-# = Usage
-#   # in features/steps/_env.rb
-#   require 'pickle/steps'
-#
-# If you need to configure pickle, do it like this
-#
-#   Pickle::Config.map 'I|me|my', :to => 'user: "me"'
-#   require 'pickle/steps'
-module Pickle
-  module Version
-    Major = 0
-    Minor = 1
-    Tiny  = 1
-    
-    String = [Major, Minor, Tiny].join('.')
-  end
-    
-  module Config
-    class << self
-      attr_writer :model_names, :factory_names, :names, :mappings
-      
-      def model_names
-        @model_names ||= Dir["#{RAILS_ROOT}/app/models/**/*.rb"].reject{|f| f =~ /observer.rb$/}.map{|f| f.sub("#{RAILS_ROOT}/app/models/",'').sub(".rb",'')}
-      end
+require 'active_support'
+require 'pickle/adapter'
+require 'pickle/config'
+require 'pickle/parser'
+require 'pickle/parser/with_session'
+require 'pickle/session'
+require 'pickle/injector'
 
-      def factory_names
-        require 'factory_girl'
-        @factory_names ||= Factory.factories.keys.map(&:to_s)
-      end
+# make the parser aware of models in the session (for fields refering to models)
+Pickle::Parser.send :include, Pickle::Parser::WithSession
 
-      def names
-        @names ||= (model_names | factory_names)
-      end
-      
-      def mappings
-        @mappings ||= []
-      end
-      
-      def map(search, options)
-        raise ArgumentError, "Usage: map 'search', :to => 'replace'" unless search.is_a?(String) && options[:to].is_a?(String)
-        self.mappings << [search, options[:to]]
-      end
-    end
-  end
-end
+# inject the pickle session into integration session if we have one (TODO: inject into merb etc?)
+if defined?(ActionController::Integration::Session)
+  Pickle::Injector.inject Pickle::Session, :into => ActionController::Integration::Session
+end
+
+# shortcuts for useful regexps when defining pickle steps
+CaptureModel = Pickle.parser.capture_model
+CaptureFields = Pickle.parser.capture_fields

data/lib/pickle/adapter.rb

@@ -0,0 +1,86 @@
+module Pickle
+  # Abstract Factory adapter class, if you have a factory type setup, you
+  # can easily create an adaptor to make it work with Pickle.
+  #
+  # The factory adaptor must have a #factories class method that returns 
+  # its instances, and each instance must respond to a #name method which
+  # identifies the factory by name (default is attr_reader for @name), and a
+  # #create method which takes an optional attributes hash,
+  # and returns a newly created object
+  class Adapter
+    attr_reader :name
+    
+    def self.factories
+      raise NotImplementedError, "return an array of factory adapter objects"
+    end
+  
+    def create(attrs = {})
+      raise NotImplementedError, "create and return an object with the given attributes"
+    end
+    
+    # by default the models are active_record subclasses, but you can set this to whatever classes you want
+    class << self
+      attr_writer :model_classes
+      
+      def model_classes
+        @model_classes ||= returning(::ActiveRecord::Base.send(:subclasses)) do |classes|
+          defined?(CGI::Session::ActiveRecordStore::Session) && classes.delete(CGI::Session::ActiveRecordStore::Session)
+        end
+      end
+    end
+    
+    # machinist adapter
+    class Machinist < Adapter
+      def self.factories
+        factories = []
+        model_classes.each do |klass|
+          factories << new(klass, "make") if klass.instance_variable_get('@blueprint')
+          # if there are special make_special methods, add blueprints for them
+          klass.methods.select{|m| m =~ /^make_/ && m !~ /_unsaved$/}.each do |method|
+            factories << new(klass, method)
+          end
+        end
+        factories
+      end
+      
+      def initialize(klass, method)
+        @klass, @method = klass, method
+        @name = (@method =~ /make_/ ? "#{@method.sub('make_','')}_" : "") + @klass.name.underscore.gsub('/','_')
+      end
+      
+      def create(attrs = {})
+        @klass.send(@method, attrs)
+      end
+    end
+    
+    # factory-girl adapter
+    class FactoryGirl < Adapter
+      def self.factories
+        (::Factory.factories.keys rescue []).map {|key| new(key)}
+      end
+      
+      def initialize(key)
+        @name = key.to_s
+      end
+    
+      def create(attrs = {})
+        Factory.create(@name, attrs)
+      end
+    end
+        
+    # fallback active record adapter
+    class ActiveRecord < Adapter
+      def self.factories
+        model_classes.map {|klass| new(klass) }
+      end
+
+      def initialize(klass)
+        @klass, @name = klass, klass.name.underscore.gsub('/','_')
+      end
+
+      def create(attrs = {})
+        @klass.send(:create!, attrs)
+      end
+    end
+  end
+end

data/lib/pickle/config.rb

@@ -0,0 +1,51 @@
+require 'ostruct'
+
+module Pickle
+  def self.config(&block)
+    returning(@config ||= Config.new) do |config|
+      config.configure(&block) if block_given?
+    end
+  end
+  
+  class Config
+    attr_writer :adapters, :factories, :mappings
+    
+    def initialize(&block)
+      configure(&block) if block_given?
+    end
+    
+    def configure(&block)
+      yield(self)
+    end
+    
+    def adapters
+      @adapters ||= [:machinist, :factory_girl, :active_record]
+    end
+    
+    def adapter_classes
+      adapters.map {|a| a.is_a?(Class) ? a : "pickle/adapter/#{a}".classify.constantize}
+    end
+    
+    def factories
+      @factories ||= adapter_classes.reverse.inject({}) do |factories, adapter|
+        factories.merge(adapter.factories.inject({}){|h, f| h.merge(f.name => f)})
+      end
+    end
+
+    def factory_names
+      factories.keys
+    end
+    
+    def mappings
+      @mappings ||= []
+    end
+    
+    # Usage: map 'me', 'myself', 'I', :to => 'user: "me"'
+    def map(*args)
+      options = args.extract_options!
+      raise ArgumentError, "Usage: map 'search' [, 'search2', ...] :to => 'replace'" unless args.any? && options[:to].is_a?(String)
+      search = args.size == 1 ? args.first.to_s : "(?:#{args.join('|')})"
+      self.mappings << OpenStruct.new(:search => search, :replace => options[:to])
+    end
+  end
+end

data/lib/pickle/injector.rb

@@ -1,18 +1,18 @@
 module Pickle
   module Injector
-    def self.inject(session, options = {})
+    def self.inject(session_class, options = {})
       target = options[:into] || ActionController::Integration::Session
-      session_name = session.name.underscore.gsub('/','_')
+      session_method = options[:name] || session_class.name.underscore.gsub('/','_')
+      session_options = options[:options] || {}
       
-      target.class_eval <<-end_eval, __FILE__, __LINE__
-        def #{session_name}
-          @#{session_name} ||= #{session.name}.new
-        end
-      end_eval
-
-      delegate_methods = session.instance_methods - Object.instance_methods
-      delegate_methods << {:to => session_name}
-      target.delegate *delegate_methods
+      # create a session object on demand (in target)
+      target.send(:define_method, session_method) do
+        instance_variable_get("@#{session_method}") || instance_variable_set("@#{session_method}", session_class.new(session_options))
+      end
+      
+      # delegate session methods to the session object (in target)
+      delegate_methods = session_class.public_instance_methods - Object.instance_methods
+      target.delegate *(delegate_methods + [{:to => session_method}])
     end
   end
 end

data/lib/pickle/parser.rb

@@ -1,49 +1,38 @@
+require 'pickle/parser/matchers'
+
 module Pickle
-  module Parser
-    module Match
-      Ordinal = '(?:\d+(?:st|nd|rd|th))'
-      Index   = "(?:first|last|#{Ordinal})"
-      Prefix  = '(?:1 |a |an |another |the |that )'
-      Quoted  = '(?:[^\\"]|\\.)*'
-      Name    = '(?::? "' + Quoted + '")'
-      
-      # model matching - depends on Parse::Config, so load before this if non standard config requried
-      ModelMapping  = "(?:#{Pickle::Config.mappings.map(&:first).map{|s| "(?:#{s})"}.join('|')})"
-      ModelName     = "(?:#{Pickle::Config.names.map{|n| n.to_s.gsub('_','[_ ]').gsub('/','[:\/ ]')}.join('|')})"
-      IndexedModel  = "(?:(?:#{Index} )?#{ModelName})"
-      NamedModel    = "(?:#{ModelName}#{Name}?)"
-      Model         = "(?:#{ModelMapping}|#{Prefix}?(?:#{IndexedModel}|#{NamedModel}))"
-      Field         = '(?:\w+: (?:' + Model + '|"' + Quoted + '"))'
-      Fields        = "(?:#{Field}, )*#{Field}"
-      
-    end
+  def self.parser(options = {})
+    @parser ||= Parser.new(options)
+  end
+  
+  class Parser
+    include Matchers
     
-    # these are expressions which capture a sub expression
-    module Capture
-      Ordinal = '(?:(\d+)(?:st|nd|rd|th))'
-      Name    = '(?::? "(' + Match::Quoted + ')")'
-      Field   = '(?:(\w+): "(' + Match::Quoted + ')")'
+    attr_reader :config
+    
+    def initialize(options = {})
+      @config = options[:config] || Pickle.config
     end
     
     # given a string like 'foo: "bar", bar: "baz"' returns {"foo" => "bar", "bar" => "baz"}
     def parse_fields(fields)
       if fields.blank?
         {}
-      elsif fields =~ /^#{Match::Fields}$/
-        fields.scan(/(#{Match::Field})(?:,|$)/).inject({}) do |m, match|
+      elsif fields =~ /^#{match_fields}$/
+        fields.scan(/(#{match_field})(?:,|$)/).inject({}) do |m, match|
           m.merge(parse_field(match[0]))
         end
       else
-        raise ArgumentError, "The fields string is not in the correct format.\n\n'#{fields}' did not match: #{Match::Fields}" 
+        raise ArgumentError, "The fields string is not in the correct format.\n\n'#{fields}' did not match: #{match_fields}" 
       end
     end
     
     # given a string like 'foo: "bar"' returns {key => value}
     def parse_field(field)
-      if field =~ /^#{Capture::Field}$/
+      if field =~ /^#{capture_key_and_value_in_field}$/
         { $1 => $2 }
       else
-        raise ArgumentError, "The field argument is not in the correct format.\n\n'#{field}' did not match: #{Match::Field}"
+        raise ArgumentError, "The field argument is not in the correct format.\n\n'#{field}' did not match: #{match_field}"
       end
     end
     
@@ -52,30 +41,28 @@ module Pickle
       str.to_s.gsub(' ','_').underscore
     end
     
+    # return [factory_name, name or integer index]
+    def parse_model(model_name)
+      apply_mappings!(model_name)
+      if /#{capture_index} #{capture_factory}$/ =~ model_name
+        [canonical($2), parse_index($1)]
+      elsif /#{capture_factory}#{capture_name_in_label}?$/ =~ model_name
+        [canonical($1), canonical($2)]
+      end
+    end
+  
     def parse_index(index)
       case index
       when '', /last/ then -1
-      when /#{Capture::Ordinal}/ then $1.to_i - 1
+      when /#{capture_number_in_ordinal}/ then $1.to_i - 1
       when /first/ then 0
       end
     end
-    
+
   private
-    # return [factory, name or integer index]
-    def parse_model(name)
-      apply_mappings!(name)
-      if /(#{Match::ModelName})#{Capture::Name}$/ =~ name
-        [canonical($1), canonical($2)]
-      elsif /(#{Match::Index}) (#{Match::ModelName})$/ =~ name
-        [canonical($2), parse_index($1)]
-      else
-        /(#{Match::ModelName})#{Capture::Name}?$/ =~ name && [canonical($1), canonical($2)]
-      end
-    end
-    
     def apply_mappings!(string)
-      Pickle::Config.mappings.each do |(search, replace)|
-        string.sub! /^(?:#{search})$/, replace
+      config.mappings.each do |mapping|
+        string.sub! /^#{mapping.search}$/, mapping.replace
       end
     end
   end