genspec 0.2.0.prerails3.2 → 0.2.0

data/lib/genspec/generator_example_group.rb

@@ -16,10 +16,21 @@ module GenSpec
       #   pass :object => true at the end;
       #
       # Ex:
-      #  
+      #
+      #   with_args '--orm', 'active_record' do
+      #     it "should use activerecord" do
+      #       # . . .
+      #     end
+      #   end
+      #
+      #   with_args '--size', 5, :object => true do
+      #     # . . .
+      #   end
+      #
       def with_args(*args, &block)
         options = args.extract_options!
         args = args.flatten.collect { |c| c.to_s } unless options[:object]
+        
         if block_given?
           context "with arguments #{args.inspect}" do
             with_args(args, options)
@@ -30,6 +41,68 @@ module GenSpec
         end
       end
       
+      # Sets the input stream for this generator.
+      #
+      # Ex:
+      #
+      #   with_input <<-end_input do
+      #     y
+      #     n
+      #     a
+      #   end_input
+      #     it "should overwrite, then skip, then overwrite all" do
+      #       # . . .
+      #     end
+      #   end
+      #
+      def with_input(string, &block)
+        if block_given?
+          context "with input string #{string.inspect}" do
+            with_input string
+            instance_eval &block
+          end
+        else
+          metadata[:generator_input] = string
+        end
+      end
+      
+      # Executes some code within the generator's source root
+      # prior to the generator actually running. Useful for
+      # setting up fixtures.
+      #
+      # Ex:
+      #
+      #   within_source_root do
+      #     touch "Gemfile"
+      #   end
+      #
+      # Optionally, the block may receive a single argument,
+      # which is the full path to the temporary directory
+      # representing the source root:
+      #
+      #   within_source_root do |tempdir|
+      #     # . . .
+      #   end
+      #
+      def within_source_root(&block)
+        metadata[:generator_init_block] = block
+      end
+      
+      # Returns an array of all init blocks from the topmost context down to this
+      # one, in that order. These blocks will be executed sequentially prior to
+      # each run of the generator.
+      def generator_init_blocks
+        result = []
+        result.concat superclass.generator_init_blocks if genspec_subclass?
+        result << metadata[:generator_init_block] if metadata[:generator_init_block]
+        result
+      end
+      
+      # Returns the generator arguments to be used for this context. If this context doesn't
+      # have any generator arguments, its superclass is checked, and so on until either the
+      # parent isn't a GenSpec or a set of arguments is found. Only the closest argument
+      # set is used; any sets specified above the discovered argument set are
+      # ignored.
       def generator_args
         return metadata[:generator_args] if metadata[:generator_args]
         
@@ -40,16 +113,45 @@ module GenSpec
         end
       end
       
+      # Returns the input stream to be used for this context. If this context doesn't
+      # have an input stream, its superclass is checked, and so on until either the
+      # parent isn't a GenSpec or an input stream is found. Only the closest input
+      # stream is used; any streams specified above the discovered input stream are
+      # ignored.
+      def generator_input
+        return metadata[:generator_input] if metadata[:generator_input]
+        
+        metadata[:generator_input] = if genspec_subclass?
+          superclass.generator_input
+        else
+          nil
+        end
+      end
+      
       alias with_arguments      with_args
       alias generator_arguments generator_args
       
+      # A hash containing the following:
+      #
+      #   :described   - the generator to be tested, or the string/symbol representing it
+      #   :args        - any arguments to be used when invoking the generator
+      #   :input       - a string to be used as an input stream, or nil
+      #   :init_blocks - an array of blocks to be invoked prior to running the generator
+      #
+      # This hash represents the +subject+ of the spec and this is the object that will
+      # ultimately be passed into the GenSpec matchers.
+      #
       def generator_descriptor
         {
           :described => target_generator,
-          :args => generator_args
+          :args => generator_args,
+          :input => generator_input,
+          :init_blocks => generator_init_blocks
         }
       end
       
+      # Traverses up the context tree to find the topmost description, which represents
+      # the controller to be tested or the string/symbol representing it.
       def target_generator
         if genspec_subclass?
           superclass.target_generator
@@ -58,6 +160,11 @@ module GenSpec
         end
       end
 
