bmabey-spork 0.4.4 → 0.5.9

data/README.rdoc

@@ -1,18 +1,35 @@
 = Spork
 
-* http://github.com/timcharper/spork
+* Repository: http://github.com/timcharper/spork
+* Issues: http://github.com/timcharper/spork/issues
+* Changes: http://github.com/timcharper/spork/blob/master/History.txt
+* Mailing list: http://groups.google.com/group/sporkgem
+* Wiki: http://wiki.github.com/timcharper/spork
 
 == SYNOPSIS:
 
-Spork is Tim Harper's implementation of a Drb spec server (similar to the script/spec_server provided by rspec-rails), except rather than using the Rails constant unloading to reload your files, it forks a copy of the server each time you run your specs.  The result?  Spork runs more solid: it doesn't get corrupted over time, and it properly handles modules and any voo-doo meta programming you may have put in your app.
+Spork is Tim Harper's implementation of test server (similar to the script/spec_server provided by rspec-rails), except rather than using the Rails constant unloading to reload your files, it forks a copy of the server each time you run your tests.  The result?  Spork runs more solid: it doesn't get corrupted over time, and it properly handles modules and any voo-doo meta programming you may have put in your app.
 
 Because Spork uses Kernel.fork, it only works on POSIX systems.  This means Windows users are not invited to this party.  Sorry :(
 
-Spork is still experimental, but is performing solid for us.
+== Supported Testing Frameworks
+
+* Rspec
+* Cucumber
+
+And more to come!  Vote for your favorite at http://github.com/timcharper/spork/issues
+
+== Supported Application Frameworks
+
+Actually, Spork ~can~ work with any application framework.  But, it ships with hooks and helpers to help make the experience much more "out of the box"
+
+* Rails
+
+More can be added!  Vote for your favorite at http://github.com/timcharper/spork/issues
 
 == INSTALL:
 
-  [sudo] gem install timcharper-spork --source http://gems.github.com/
+  [sudo] gem install spork
 
 alternatively:
 
@@ -35,37 +52,48 @@ Finally, run spork.  A spec DRb server will be running!
 
   spork
 
-To get the TextMate RSpec bundle to use spork, go to config->advanced->shell variables, and add TM_RSPEC_OPTS=--drb.
+== Diagnostic mode
 
-To run from the command line, use spec --drb spec/lib/my_spec.rb
+Initially, you may find that a few files don't reload automatically.  This is because they are being loaded during Spork startup.  To identify which project files are being pre-loaded, and why, run:
 
-Or, you could add --drb to your spec.opts file.
+  spork --diagnose
+  (or spork -d, for short)
 
-== Some potential issues and ways to overcome them:
+It will output a lot of stuff.  At the top you'll find a summary of all project files loaded.  Down below, the stack trace for each file (how it got loaded).  Spork hooks into Rails and does some magic (TM) to prevent ApplicationController observers, etc from pre-loading.  Similar hooks for other ruby frameworks may come as support demands.
+
+== Running specs over Spork
+
+=== RSpec
 
-=== ActiveRecord reports "connection has gone away" for the first few specs
+To get the TextMate RSpec bundle to use spork, go to config->advanced->shell variables, and add:
 
-Not sure why this happens, but if you simply add a line to re-establish your database connection on each line as follows, the problem goes away:
+  TM_RSPEC_OPTS=--drb.
 
-  Spork.each_run do
-    ActiveRecord::Base.establish_connection # make sure that the db connection is ready.
-  end
+To run from the command line, use:
 
-=== Couldn't find formatter class Spec::Runner::Formatter::TextMateFormatter Make sure the --require option is specified *before* --format
+  spec --drb spec/lib/my_spec.rb
 
-On one of our projects, many of us using TextMate with spork, only one developer got this error message while the rest of us ran just fine.  I don't know exactly why it happened, but requiring the textmate formatter in the prefork block made it go away, like this:
+Or, you could add the following flag to your +spec.opts+ file.
+
+  --drb
+
+=== Cucumber
+
+Cucumber --drb support for spork is not official yet (but it works).  It's the hottest sauce boiling on the world wide web right now.  If you can't wait to try it, head on over to Cucumber core-team member Ben Mabey's drb branch and build your own cucumber gem:
+
+  http://github.com/bmabey/cucumber/tree/drb_server
+
+Use this as a guideline when "Sporking" your features/support/env.rb file
+
+  http://gist.github.com/123370
+
+== Some potential issues and ways to overcome them:
 
-  Spork.prefork do
-    gem "rspec", "= 1.2.6"
-    require 'spec'
-    ...
-    require 'spec/runner/formatter/text_mate_formatter'
-    ...
-  end
+See http://wiki.github.com/timcharper/spork/troubleshooting
 
 == Kudos to
 
-* Ben Mabey - help with documentation, testing, suggestions, patches, collaborated with Cucumber support.
+* Ben Mabey - help with documentation, testing, suggestions, patches, and bringing Cucumber support.
 * David Chelimsky - for the fine RSpec testing framework, and the original rspec-rails spec_server implementation, which Spork has built upon.
 * Lead Media Partners - just for being an awesome place to work.
 

data/assets/bootstrap.rb

@@ -2,7 +2,7 @@ require 'rubygems'
 require 'spork'
 
 Spork.prefork do
-  # Loading more in this block will cause your specs to run faster. However, 
+  # Loading more in this block will cause your tests to run faster. However, 
   # if you change any configuration or code from libraries loaded here, you'll
   # need to restart spork for it take effect.
   

data/features/cucumber_rails_integration.feature

@@ -0,0 +1,113 @@
+Feature: Cucumber integration with rails
+  As a developer using cucumber and rails
+  I want to use Spork with Cucumber
+  In order to eliminate the startup cost of my application each time I run them
+  
+  Background: Sporked env.rb
+    Given I am in a fresh rails project named "test_rails_project"
+    And the application has a model, observer, route, and application helper
+    And a file named "features/support/env.rb" with:
+      """
+      require 'rubygems'
+      require 'spork'
+
+      Spork.prefork do
+        # Loading more in this block will cause your tests to run faster. However, 
+        # if you change any configuration or code from libraries loaded here, you'll
+        # need to restart spork for it take effect.
+        
+        # Sets up the Rails environment for Cucumber
+        ENV['RAILS_ENV'] = "features"
+        require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
+
+        require 'webrat'
+
+        Webrat.configure do |config|
+          config.mode = :rails
+        end
+
+        require 'webrat/core/matchers'
+        require 'cucumber'
+        require 'cucumber/formatter/unicode' # Comment out this line if you don't want Cucumber Unicode support
+        require 'spec/rails'
+        require 'cucumber/rails/rspec'
+        
+        #### this is for this test only #######
+        $loaded_stuff << 'prefork block' ######
+        #######################################
+      end
+
+      Spork.each_run do
+        # This code will be run each time you run your specs.
+        require 'cucumber/rails/world'
+        Cucumber::Rails.use_transactional_fixtures
+        Cucumber::Rails.bypass_rescue # Comment out this line if you want Rails own error handling
+                                      # (e.g. rescue_action_in_public / rescue_responses / rescue_from)
+        
+        #### this is for this test only #######
+        $loaded_stuff << 'each_run block' #####
+        #######################################
+      end
+      """
+    And a file named "features/cucumber_rails.feature" with:
+      """
+      Feature: cucumber rails
+        Scenario: did it work
+          Then it should work
+      """
+    And a file named "features/support/cucumber_rails_helper.rb" with:
+      """
+      $loaded_stuff << 'features/support/cucumber_rails_helper.rb'
+      """
+    And a file named "config/environments/features.rb" with:
+      """
+      # your cucumber env here
+      """
+    And a file named "config/database.yml" with:
+      """
+      features:
+        adapter: sqlite3
+        database: db/features.sqlite3
+        timeout: 5000
+      """
+    And a file named "features/step_definitions/cucumber_rails_steps.rb" with:
+      """
+      Then "it should work" do
+        Spork.state.should == :using_spork
+        RAILS_ENV.should == 'features'
+        (Rails.respond_to?(:logger) ? Rails.logger : ActionController::Base.logger).info "hey there"
+        $loaded_stuff.should include('ActiveRecord::Base.establish_connection')
+        $loaded_stuff.should include('User')
+        $loaded_stuff.should include('UserObserver')
+        $loaded_stuff.should include('ApplicationHelper')
+        $loaded_stuff.should include('config/routes.rb')
+        $loaded_stuff.should include('features/support/cucumber_rails_helper.rb')
+        $loaded_stuff.should include('each_run block')
+        $loaded_stuff.should include('prefork block')
+        puts "It worked!"
+      end
+      """
+    Scenario: Analyzing files were preloaded
+      When I run spork --diagnose
+      Then the output should not contain "user_observer.rb"
+      Then the output should not contain "user.rb"
+      Then the output should not contain "app/controllers/application.rb"
+      Then the output should not contain "app/controllers/application_controller.rb"
+      Then the output should not contain "app/controllers/application_helper.rb"
+      Then the output should not contain "config/routes.rb"
+      Then the output should not contain "features/step_definitions/cucumber_rails_steps.rb"
+      Then the output should not contain "features/support/cucumber_rails_helper.rb"
+      
+    Scenario: Running spork with a rails app and observers
+      When I fire up a spork instance with "spork cucumber"
+      And I run cucumber --drb features/cucumber_rails.feature
+      Then the error output should be empty
+      And the output should contain "It worked!"
+      And the file "log/features.log" should include "hey there"
+      
+    Scenario: Running spork with a rails app and a non-standard port
+      When I fire up a spork instance with "spork cucumber -p 9000"
+      And I run cucumber --drb --port 9000 features/cucumber_rails.feature
+      Then the error output should be empty
+      And the output should contain "It worked!"
+      And the file "log/features.log" should include "hey there"

data/features/diagnostic_mode.feature

@@ -0,0 +1,41 @@
+Feature: Diagnostic Mode
+  To help a developer quickly pinpoint why files are being loaded
+  Spork provides a diagnostic mode
+  That provides a list of which project files were loaded during prefork, and who loaded them.
+
+  Scenario: Running spork --diagnose
+    Given I am in the directory "test_project"
+    And a file named "spec/spec_helper.rb" with:
+      """
+      require 'rubygems'
+      require 'spork'
+
+      Spork.prefork do
+        require 'lib/awesome.rb'
+        require '../external_dependency/super_duper.rb'
+      end
+
+      Spork.each_run do
+        puts "I'm loading the stuff just for this run..."
+      end
+      """
+    And a file named "lib/awesome.rb" with:
+      """
+      class Awesome
+      end
+      """
+    And a file named "../external_dependency/super_duper.rb" with:
+      """
+      class Awesome
+      end
+      """
+    When I run spork --diagnose
+    Then the error output should contain
+      """
+      Loading Spork.prefork block...
+      """
+    And the output should contain "lib/awesome.rb"
+    And the output should contain "spec/spec_helper.rb:5"
+    And the output should not contain "super_duper.rb"
+    And the output should not contain "diagnose.rb"
+     

data/features/rails_delayed_loading_workarounds.feature

@@ -0,0 +1,80 @@
+Feature: Rails Delayed Work arounds
+  To allow a rails developer to update as many parts of his application as possible without needing to restart Spork
+  Spork automatically tells rails to delay loading certain parts of the application until after the fork occurs
+  Providing work arounds
+
+  Background: Rails App with RSpec and Spork
+
+    Given I am in a fresh rails project named "test_rails_project"
+    And a file named "spec/spec_helper.rb" with:
+      """
+      require 'rubygems'
+      require 'spork'
+
+      Spork.prefork do
+        require File.dirname(__FILE__) + '/../config/environment.rb'
+        require 'spec'
+        require 'spec/rails'
+      end
+
+      Spork.each_run do
+      end
+      """
+    And the application has a model, observer, route, and application helper
+  Scenario: within a view, calling helper methods from an included module in ApplicationHelper
+    Given a file named "app/helpers/application_helper.rb" with:
+      """
+      module ApplicationHelper
+        include Reverseatron
+      end
+      """
+    Given a file named "lib/reverseatron.rb" with:
+      """
+      module Reverseatron
+        def reverse_text(txt)
+          txt.reverse
+        end
+      end
+      """
+    Given a file named "app/controllers/users_controller.rb" with:
+      """
+      class UsersController < ApplicationController
+        $loaded_stuff << 'UsersController'
+        def index
+          @users = []
+        end
+      end
+      """
+    Given a file named "app/controllers/users_helper.rb" with:
+      """
+      module UsersHelper
+      end
+      """
+    Given a file named "app/views/users/index.html.erb" with:
+      """
+      <%= reverse_text('listing users'.reverse) %>
+      """
+    Given a file named "spec/controllers/users_controller_spec.rb" with:
+      """
+      describe UsersController do
+        integrate_views
+        it "renders a page, using a method inherited from ApplicationController" do
+          get :index
+          response.body.should include('listing users')
+          puts "Controller stack is functioning"
+          response.body.should include('Here is a list of users')
+          puts "Views are not being cached"
+        end
+      end
+      """
+    When I fire up a spork instance with "spork rspec"
+    And the contents of "app/views/users/index.html.erb" are changed to:
+      """
+      <%= reverse_text('listing users'.reverse) %>
+      <p>Here is a list of users</p>
+      """
+      
+    And I run spec --drb spec/controllers/users_controller_spec.rb
+    Then the output should contain "Controller stack is functioning"
+    Then the output should contain "Views are not being cached"
+  

data/features/rspec_rails_integration.feature

@@ -0,0 +1,90 @@
+Feature: Rails Integration
+  To get a developer up and running quickly
+  Spork automatically integrates with rails
+  Providing default hooks and behaviors
+
+  Background: Rails App with RSpec and Spork
+
+    Given I am in a fresh rails project named "test_rails_project"
+    And a file named "spec/spec_helper.rb" with:
+      """
+      require 'rubygems'
+      require 'spork'
+
+      Spork.prefork do
+        # Loading more in this block will cause your specs to run faster. However, 
+        # if you change any configuration or code from libraries loaded here, you'll
+        # need to restart spork for it take effect.
+        require File.dirname(__FILE__) + '/../config/environment.rb'
+        require 'spec'
+        require 'spec/rails'
+        
+        #### this is for this test only #######
+        $loaded_stuff << 'prefork block' ######
+        #######################################
+      end
+
+      Spork.each_run do
+        # This code will be run each time you run your specs.
+        
+        #### this is for this test only #######
+        $loaded_stuff << 'each_run block' #####
+        #######################################
+      end
+      """
+    And the application has a model, observer, route, and application helper
+  Scenario: Analyzing files were preloaded
+    When I run spork --diagnose
+    Then the output should not contain "user_observer.rb"
+    Then the output should not contain "user.rb"
+    Then the output should not contain "app/controllers/application.rb"
+    Then the output should not contain "app/controllers/application_controller.rb"
+    Then the output should not contain "app/controllers/application_helper.rb"
+    Then the output should not contain "config/routes.rb"
+  
+  Scenario: Running spork with a rails app and observers
+    Given a file named "spec/did_it_work_spec.rb" with:
+    """
+    describe "Did it work?" do
+      it "checks to see if all worked" do
+        Spork.state.should == :using_spork
+        (Rails.respond_to?(:logger) ? Rails.logger : ActionController::Base.logger).info "hey there"
+        $loaded_stuff.should include('ActiveRecord::Base.establish_connection')
+        $loaded_stuff.should include('User')
+        $loaded_stuff.should include('UserObserver')
+        $loaded_stuff.should include('ApplicationHelper')
+        $loaded_stuff.should include('config/routes.rb')
+        $loaded_stuff.should include('each_run block')
+        $loaded_stuff.should include('prefork block')
+        puts "Specs successfully run within spork, and all initialization files were loaded"
+      end
+    end
+    """
+    When I fire up a spork instance with "spork rspec"
+    And I run spec --drb spec/did_it_work_spec.rb 
+    Then the output should contain "Specs successfully run within spork, and all initialization files were loaded"
+    And the file "log/test.log" should include "hey there"
+
+
+  Scenario: Running spork with a rails app and a non-standard port
+    Given a file named "spec/did_it_work_spec.rb" with:
+    """
+    describe "Did it work?" do
+      it "checks to see if all worked" do
+        Spork.state.should == :using_spork
+        (Rails.respond_to?(:logger) ? Rails.logger : ActionController::Base.logger).info "hey there"
+        $loaded_stuff.should include('ActiveRecord::Base.establish_connection')
+        $loaded_stuff.should include('User')
+        $loaded_stuff.should include('UserObserver')
+        $loaded_stuff.should include('ApplicationHelper')
+        $loaded_stuff.should include('config/routes.rb')
+        $loaded_stuff.should include('each_run block')
+        $loaded_stuff.should include('prefork block')
+        puts "Specs successfully run within spork, and all initialization files were loaded"
+      end
+    end
+    """
+    When I fire up a spork instance with "spork rspec --port 7000"
+    And I run spec --drb --port 7000 spec/did_it_work_spec.rb 
+    Then the output should contain "Specs successfully run within spork, and all initialization files were loaded"
+    And the file "log/test.log" should include "hey there"

data/features/steps/rails_steps.rb

@@ -0,0 +1,53 @@
+Given /^I am in a fresh rails project named "(.+)"$/ do |folder_name|
+  @current_dir = SporkWorld::SANDBOX_DIR
+  version_argument = ENV['RAILS_VERSION'] ? "_#{ENV['RAILS_VERSION']}_" : nil
+  # run("#{SporkWorld::RUBY_BINARY} #{%x{which rails}.chomp} #{folder_name}")
+  run([SporkWorld::RUBY_BINARY, '-I', Cucumber::LIBDIR, %x{which rails}.chomp, version_argument, folder_name].compact * " ")
+  @current_dir = File.join(File.join(SporkWorld::SANDBOX_DIR, folder_name))
+end
+
+
+Given "the application has a model, observer, route, and application helper" do
+  Given 'a file named "app/models/user.rb" with:',
+    """
+    class User < ActiveRecord::Base
+      $loaded_stuff << 'User'
+    end
+    """
+  Given 'a file named "app/models/user_observer.rb" with:',
+    """
+    class UserObserver < ActiveRecord::Observer
+      $loaded_stuff << 'UserObserver'
+    end
+    """
+  Given 'a file named "app/helpers/application_helper.rb" with:',
+    """
+    module ApplicationHelper
+      $loaded_stuff << 'ApplicationHelper'
+    end
+    """
+  Given 'the following code appears in "config/environment.rb" after /Rails::Initializer.run/:',
+    """
+      config.active_record.observers = :user_observer
+    """
+  Given 'the following code appears in "config/routes.rb" after /^end/:',
+    """
+      $loaded_stuff << 'config/routes.rb'
+    """
+  Given 'a file named "config/initializers/initialize_loaded_stuff.rb" with:',
+    """
+    $loaded_stuff ||= []
+    """
+  Given 'a file named "config/initializers/log_establish_connection_calls.rb" with:',
+    """
+    class ActiveRecord::Base
+      class << self
+        def establish_connection_with_load_logging(*args)
+          establish_connection_without_load_logging(*args)
+          $loaded_stuff << 'ActiveRecord::Base.establish_connection'
+        end
+        alias_method_chain :establish_connection, :load_logging
+      end
+    end
+    """
+end