bmabey-spork 0.4.4 → 0.5.9

data/lib/spork/app_framework/rails_stub_files/application.rb

@@ -0,0 +1,3 @@
+# This is a stub used to help Spork delay the loading of the real ApplicationController
+class ::ApplicationController < ActionController::Base
+end

data/lib/spork/app_framework/rails_stub_files/application_controller.rb

@@ -0,0 +1,3 @@
+# This is a stub used to help Spork delay the loading of the real ApplicationController
+class ::ApplicationController < ActionController::Base
+end

data/lib/spork/app_framework/rails_stub_files/application_helper.rb

@@ -0,0 +1,3 @@
+# This is a stub used to help Spork delay the loading of the real ApplicationHelper
+module ::ApplicationHelper
+end

data/lib/spork/app_framework/unknown.rb

@@ -0,0 +1,6 @@
+# This is used if no supported appliction framework is detected
+class Spork::AppFramework::Unknown < Spork::AppFramework
+  def entry_point
+    nil
+  end
+end

data/lib/spork/custom_io_streams.rb

@@ -0,0 +1,25 @@
+# This class is mainly used for testing.
+# When included (and used), it gives us an opportunity to stub out the output streams used for a given class
+module Spork::CustomIOStreams
+  def self.included(klass)
+    klass.send(:extend, ::Spork::CustomIOStreams::ClassMethods)
+  end
+  
+  def stderr
+    self.class.stderr
+  end
+
+  def stdout
+    self.class.stdout
+  end
+  
+  module ClassMethods
+    def stderr
+      $stderr
+    end
+  
+    def stdout
+      $stdout
+    end
+  end
+end

data/lib/spork/diagnoser.rb

@@ -0,0 +1,103 @@
+# The Diagnoser hooks into load and require and keeps track of when files are required / loaded, and who loaded them.
+# It's used when you run spork --diagnose
+#
+# = Example
+#  
+#  Spork::Diagnoser.install_hook!('/path/env.rb', '/path')
+#  require '/path/to/env.rb'
+#  Spork::Diagnoser.output_results(STDOUT)
+class Spork::Diagnoser
+  class << self
+    def loaded_files
+      @loaded_files ||= {}
+    end
+    
+    # Installs the diagnoser hook into Kernel#require and Kernel#load
+    #
+    # == Parameters
+    #
+    # * +entry_file+ - The file that is used to load the project.  Used to filter the backtrace so anything that happens after it is hidden.
+    # * +dir+ - The project directory.  Any file loaded outside of this directory will not be logged.
+    def install_hook!(entry_file = nil, dir = Dir.pwd)
+      @dir = File.expand_path(Dir.pwd, dir)
+      @entry_file = entry_file
+      
+      Kernel.class_eval do
+        alias :require_without_diagnoser :require
+        alias :load_without_diagnoser :load
+        
+        def require(string)
+          ::Spork::Diagnoser.add_included_file(string, caller)
+          require_without_diagnoser(string)
+        end
+        
+        def load(string)
+          ::Spork::Diagnoser.add_included_file(string, caller)
+          load_without_diagnoser(string)
+        end
+      end
+    end
+    
+    def add_included_file(filename, callstack)
+      filename = expand_filename(filename)
+      return unless File.exist?(filename)
+      loaded_files[filename] = filter_callstack(caller) if subdirectory?(filename)
+    end
+    
+    # Uninstall the hook. Generally useful only for testing the Diagnoser.
+    def remove_hook!
+      return unless Kernel.private_instance_methods.include?('require_without_diagnoser')
+      Kernel.class_eval do
+        alias :require :require_without_diagnoser
+        alias :load :load_without_diagnoser
+        
+        undef_method(:require_without_diagnoser)
+        undef_method(:load_without_diagnoser)
+      end
+      true
+    end
+    
+    # output the results of a diagnostic run.
+    #
+    # == Parameters
+    #
+    # * +stdout+ - An IO stream to output the results to.
+    def output_results(stdout)
+      project_prefix = Dir.pwd + "/"
+      minimify = lambda { |f| f.gsub(project_prefix, '')}
+      stdout.puts "- Spork Diagnosis -\n"
+      stdout.puts "-- Summary --"
+      stdout.puts loaded_files.keys.sort.map(&minimify)
+      stdout.puts "\n\n\n"
+      stdout.puts "-- Detail --"
+      loaded_files.keys.sort.each do |file|
+        stdout.puts "\n\n\n--- #{minimify.call(file)} ---\n"
+        stdout.puts loaded_files[file].map(&minimify)
+      end
+    end
+    
+    private
+      def filter_callstack(callstack, entry_file = @entry_file)
+        callstack.pop until callstack.empty? || callstack.last.include?(@entry_file) if @entry_file
+        callstack.map do |line|
+          next if line.include?('lib/spork/diagnoser.rb')
+          line.gsub!('require_without_diagnoser', 'require')
+          line
+        end.compact
+      end
+    
+      def expand_filename(filename)
+        ([Dir.pwd] + $:).each do |attempted_path|
+          attempted_filename = File.expand_path(filename, attempted_path)
+          return attempted_filename if File.file?(attempted_filename)
+          attempted_filename = attempted_filename + ".rb"
+          return attempted_filename if File.file?(attempted_filename)
+        end
+        filename
+      end
+    
+      def subdirectory?(directory)
+        File.expand_path(directory, Dir.pwd).include?(@dir)
+      end
+  end
+end

