torquespec 0.3.2 → 0.3.3

data/.gitignore

@@ -2,4 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
-.torquespec/*
+.torquespec/*
+/README.html

data/README.org

@@ -0,0 +1,171 @@
+#+TITLE:     Integration Testing for TorqueBox
+#+AUTHOR:    Jim Crossley
+#+EMAIL:     jcrossley@redhat.com
+#+LANGUAGE:  en
+#+OPTIONS:   H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
+#+OPTIONS:   TeX:t LaTeX:nil skip:nil d:nil todo:t pri:nil tags:not-in-toc
+#+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
+#+EXPORT_SELECT_TAGS: export
+#+EXPORT_EXCLUDE_TAGS: noexport
+
+* TorqueSpec 
+  
+  TorqueSpec extends the [[http://relishapp.com/rspec][RSpec testing framework]] to provide
+  integration testing for applications designed to run on the
+  [[http://torquebox.org/][TorqueBox Ruby application server]].  Before running your RSpec
+  examples, TorqueSpec ensures that a TorqueBox server is running and
+  enables you to verify expectations against real applications
+  deployed on it.
+
+  Easy browser control/simulation is possible via the [[https://github.com/jnicklas/capybara][capybara]] or
+  [[https://github.com/brynary/webrat][webrat]] gems, of course, but TorqueSpec also provides "in-container"
+  testing, where your examples are actually run within the TorqueBox
+  server itself.
+
+** Installation
+
+   Install the torquespec gem:
+
+   : $ gem install torquespec
+
+   And then in your spec files (or indirectly via =spec_helper.rb=):
+
+   : require 'torquespec'
+
+   Doing this will cause TorqueSpec to add a "before suite" hook that
+   fires up a TorqueBox server, i.e. JBoss, prior to running your
+   specs and an "after suite" hook to shut it down.
+
+** RSpec extensions
+
+   Aiming to be minimally intrusive, TorqueSpec makes two new methods
+   available to your spec files: =deploy= and =remote_describe=.
+
+*** deploy()
+
+    Determines which app[s] are deployed prior to running a particular
+    =ExampleGroup=, so typically called from a top-level =describe=
+    block.  The deployment and subsequent undeployment occur within
+    "before all" and "after all" RSpec hooks, respectively.
+
+    The method accepts any number of arguments, each of which should
+    represent a [[http://torquebox.org/2x/builds/html-docs/deployment-descriptors.html][TorqueBox deployment descriptor]], typically a YAML
+    "here document", a Hash, or a path to an existing file.  It also
+    accepts a block, the result of which should also be one or more
+    deployment descriptors.  Here's an example using a single here
+    doc:
+
+    : describe "basic test with heredoc" do
+    : 
+    :   deploy <<-DD_END.gsub(/^ {4}/,'')
+    :     application:
+    :       root: #{File.dirname(__FILE__)}/../app
+    :       env: development
+    :     web:
+    :       context: /basic
+    :   DD_END
+    : 
+    :   it "should work" do
+    :     visit "/basic"
+    :     page.should have_content('it worked')
+    :     page.find("#success")[:class].should == 'basic'
+    :   end
+    : 
+    : end
+
+    Here docs are especially nice because they support string
+    substitution.  Note that we're setting the location of the app
+    relative to the location of the spec file itself,
+    e.g. =__FILE__=.  And the little =gsub(/^ {4},'')= trick allows
+    you to indent the YAML relative to the Ruby.
+
+*** remote_describe()
+
+    TorqueSpec supports "in container" testing via the
+    =remote_describe= method.  It behaves exactly like the RSpec
+    =describe= method, but the resulting =ExampleGroup= will be run
+    inside the TorqueBox server.
+
+    If your spec calls =remote_describe=, TorqueSpec will deploy a
+    small daemon with your application.  This daemon will act as an
+    additional RSpec runner to which the "local" runner will delegate
+    the invocation of those =ExampleGroups= defined by
+    =remote_describe=.  This delegation occurs via DRb: the "remote"
+    runner reports its results to the "local" one, allowing you to
+    summarize the results of all your tests, both in-container and
+    out, in a single report.
+
+    Because your specs are consumed by two separate RSpec processes,
+    you must ensure that any gems other than TorqueSpec/RSpec are
+    available to the process that needs them.
+
+    : require 'torquespec'
+    : 
+    : TorqueSpec.local {
+    :   require 'capybara'
+    : }
+    : 
+    : app = <<-END.gsub(/^ {4}/,'')
+    :     application:
+    :       root: #{File.dirname(__FILE__)}/../app
+    :     END
+    : 
+    : describe "local test" do
+    :   deploy(app)
+    : 
+    :   it "should work" do
+    :     visit "/"
+    :     page.should have_content('it worked')
+    :   end
+    : end
+    : 
+    : remote_describe "remote test" do
+    :   deploy(app)
+    : 
+    :   it "should work" do
+    :     some_service = inject(com.foo.SomeService)
+    :     some_service.run.should == 'SUCCESS'
+    :   end
+    : end
+    
+    The above spec shows two example groups, one local and one remote.
+    But this spec will be processed by both the local test runner and
+    the remote daemon.  The local one uses =capybara= so its require
+    is guarded in a =TorqueSpec.local= block, which won't be run
+    remotely.  There's a complementary =TorqueSpec.remote= method
+    available, too.
+
+    Note also that the remote example is injecting a service that
+    wouldn't be available in the local runtime, only in the remote
+    TorqueBox server.  Hence, the convenience, if not potential
+    confusion, of in-container testing. :)
+
+** Configuration 
+
+   Configuration parameters are variables in the TorqueSpec namespace, e.g. =TorqueSpec.max_heap=.
+
+   | Parameter    | Description                                                    | Default       |
+   |--------------+----------------------------------------------------------------+---------------|
+   | ~knob_root~  | Where TorqueSpec creates your deployment descriptors           | .torquespec   |
+   | ~jboss_home~ | Where JBoss is installed                                       | ~$JBOSS_HOME~ |
+   | ~max_heap~   | The maximum RAM allocated to the JBoss JVM                     | 1024 MB       |
+   | ~jvm_args~   | Arguments to the JVM running JBoss                             | /see below/   |
+   | ~drb_port~   | The in-container spec runner listens on this port for requests | 7772          |
+   | ~lazy~       | Whether to use a running JBoss and leave it running when done  | false         |
+
+   By default, TorqueSpec is initialized thusly:
+
+   : TorqueSpec.configure do |config|
+   :   config.drb_port = 7772
+   :   config.knob_root = ".torquespec"
+   :   config.jvm_args = "-Xms64m -Xmx1024m -XX:MaxPermSize=512m -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:+CMSClassUnloadingEnabled -Dgem.path=default"
+   : end
+
+   Include a similar block in your =spec_helper.rb= to customize any of these.
+
+** Dependencies
+
+   TorqueSpec has been extensively tested with RSpec 2, though RSpec 1
+   should be compatible as well.  But really, why are you still using
+   RSpec 1?
+

data/lib/rspec/core/torquespec-extensions.rb

@@ -13,12 +13,15 @@ TorqueSpec::Configurator.configure do |config|
   config.extend(TorqueSpec)
 end
 
-if ENV['TORQUEBOX_APP_NAME']
+TorqueSpec.remote {
   module TorqueSpec
     def deploy(*descriptors)
     end
   end
-else
+}
+
+TorqueSpec.local {
+
   require 'torquespec/server'
 
   TorqueSpec::Configurator.configure do |config|
@@ -43,7 +46,7 @@ else
       Thread.current[:app_server].stop
     end
   end
-end
+}
 
 require 'torquespec/daemon'
 
@@ -51,7 +54,7 @@ module TorqueSpec
   module ObjectExtensions
     def remote_describe(*args, &example_group_block)
       group = describe(*args, &example_group_block)
-      ENV['TORQUEBOX_APP_NAME'] ? group : group.extend( TorqueSpec::Daemon::Client )
+      TorqueSpec.remote? ? group : group.extend( TorqueSpec::Daemon::Client )
     end
   end
 end

data/lib/torquespec/daemon.rb

@@ -6,7 +6,7 @@ module TorqueSpec
   class Daemon
 
     def initialize(opts={})
-      puts "JC: create daemon opts=#{opts.inspect}"
+      puts "daemon: create opts=#{opts.inspect}"
       dir = opts['pwd'].to_s
       raise "The 'pwd' option must contain a valid directory name" if dir.empty? || !File.exist?(dir)
       Dir.chdir( dir ) do
@@ -25,24 +25,17 @@ module TorqueSpec
     end
 
     def start
-      puts "JC: start daemon"
+      puts "daemon: start"
       DRb.start_service("druby://127.0.0.1:#{TorqueSpec.drb_port}", self)
-      10.times do
-        if DRb.current_server
-          break
-        else
-          sleep(0.1)
-        end
-      end
     end
 
     def stop
-      puts "JC: stop daemon"
+      puts "daemon: stop"
       DRb.stop_service
     end
 
     def run(name, reporter)
-      puts "JC: run #{name}"
+      puts "daemon: run #{name}"
       example_group = @world.example_groups.find { |g| g.name == name }
       example_group.run( reporter )
     end
@@ -65,15 +58,21 @@ module TorqueSpec
       def run_remotely(reporter)
         DRb.start_service("druby://127.0.0.1:0")
         daemon = DRbObject.new_with_uri("druby://127.0.0.1:#{TorqueSpec.drb_port}")
+        attempts = 10
         begin
           daemon.run( name, reporter )
+        rescue DRb::DRbConnError
+          # Overcome DRb.start_service() race condition
+          raise unless (attempts-=1) > 0
+          sleep(0.2)
+          retry
         ensure
           DRb.stop_service
         end
       end
       
       def deploy_paths
-        [ DeploymentDescriptor.new({}, display_name, true).path ]
+        [ DeploymentDescriptor.new( {}, display_name, true ).path ]
       end
 
     end

data/lib/torquespec/torquespec.rb

@@ -7,7 +7,7 @@ module TorqueSpec
     metaclass = class << self; self; end
     metaclass.send(:define_method, :deploy_paths) do
       return @deploy_paths if @deploy_paths
-      descriptors << block.call if block
+      descriptors += [block.call].flatten if block
       i = descriptors.size > 1 ? 0 : nil
       @deploy_paths = descriptors.map do |descriptor| 
         DeploymentDescriptor.new(descriptor, 
@@ -29,6 +29,15 @@ module TorqueSpec
     def as7?
       File.exist?( File.join( jboss_home, "bin/standalone.sh" ) )
     end
+    def jboss_home
+      @jboss_home ||= ENV['JBOSS_HOME'] || jboss_home_from_server_gem
+    end
+    def jboss_home_from_server_gem
+      require 'torquebox-server'
+      TorqueBox::Server.jboss_home
+    rescue Exception
+      $stderr.puts "WARN: Unable to determine JBoss install location; set either TorqueSpec.jboss_home or ENV['JBOSS_HOME']"
+    end
   end
 
   # A somewhat hackish way of exposing client-side gems to the server-side daemon
@@ -70,7 +79,6 @@ end
 TorqueSpec.configure do |config|
   config.drb_port = 7772
   config.knob_root = ".torquespec"
-  config.jboss_home = ENV['JBOSS_HOME']
   config.jvm_args = "-Xms64m -Xmx1024m -XX:MaxPermSize=512m -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:+CMSClassUnloadingEnabled -Dgem.path=default"
 end
 

data/lib/torquespec/version.rb

@@ -1,3 +1,3 @@
 module TorqueSpec
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/spec/hello_world_spec.rb

@@ -15,10 +15,10 @@ end
 
 describe "simple directory deployment" do
   
-  deploy <<-END.gsub(/^ {4}/,'')
+  deploy <<-DD_END.gsub(/^ {4}/,'')
     application:
       root: #{File.dirname(__FILE__)}/../apps/simple
-  END
+  DD_END
 
   it "should greet the world" do
     response = open("http://localhost:8080") {|f| f.read}

metadata

@@ -1,52 +1,41 @@
 --- !ruby/object:Gem::Specification 
 name: torquespec
 version: !ruby/object:Gem::Version 
-  hash: 23
-  prerelease: false
-  segments: 
-  - 0
-  - 3
-  - 2
-  version: 0.3.2
+  prerelease: 
+  version: 0.3.3
 platform: ruby
 authors: 
-- Jim Crossley
-- Bob McWhirter
+  - Jim Crossley
+  - Bob McWhirter
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2011-06-11 00:00:00 -04:00
+date: 2011-06-14 00:00:00 -04:00
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: json
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :runtime
-  version_requirements: *id002
+  - !ruby/object:Gem::Dependency 
+    name: rspec
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :runtime
+    version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: json
+    prerelease: false
+    requirement: &id002 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :runtime
+    version_requirements: *id002
 description: Write integration tests around the deployment of your app to a real JBoss app server
 email: team@projectodd.org
 executables: []
@@ -56,29 +45,29 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- .gitignore
-- Gemfile
-- README.md
-- Rakefile
-- apps/empty/torquebox.yml
-- apps/node-info.war
-- apps/simple.knob
-- apps/simple/config.ru
-- lib/rspec/core/torquespec-extensions.rb
-- lib/torque_spec/daemon.rb
-- lib/torquespec.rb
-- lib/torquespec/as6.rb
-- lib/torquespec/as7.rb
-- lib/torquespec/daemon.rb
-- lib/torquespec/deployment_descriptor.rb
-- lib/torquespec/server.rb
-- lib/torquespec/torquespec.rb
-- lib/torquespec/version.rb
-- spec/empty_spec.rb
-- spec/guard_spec.rb
-- spec/hello_world_spec.rb
-- spec/remote_spec.rb
-- torquespec.gemspec
+  - .gitignore
+  - Gemfile
+  - README.org
+  - Rakefile
+  - apps/empty/torquebox.yml
+  - apps/node-info.war
+  - apps/simple.knob
+  - apps/simple/config.ru
+  - lib/rspec/core/torquespec-extensions.rb
+  - lib/torque_spec/daemon.rb
+  - lib/torquespec.rb
+  - lib/torquespec/as6.rb
+  - lib/torquespec/as7.rb
+  - lib/torquespec/daemon.rb
+  - lib/torquespec/deployment_descriptor.rb
+  - lib/torquespec/server.rb
+  - lib/torquespec/torquespec.rb
+  - lib/torquespec/version.rb
+  - spec/empty_spec.rb
+  - spec/guard_spec.rb
+  - spec/hello_world_spec.rb
+  - spec/remote_spec.rb
+  - torquespec.gemspec
 has_rdoc: true
 homepage: http://github.com/torquebox/torquespec
 licenses: []
@@ -87,34 +76,28 @@ post_install_message:
 rdoc_options: []
 
 require_paths: 
-- lib
+  - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
 requirements: []
 
 rubyforge_project: torquespec
-rubygems_version: 1.3.7
+rubygems_version: 1.5.1
 signing_key: 
 specification_version: 3
 summary: Deploy TorqueBox knobs to a running JBoss instance
 test_files: 
-- spec/empty_spec.rb
-- spec/guard_spec.rb
-- spec/hello_world_spec.rb
-- spec/remote_spec.rb
+  - spec/empty_spec.rb
+  - spec/guard_spec.rb
+  - spec/hello_world_spec.rb
+  - spec/remote_spec.rb

data/README.md

@@ -1,8 +0,0 @@
-# TorqueSpec #
-
-TorqueSpec helps you build integration tests for your TorqueBox
-applications.  It encapsulates the control of a JBoss AS instance, and
-makes it easy to deploy your apps before running your RSpec examples
-and undeploy them afterwards.
-
-More docs coming soon.