+      # Returns true if this object's superclass is also a GenSpec.
+      #
+      # When a context is created, rspec creates a class inheriting from the context's
+      # parent. Therefore, this method can be used to recurse up to the highest-level
+      # spec that still tests a generator.
       def genspec_subclass?
         superclass.include?(GenSpec::GeneratorExampleGroup)
       end

data/lib/genspec/matchers/base.rb

@@ -1,11 +1,14 @@
 module GenSpec
   module Matchers
     class Base
-      attr_reader :block, :generator, :args, :described
-      delegate :source_root, :to => :generator
+      attr_reader :block, :generator, :args, :init_blocks
       attr_reader :destination_root
       attr_accessor :error
       
+      def source_root
+        generator.source_root
+      end
+      
       def initialize(&block)
         @block = block if block_given?
         @matched = false
@@ -18,20 +21,27 @@ module GenSpec
       def matches?(generator)
         @described = generator[:described]
         @args = generator[:args]
+        @shell = GenSpec::Shell.new("", generator[:input] || "")
+        @init_blocks = generator[:init_blocks]
         
-        if @described.kind_of?(Array)
-          @generator = Rails::Generators.find_by_namespace(*@described)
+        if @described.kind_of?(Class)
+          @generator = @described
         else
-          @generator = Rails::Generators.find_by_namespace(@described)
+          if defined?(Rails)
+            @generator = Rails::Generators.find_by_namespace(@described)
+          else
+            @generator = Thor::Util.find_by_namespace(@described)
+          end
         end
         
         raise "Could not find generator: #{@described.inspect}" unless @generator
         
-        localize_generator!
         inject_error_handlers!
         invoking
         invoke
         matched?
+      ensure
+        complete
       end
       
       def matched?
@@ -47,7 +57,13 @@ module GenSpec
       end
       
       protected
+      # callback fired after matching process is complete, regardless of success, failure
+      # or error
+      def complete
+      end
+      
       # callback which fires just before a generator has been invoked.
+      # Allows matchers to inject whatever hooks they need into the generator.
       def invoking
       end
       
@@ -56,16 +72,6 @@ module GenSpec
       def generated
       end
       
-      def temporary_root
-        Dir.mktmpdir do |dir|
-          # need to copy a few files for some methods, ie route_resources
-          FileUtils.touch(File.join(dir, "Gemfile"))
-          
-          # all set.
-          yield dir
-        end
-      end
-      
       def spec_file_contents(filename)
         if @block
           content = File.read(filename)
@@ -73,28 +79,16 @@ module GenSpec
         end
       end
       
-      protected
+      def shell
+        @shell
+      end
+      
       # Causes errors not to be raised if a generator fails. Useful for testing output,
       # rather than results.
       def silence_errors!
         @errors_silenced = true
       end
       
-      def silence_thor!
-        @generator.instance_eval do
-          alias thor_method_added method_added
-
-          # to silence callbacks and errors about reserved keywords
-          def method_added(meth)
-          end
-        end
-        
-        yield
-        
-        # un-silence errors and callbacks
-        @generator.instance_eval { alias thor_method_added method_added }
-      end
-      
       private
       def check_for_errors
         # generation is complete - check for errors and re-raise it if it's there
@@ -102,47 +96,48 @@ module GenSpec
       end
       
       def invoke
-        temporary_root do |tempdir|
-          @destination_root = tempdir
-          @generator.start(@args || [], {:destination_root => destination_root})
-          check_for_errors
-          generated
+        Dir.mktmpdir do |tempdir|
+          FileUtils.chdir tempdir do
+            init_blocks.each do |block|
+              block.call(tempdir)
+            end
+          
+            @destination_root = tempdir
+            stdout, stderr, stdin = $stdout, $stderr, $stdin
+            $stdout, $stderr, $stdin = shell.output, shell.output, shell.input
+
+            begin
+              @generator.start(@args || [], {
+                :shell => @shell,
+                :destination_root => destination_root
+              })
+            ensure
+              $stdout, $stderr, $stdin = stdout, stderr, stdin
+            end
+          
+            check_for_errors
+            generated
+          end
         end
       end
       
       def inject_error_handlers!
-        silence_thor! do
-          @generator.class_eval do
+        interceptor = self
+        @generator.class_eval do
+          no_tasks do
             def invoke_with_genspec_error_handler(*names, &block)
               invoke_without_genspec_error_handler(*names, &block)
             rescue Thor::Error => err