data/lib/spork/forker.rb

@@ -0,0 +1,70 @@
+# A helper class that allows you to run a block inside of a fork, and then get the result from that block.
+#
+# == Example:
+#
+#   forker = Spork::Forker.new do
+#     sleep 3
+#     "success"
+#   end
+#   
+#   forker.result # => "success"
+class Spork::Forker
+  
+  # Raised if the fork died (was killed) before it sent it's response back.
+  class ForkDiedException < Exception; end
+  def initialize(&block)
+    return unless block_given?
+    @child_io, @server_io = UNIXSocket.socketpair
+    @child_pid = Kernel.fork do
+      @server_io.close
+      Marshal.dump(yield, @child_io)
+      # wait for the parent to acknowledge receipt of the result.
+      master_response = 
+        begin
+          Marshal.load(@child_io)
+        rescue EOFError
+          nil
+        end
+      
+      # terminate, skipping any at_exit blocks.
+      exit!(0)
+    end
+    @child_io.close
+  end
+  
+  # Wait for the fork to finish running, and then return its return value.
+  #
+  # If the fork was aborted, then result returns nil.
+  def result
+    return unless running?
+    result_thread = Thread.new do
+      begin
+        @result = Marshal.load(@server_io)
+        Marshal.dump('ACK', @server_io)
+      rescue ForkDiedException
+        @result = nil
+      end
+    end
+    Process.wait(@child_pid)
+    result_thread.raise(ForkDiedException) if @result.nil?
+    @child_pid = nil
+    @result
+  end
+  
+  # abort the current running fork
+  def abort
+    if running?
+      Process.kill(Signal.list['TERM'], @child_pid)
+      @child_pid = nil
+      true
+    end
+  end
+  
+  def running?
+    return false unless @child_pid
+    Process.getpgid(@child_pid)
+    true
+  rescue Errno::ESRCH
+    false
+  end
+end

data/lib/spork/runner.rb

@@ -2,6 +2,7 @@ require 'optparse'
 require 'spork/server'
 
 module Spork
+  # This is used by bin/spork. It's wrapped in a class because it's easier to test that way.
   class Runner
     attr_reader :server
     
@@ -19,7 +20,9 @@ module Spork
       
       opt.separator "Options:"
       opt.on("-b", "--bootstrap")  {|ignore| @options[:bootstrap] = true }
+      opt.on("-d", "--diagnose")  {|ignore| @options[:diagnose] = true }
       opt.on("-h", "--help")  {|ignore| @options[:help] = true }
+      opt.on("-p", "--port [PORT]") {|port| @options[:port] = port }
       non_option_args = args.select { |arg| ! args[0].match(/^-/) }
       @options[:server_matcher] = non_option_args[0]
       opt.parse!(args)
@@ -41,11 +44,12 @@ module Spork
       text.string
     end
     
+    # Returns a server for the specified (or the detected default) testing framework.  Returns nil if none detected, or if the specified is not supported or available.
     def find_server
       if options[:server_matcher]
         @server = Spork::Server.supported_servers(options[:server_matcher]).first
         unless @server
-          @output.puts <<-ERROR
+          @error.puts <<-ERROR
 #{options[:server_matcher].inspect} didn't match a supported test framework.
 
 #{supported_servers_text}
@@ -54,7 +58,7 @@ module Spork
         end
         
         unless @server.available?
-          @output.puts  <<-USEFUL_ERROR
+          @error.puts  <<-USEFUL_ERROR
 I can't find the helper file #{@server.helper_file} for the #{@server.server_name} testing framework.
 Are you running me from the project directory?
           USEFUL_ERROR
@@ -63,7 +67,7 @@ Are you running me from the project directory?
       else
         @server = Spork::Server.available_servers.first
         if @server.nil?
