= DTR -- Distributed Test Runner

Supporting DTR version: 1.x.x

This package contains DTR, a distributed test runner program for decreasing 
time of running ruby tests, only supporting Test::Unit ruby testing framework
currently.

DTR has the following features:

* Run tests in mutli processes or on distributed machines.

* Hot plug distributed agents.

* Synchronizing codebase between agent and master processes.

* Runtime injection, all tests run in same environment.

DTR works in two parts: Runner Agent and DTR Master.

* Runner Agent is a DRb service hosting on distributed machines to run tests. For using 'fork' to create runner process, Runner Agent can't run on Windows directly. Requisites for running agent: Unix/Linux based OS System for forking sub-process; 'unzip' command for extracting codebase package.

* DTR Master is the process finding runner service to run tests and collect test results. It works by loading 'dtr/test_unit_injection.rb' with all test files. Requisites for running agent: 'zip' command for creating codebase package.

DTR (version >= 1.0.0) supports synchronizing codebase by a DTR::PackageTask defined in your rake tasks. The DTR::PackageTask is a similar task with Rake::PackageTask, the following is a simple example:

  % require 'dtr/raketasks'
  % DTR::PackageTask.new do |p|
  %   p.package_files.include("**/*")
  %   p.package_files.exclude('tmp/**/*')
  %   p.package_files.exclude('log/*')
  % end

The DTR::TestTask will create a DTR::PackageTask for you directly, and you can specify package_files too.

  % DTR::TestTask.new do |t|
  %   t.test_files = FileList['test/*_test.rb']
  %   t.processes = 2
  %   t.package_files.include('**/*.rb')
  %   t.package_files.exclude('tmp/**/*')
  %   t.package_files.exclude('log/*')
  % end

Note: Exclude('log/*') only excludes all files inside 'log' directory except 'log' directory itself.

== Download

The latest version of DTR can be found at

* http://github.com/xli/dtr/tree/master

== Installation

=== Normal Installation

You can install DTR with the following command.

  % ruby install.rb

from its distribution directory. or create a gem and install it:

  % rake gem
  % sudo gem install pkg/dtr-version.gem

=== GEM Installation

==== Last stable version from rubyforge.org

Download and install DTR with the following.

   gem install --remote dtr

==== Last version on github master branch

Run the following if you haven't already:

  gem sources -a http://gems.github.com

Install the gem:

  sudo gem install xli-dtr

=== Running the DTR Test Suite

If you wish to run the unit and functional tests that come with DTR:

* CD into the top project directory of dtr.
* Type the following:

   rake # You need a version of rake installed

== Simple Example

Start DTR agent with providing 2 runners as follows:

  % dtr --broadcast_ip broadcast_ip -r runner1,runner2

Type "dtr --help" for an up-to-date option summary.
Invoking <tt>dtr</tt> without any options causes dtr to show help too.

Most of time your project test suite need setup environment before run tests, you
can set setup command by option '--setup', for example:

  % dtr --broadcast_ip broadcast_ip -r runner1,runner2 --setup "rake db:test:prepare"

You also can specify DTR_AGENT_ENV_SETUP_CMD in your master process environment to let all agents which is not started with --setup option specified, setup same environment.

At last, you need to add 'dtr/test_unit_injection.rb' into test_files of your test 
task in your Rakefile, and for load it, you also need add dtr lib path:

  % require 'dtr'
  % 
  % ENV['DTR_AGENT_ENV_SETUP_CMD'] = 'rake db:test:prepare'
  % DTR.broadcast_list = ['broadcast_ip']
  % 
  % Rake::TestTask.new(:dtr) do |t|
  %   t.libs << DTR.lib_path
  %   t.test_files = FileList['dtr/test_unit_injection.rb', 'test/**/*_test.rb']
  %   t.warning = false
  %   t.verbose = false
  % end

In the case above we also changed dtr broadcast list for looking for agents.
You can simply use DTR::TestTask instead of Rake::TestTask to setup your dtr task:

  % DTR::TestTask.new :dtr do |t|
  %   t.test_files = FileList['test/**/*_test.rb']
  %   t.processes = 0 # don't start agent in local machine, default is 1, so we reset to 0 here.
  % end

Also you must define a DTR::PackageTask in your rakefile for packaging files need for running test.

DTR broadcast_list & port configuration would be cached in the directory running the test or agent process.
The configuration file named .dtr_env_pstore

== Run tests in multi-processes on one machine

For running Runner in multi-processes.
The following is the test task example in the rake file:

  require 'dtr/raketasks'

  DTR::TestTask.new :test do |t|
    t.test_files = FileList['test/*test.rb']
    t.processes = 2 #default is 1
  end

== Credits

[<b>Josh Price</b>] For fixing tests packer in release 0.0.1.

[<b>Wang Pengchao</b>] For sharing lots of ideas.

[<b>Barrow H Kwan</b>] For patch of specifying DTR Rinda server port.

[<b>Mingle team</b>(http://studios.thoughtworks.com/mingle-project-intelligence)] For making all these happen.

== License

DTR is available under an Apache License Version 2.

== Support

Feel free to submit commits or feature requests.
For other information, feel free to contact mailto:iam@li-xiao.com.

== Usage

DTR agent command is invoked from the command line using:

   % dtr [<em>options</em> ...]

=== Options are:

  -p, --port PORT                  Port number of DTR rinda server. Default is 3344.
  -r runner1_name,runner2_name     Start DTR test runner agent with unique runner names.
  -a, --broadcast_address ADDRESS  Specify broadcast address for looking up dtr rinda server, e.g. 192.168.255.255. Default is 'localhost'.
  -i, --setup COMMAND              Set command for initializing test runner test environment, e.g. 'rake db:test:prepare'. Default is do nothing. You also can specify DTR_AGENT_ENV_SETUP_CMD in your master process environment to let all agents setup same environment.
  -m, --monitor                    Monitor the status of the dtr agents.
  -v, --version                    Show version
  -h, --help                       Show this help doc

Type "dtr --help" for an up-to-date option summary.

= Other stuff

Author::  Li Xiao <iam@li-xiao.com>
Requires:: Ruby 1.8.6 or later
License::  Copyright 2007-2008 by Li Xiao.
           Released under an Apache License 2.  See the LICENSE file
           included in the distribution.

== Warranty

This software is provided "as is" and without any express or
implied warranties, including, without limitation, the implied
warranties of merchantibility and fitness for a particular
purpose.