-              self.class.interceptor.error = err
+              # self.class.interceptor.error = err
+              interceptor.error = err
               raise err
             end
-            
+          
             alias invoke_without_genspec_error_handler invoke
             alias invoke invoke_with_genspec_error_handler
           end
         end
       end
-      
-      def localize_generator!
-        # subclass the generator in question so that aliasing its methods doesn't
-        # impact the root generator (which would be a Bad Thing for other specs)
-        gen = @generator
-        generator = Class.new(gen)
-        # we have to force the name in order to avoid nil errors within Thor.
-        generator.instance_eval "def self.name; #{gen.name.inspect}; end"
-        @generator = generator
-
-        
-        # add self as the "interceptor" so that our generator's wrapper methods can
-        # gain access to this object.
-        def @generator.interceptor; @interceptor; end
-        def @generator.interceptor=(a); @interceptor = a; end
-    
-        @generator.interceptor = self
-      end
     end
   end
 end

data/lib/genspec/matchers/generation_method_matcher.rb

@@ -1,4 +1,23 @@
 class GenSpec::Matchers::GenerationMethodMatcher < GenSpec::Matchers::Base
+  # The modules whose public instance methods will be converted into GenSpec matchers.
+  # See #generation_methods for details.
+  #
+  # By default, this includes all of the following:
+  #
+  # * +Thor::Actions+
+  # * +Rails::Generators::Actions+
+  # * +Rails::Generators::Migration+
+  #
+  # If Rails has not been loaded, (e.g. you are testing Thor generators, not Rails generators),
+  # the Rails modules are silently ignored.
+  #
+  # You can add any additional modules to this list. Note that you should list them 
+  # in the form of a String representing the module name, rather than adding the modules
+  # themselves. This allows you to add them prior to actually load them.
+  #
+  # This will only take effect _before_ the specs have been executed; it is best done from
+  # within the +spec_helper.rb+ file during the load process.
+  #
   GENERATION_CLASSES = [ 'Thor::Actions', 'Rails::Generators::Actions', 'Rails::Generators::Migration' ]
   
   attr_reader :method_name, :method_args
@@ -46,42 +65,80 @@ class GenSpec::Matchers::GenerationMethodMatcher < GenSpec::Matchers::Base
   
   protected
   def invoking
-    silence_thor! do
-      generator.class_eval <<-end_code
-        def #{method_name}_with_intercept(*argus, &block)
-          expected_args = self.class.interceptor.method_args
+    method_name = self.method_name
+    interceptor = self
+    generator.class_eval do
+      no_tasks do
+        define_method :"#{method_name}_with_intercept" do |*argus, &block|
+          expected_args = interceptor.method_args
           if expected_args.length > 0
             actual_args = argus[0...expected_args.length]
             if actual_args == expected_args
-              self.class.interceptor.match!
+              interceptor.match!
             else
-              self.class.interceptor.report_actual_args(actual_args)
+              # we've already matched the method, and there are no expected args.
+              interceptor.report_actual_args actual_args
             end
           else
-            # we've already matched the method, and there are no expected args.
-            self.class.interceptor.match!
+            interceptor.match!
           end
-
-          #{method_name}_without_intercept(*argus, &block)
+          
+          send(:"#{method_name}_without_intercept", *argus, &block)
         end
-      end_code
-      generator.send(:alias_method_chain, method_name, :intercept)
-    end    
+        
+        alias_method_chain :"#{method_name}", :intercept
+      end
+    end
+  end
+  
+  def complete
+    # we couldn't subclass the generator anonymously because this dirties the
+    # rails generator search process. Instead we'll rely on manually de-aliasing
+    # the method being monitored.
+    method_name = self.method_name
+    generator.class_eval do
+      no_tasks do
+        alias_method :"#{method_name}", :"#{method_name}_without_intercept"
+      end
+    end
   end
   
   public
   class << self
+    # Returns all public instance methods found in the modules listed in 
+    # GENERATION_CLASSES. This is the list of methods that will be converted
+    # into matchers, which can be used like so:
+    #
+    #   subject.should create_file(. . .)
+    #
+    # See also GENERATION_CLASSES
+    #
     def generation_methods
       GENERATION_CLASSES.inject([]) do |arr, mod|