-          @output.puts  <<-USEFUL_ERROR
+          @error.puts  <<-USEFUL_ERROR
 I can't find any testing frameworks to use.
 Are you running me from a project directory?
           USEFUL_ERROR
@@ -76,14 +80,28 @@ Are you running me from a project directory?
     def run
       return false unless find_server
       ENV["DRB"] = 'true'
-      ENV["RAILS_ENV"] ||= 'test' if server.using_rails?
-      @output.puts "Using #{server.server_name}"
-      return server.bootstrap if options[:bootstrap]
-      return(false) unless server.preload
-      server.run
-      return true
-    end
+      @error.puts "Using #{server.server_name}"
+      @error.flush
+
+      server.port = options[:port]
 
+      case
+      when options[:bootstrap]
+        server.bootstrap
+      when options[:diagnose]
+        require 'spork/diagnoser'
+        
+        Spork::Diagnoser.install_hook!(server.entry_point)
+        server.preload
+        Spork::Diagnoser.output_results(@output)
+        return true
+      else
+        return(false) unless server.preload
+        server.run
+        return true
+      end
+    end
+    
     private
     attr_reader :options 
 

data/lib/spork/server.rb

@@ -1,33 +1,41 @@
 require 'drb/drb'
 require 'rbconfig'
+require 'spork/forker.rb'
+require 'spork/custom_io_streams.rb'
+require 'spork/app_framework.rb'
 
-# This is based off of spec_server.rb from rspec-rails (David Chelimsky), which was based on Florian Weber's TDDMate
+# An abstract class that is implemented to create a server
+#
+# (This was originally based off of spec_server.rb from rspec-rails (David Chelimsky), which was based on Florian Weber's TDDMate)
 class Spork::Server
   @@supported_servers = []
   
   LOAD_PREFERENCE = ['RSpec', 'Cucumber']
   BOOTSTRAP_FILE = File.dirname(__FILE__) + "/../../assets/bootstrap.rb"
   
+  include Spork::CustomIOStreams
+  
+  # Abstract method: returns the servers port.  Override this to return the port that should be used by the test framework.
   def self.port
     raise NotImplemented
   end
   
+  # Abstract method: returns the entry file that loads the testing environment, such as spec/spec_helper.rb.
   def self.helper_file
     raise NotImplemented
   end
   
+  # Convenience method that turns the class name without the namespace
   def self.server_name
     self.name.gsub('Spork::Server::', '')
   end
   
-  def self.inherited(subclass)
-    @@supported_servers << subclass
-  end
-  
+  # Returns a list of all testing servers that have detected their testing framework being used in the project.
   def self.available_servers
     supported_servers.select { |s| s.available? }
   end
   
+  # Returns a list of all servers that have been implemented (it keeps track of them automatically via Class.inherited)
   def self.supported_servers(starting_with = nil)
     @@supported_servers.sort! { |a,b| a.load_preference_index <=> b.load_preference_index }
     return @@supported_servers if starting_with.nil?
@@ -36,28 +44,28 @@ class Spork::Server
     end
   end
   
+  # Returns true if the testing frameworks helper file exists.  Override if this is not sufficient to detect your testing framework.
   def self.available?
     File.exist?(helper_file)
   end
   
+  # Used to specify
   def self.load_preference_index
     LOAD_PREFERENCE.index(server_name) || LOAD_PREFERENCE.length
   end
   
-  def self.using_rails?
-    File.exist?("config/environment.rb")
-  end
-  
+  # Detects if the test helper has been bootstrapped.
   def self.bootstrapped?
     File.read(helper_file).include?("Spork.prefork")
   end
   
+  # Bootstraps the current test helper file by prepending a Spork.prefork and Spork.each_run block at the beginning.
   def self.bootstrap
     if bootstrapped?
-      puts "Already bootstrapped!"
+      stderr.puts "Already bootstrapped!"
       return
     end
-    puts "Bootstrapping #{helper_file}."
+    stderr.puts "Bootstrapping #{helper_file}."
     contents = File.read(helper_file)
     bootstrap_code = File.read(BOOTSTRAP_FILE)
     File.open(helper_file, "wb") do |f|
@@ -65,7 +73,7 @@ class Spork::Server
       f.puts contents
     end
     
-    puts "Done. Edit #{helper_file} now with your favorite text editor and follow the instructions."
+    stderr.puts "Done. Edit #{helper_file} now with your favorite text editor and follow the instructions."
     true
   end
   
@@ -74,65 +82,101 @@ class Spork::Server
     new.listen
   end
   