-        mod = mod.constantize if mod.kind_of?(String)
+        if mod.kind_of?(String)
+          next arr if !defined?(Rails) && mod =~ /^Rails/
+          mod = mod.constantize
+        end
         arr.concat mod.public_instance_methods.collect { |i| i.to_s }.reject { |i| i =~ /=/ }
         arr
-      end
+      end.uniq.sort
     end
     
+    # called from GenSpec::Matchers#call_action
+    # 
+    # example:
+    #   subject.should call_action(:create_file, ...)
+    #
+    # equivalent to:
+    #   subject.should GenSpec::Matchers::GenerationMethodMatcher.for_method(:create_file, ...)
+    #
     def for_method(which, *args, &block)
-      if generation_methods.include?(which.to_s) then self.new(which, *args, &block)
-      else nil
+      if generation_methods.include?(which.to_s)
+        new(which, *args, &block)
+      else
+        raise "Could not find a matcher for '#{which.inspect}'!\n\n" \
+              "If this is a custom action, try adding the Thor Action module to GenSpec:\n\n" \
+              "  GenSpec::Matchers::GenerationMethodMatcher::GENERATION_CLASSES << 'My::Actions'"
       end
     end
   end

data/lib/genspec/matchers/output_matcher.rb

@@ -2,7 +2,7 @@ module GenSpec
   module Matchers
     class OutputMatcher < GenSpec::Matchers::Base
       def output
-        Thor::Base.shell.output.string
+        shell.output.string
       end
       
       def initialize(text_or_regexp)

data/lib/genspec/matchers/result_matcher.rb

@@ -9,10 +9,20 @@ module GenSpec
       end
       
       def generated
-        path = File.join(destination_root, filename)
-        if File.exist?(path)
+        if filename
+          path = File.join(destination_root, filename)
+          if File.exist?(path)
+            match!
+            spec_file_contents(path)
+          end
+        else
+          # there was no error, so in the context of
+          # "should generate", it most certainly
+          # generated.
           match!
-          spec_file_contents(path)
+          if block
+            block.call
+          end
         end
       end
       

data/lib/genspec/matchers.rb

@@ -7,21 +7,26 @@ module GenSpec
   module Matchers
     # Valid types: :dependency, :class_collisions, :file, :template, :complex_template, :directory, :readme,
     # :migration_template, :route_resources
-    def generate(kind, *args, &block)
+    #
+    # Examples:
+    #   subject.should generate(:file, ...)
+    #   subject.should generate("vendor/plugins/will_paginate/init.rb")
+    #
+    def generate(kind = nil, *args, &block)
       if kind.kind_of?(Symbol)
+        # subject.should generate(:file, ...)
         call_action(kind, *args, &block)
       else
+        # subject.should generate("vendor/plugins/will_paginate/init.rb")
         GenSpec::Matchers::ResultMatcher.new(kind, &block)
       end
     end
     
+    # ex:
+    #   subject.should call_action(:create_file, ...)
+    #
     def call_action(kind, *args, &block)
-      unless matcher = GenSpec::Matchers::GenerationMethodMatcher.for_method(kind, *args, &block)
-        raise "Could not find a matcher for '#{kind.inspect}'!\n\n" \
-              "If this is a custom action, try adding the Thor Action module to GenSpec:\n\n" \
-              "GenSpec::Matchers::GenerationMethodMatcher::GENERATION_CLASSES << 'My::Actions'"
-      end
-      matcher
+      GenSpec::Matchers::GenerationMethodMatcher.for_method(kind, *args, &block)
     end
     
     # This tests the content sent to the command line, instead of the generated product.
@@ -33,10 +38,16 @@ module GenSpec
     class << self
       def add_shorthand_methods(base)
         instance_methods = base.instance_methods.collect { |m| m.to_s }
+        
+        # ex:
+        #   subject.should create_file(...)
+        # equivalent to:
+        #   subject.should call_action(:create_file, ...)
+        
         GenSpec::Matchers::GenerationMethodMatcher.generation_methods.each do |method_name|
           # don't overwrite existing methods. since the user expects this to fire FIRST,
-          # it's as if this method's been "overridden".
-          next if instance_methods.include?(method_name)
+          # it's as if this method's been "overridden". See #included and #extended.
+          next if instance_methods.include?(method_name.to_s)
           base.class_eval <<-end_code
             def #{method_name}(*args, &block)                    # def create_file(*args, &block)
               call_action(#{method_name.inspect}, *args, &block) #   call_action('create_file', *args, &block)
@@ -44,16 +55,6 @@ module GenSpec
           end_code
         end 
       end
-      
-      # this is to delay definition of the generation method matchers (like #create_file) until
-      # after initialization, in order to facilitate custom Thor actions.
-      def included(base)
-        add_shorthand_methods(base)
-      end
-      
-      def extended(base)
-        add_shorthand_methods(class << base; self; end)
-      end
     end
   end
 end

data/lib/genspec/shell.rb

@@ -1,10 +1,26 @@
+require 'thor/shell/basic'
+
 module GenSpec
   # Just like a Thor::Shell::Basic except that input and output are both redirected to
   # the specified streams. By default, these are initialized to instances of StringIO.
   class Shell < Thor::Shell::Basic
-    attr_accessor :input, :output
+    attr_accessor :stdin, :stdout, :stderr
+    alias_method :input, :stdin
+    alias_method :input=, :stdin=
+    alias_method :output, :stdout
+    alias_method :output=, :stdout=
+    
+    def ask(statement, color = nil)
+      say "#{statement} ", color
+      response = stdin.gets
+      if response
+        response.strip
+      else
+        raise "Asked '#{statement}', but input.gets returned nil!"
+      end
+    end
     
-    def initialize(output="", input="")
+    def initialize(output = "", input = "")
       super()
       new(output, input)
     end
@@ -13,81 +29,10 @@ module GenSpec
     def new(output="", input="")
       init_stream(:output, output)
       init_stream(:input,  input)
+      @stderr = @stdout
       self
     end
-    
-    # Ask something to the user and receives a response.
-    #
-    # ==== Example
-    # ask("What is your name?")
-    #
-    def ask(statement, color=nil)
-      say("#{statement} ", color)
-      input.gets.strip
-    end
-
-    # Say (print) something to the user. If the sentence ends with a whitespace
-    # or tab character, a new line is not appended (print + flush). Otherwise
-    # are passed straight to puts (behavior got from Highline).
-    #
-    # ==== Example
-    # say("I know you knew that.")
-    #
-    def say(message="", color=nil, force_new_line=(message.to_s !~ /( |\t)$/))
-      message  = message.to_s
-      message  = set_color(message, color) if color
-
-      if force_new_line
-        output.puts(message)
-      else
-        output.print(message)
-        output.flush
-      end
-    end
 
-    # Prints a table.
-    #
-    # ==== Parameters
-    # Array[Array[String, String, ...]]
-    #
-    # ==== Options
-    # ident<Integer>:: Ident the first column by ident value.
-    #
-    def print_table(table, options={})
-      return if table.empty?
-
-      formats, ident = [], options[:ident].to_i
-      options[:truncate] = terminal_width if options[:truncate] == true
-
-      0.upto(table.first.length - 2) do |i|
-        maxima = table.max{ |a,b| a[i].size <=> b[i].size }[i].size
-        formats << "%-#{maxima + 2}s"
-      end
-
-      formats[0] = formats[0].insert(0, " " * ident)
-      formats << "%s"
-
-      table.each do |row|
-        sentence = ""
-
-        row.each_with_index do |column, i|
-          sentence << formats[i] % column.to_s
-        end
-
-        sentence = truncate(sentence, options[:truncate]) if options[:truncate]
-        output.puts sentence  
-      end
-    end
-
-    # Called if something goes wrong during the execution. This is used by Thor
-    # internally and should not be used inside your scripts. If someone went
-    # wrong, you can always raise an exception. If you raise a Thor::Error, it
-    # will be rescued and wrapped in the method below.
-    #
-    def error(statement)
-      output.puts statement
-    end
-    
     private
     def init_stream(which, value)
       if value.kind_of?(String)

data/lib/genspec/version.rb

@@ -0,0 +1,12 @@
+module GenSpec
+  class Version
+    MAJOR = 0
+    MINOR = 2
+    PATCH = 0
+    RELEASE = nil
+    
+    STRING = (RELEASE ? [MAJOR, MINOR, PATCH, RELEASE] : [MAJOR, MINOR, PATCH]).join('.')
+  end
+  
+  VERSION = Version::STRING
+end