+  # Sets up signals and starts the DRb service. If it's successful, it doesn't return. Not ever.  You don't need to override this.
   def listen
     trap("SIGINT") { sig_int_received }
     trap("SIGTERM") { abort; exit!(0) }
     trap("USR2") { abort; restart } if Signal.list.has_key?("USR2")
     DRb.start_service("druby://127.0.0.1:#{port}", self)
-    puts "Spork is ready and listening on #{port}!"
+    stderr.puts "Spork is ready and listening on #{port}!"
+    stderr.flush
     DRb.thread.join
   end
   
   def port
-    self.class.port
+    self.class.instance_variable_get("@port") || self.class.port
+  end
+
+  def self.port= p
+    @port = p
   end
   
   def helper_file
     self.class.helper_file
   end
   
+  # This is the public facing method that is served up by DRb.  To use it from the client side (in a testing framework):
+  # 
+  #   DRb.start_service("druby://localhost:0") # this allows Ruby to do some magical stuff so you can pass an output stream over DRb.
+  #                                            # see http://redmine.ruby-lang.org/issues/show/496 to see why localhost:0 is used.
+  #   spec_server = DRbObject.new_with_uri("druby://127.0.0.1:8989")
+  #   spec_server.run(options.argv, $stderr, $stdout)
+  #
+  # When implementing a test server, don't override this method: override run_tests instead.
   def run(argv, stderr, stdout)
-    return false if running?
-    $stdout = stdout
-    $stderr = stderr
-    @child_pid = Kernel.fork do
-      Spork.exec_each_run(helper_file)
+    abort if running?
+    
+    @child = ::Spork::Forker.new do
+      $stdout, $stderr = stdout, stderr
+      Spork.exec_each_run { load helper_file }
       run_tests(argv, stderr, stdout)
     end
-    Process.wait(@child_pid)
-    @child_pid = nil
-    true
+    @child.result
   end
   
+  # returns whether or not the child (a test run) is running right now.
   def running?
-    !! @child_pid
+    @child && @child.running?
   end
   
+  protected
+    # Abstract method: here is where the server runs the tests.
+    def run_tests(argv, input, output)
+      raise NotImplemented
+    end
+  
   private
+    def self.inherited(subclass)
+      @@supported_servers << subclass
+    end
+    
+    def self.framework
+      @framework ||= Spork::AppFramework.detect_framework
+    end
+    
+    def self.entry_point
+      bootstrapped? ? helper_file : framework.entry_point
+    end
+
     def self.preload
-      if bootstrapped?
-        puts "Loading Spork.prefork block..."
-        Spork.exec_prefork(helper_file)
-      else
-        puts "#{helper_file} has not been sporked.  Run spork --bootstrap to do so."
-        # are we in a rails app?
-        if using_rails?
-          puts "Preloading Rails environment"
-          require "config/environment.rb"
-        else
-          puts "There's nothing I can really do for you.  Bailing."
-          return false
+      Spork.exec_prefork do
+        unless bootstrapped?
+          stderr.puts "#{helper_file} has not been bootstrapped.  Run spork --bootstrap to do so."
+          stderr.flush
+        
+          if framework.bootstrap_required?
+            stderr.puts "I can't do anything for you by default for the framework your using: #{framework.short_name}.\nYou must bootstrap #{helper_file} to continue."
+            stderr.flush
+            return false
+          else
+            load(framework.entry_point)
+          end
         end
+      
+        framework.preload do
+          if bootstrapped?
+            stderr.puts "Loading Spork.prefork block..."
+            stderr.flush
+            load(helper_file)
+          end
+        end  
       end
       true
     end
     
-    def run_tests(argv, input, output)
-      raise NotImplemented
-    end
-    
     def restart
-      puts "restarting"
+      stderr.puts "restarting"
+      stderr.flush
       config       = ::Config::CONFIG
       ruby         = File::join(config['bindir'], config['ruby_install_name']) + config['EXEEXT']
       command_line = [ruby, $0, ARGV].flatten.join(' ')
@@ -140,20 +184,18 @@ class Spork::Server
     end
     
     def abort
-      if running?
-        Process.kill(Signal.list['TERM'], @child_pid)
-        true
-      end
+      @child && @child.abort
     end
     
     def sig_int_received
       if running?
         abort
-        puts "Running specs stopped.  Press CTRL-C again to stop the server."
+        stderr.puts "Running tests stopped.  Press CTRL-C again to stop the server."
+        stderr.flush
       else
         exit!(0)
       end
     end
 end
 
-Dir[File.dirname(__FILE__) + "/server/*.rb"].each { |file| require file }
+Dir[File.dirname(__FILE__) + "/server/*.rb"].each { |file| require file }