dtr

= 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. Requisites for running agent: '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 or defining a DTR::TestTask in your rake file. Requisites for running master: 'zip' command for creating codebase package.

DTR (version >= 1.0.0) supports synchronizing codebase by a DTR::PackageTask defined in your rake tasks without any namespace. 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.

== Rails plugin

For Rails project, you can install dtr for your project by the following script:

./script/plugin install git://github.com/xli/dtr.git

There are dtr tasks defined for you to run tests within dtr grid. The test task is named 'dtr:test'. The default dtr package task is very simple, for large project you may need to custom it to decreasing time of synchronizing codebase.

Your project directory name would be the default group name of dtr agents. You can specify an environment variable named 'DTR_GROUP' to change the group name. By default, dtr tasks would lookup the broadcast ip by 'ifconfig' command. If it doesn't work for you, you can specify an environment variable named 'BROADCAST_IP' to overwrite it.

== Download

The latest version of DTR can be found at

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

== 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

== Documentation

http://dtr.rubyforge.org/

== 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 1 runner in group 'my_project_name' as follows:

dtr -r runner1 -g my_project_name

Type "dtr --help" for an up-to-date option summary. DTR stored your configuration automatically, and configurations would be picked up automatically next time you start dtr.

DTR supports Rails test environment setup, so you don't need to configure it unless your test environment setup is different with Rails project default command. You can setup environment as you need by option '--setup', for example:

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

If you installed dtr as your Rails project plugin, you don't need the following steps. Otherwise, you need define a DTR::TestTask in your rake file:

require 'dtr/raketasks'

Uncomment the following code to specify DTR_AGENT_ENV_SETUP_CMD here to get all agents

that are not started with '--setup' option specified to setup test environment.

ENV['DTR_AGENT_ENV_SETUP_CMD'] = 'rake db:test:prepare'

DTR.broadcast_list = ['broadcast_ip'] DTR.group = 'my_project_name'

DTR::TestTask.new 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. t.package_files.include("Rakefile") t.package_files.include("app//") t.package_files.include("db/migrate/**/") t.package_files.include("config//*") t.package_files.include("lib//") t.package_files.include("vendor/**/") t.package_files.include("test/**/*") end

The default task name is 'dtr', and it also creates package tasks you need for packaging files need for running test. More details about DTR::TestTask and DTR::PackageTask, see the API doc:

ri DTR::TestTask ri DTR::PackageTask

Notes:

• DTR broadcast_list and group configuration would be cached in the directory. Name of configuration file is '.dtr_env_pstore'.
• For packaging codebase, DTR::PackageTask creates tasks: dtr_package, dtr_clobber_package and dtr_repackage; DTR Master just simply run a command 'rake dtr_repackage' to create the package and run 'rake dtr_clobber_package' to clean package. So make sure there are those tasks under root namespace in your rake tasks.

== Run tests in multi-processes on one machine

For running agent runners in multi-processes with Master process on same machine and quit with Master process. The following is the test task example in the rake file:

require 'dtr/raketasks'

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

== Credits

[Josh Price] For fixing tests packer in release 0.0.1.

[Wang Pengchao] For sharing lots of ideas and code contributions.

[Barrow H Kwan] For patch of specifying DTR Rinda server port (version 0.0.x) and testing DTR new version.

[Mingle team(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:[e-mail].

== Usage

DTR agent command is invoked from the command line using:

dtr [options ...]

=== Options are:

-p, --port PORT Port number of DTR agent listening. Default is 7788. -g, --group GROUP_NAME If you have several DTR grids working for different project or environment, you should group your agents in different names for different usages. Default is none. -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 agent service, e.g. 192.168.255.255. Default is 'localhost'. DTR master and monitor would need this. -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 and master processes. Used for testing your dtr grid environment. CAUTION! monitoring agents causes all idle agents hang on by the monitor process. -v, --version Show version -h, --help Show this help doc

Notes:

• DTR would always add 'localhost' into broadcast list.
• Agent start by specifying runners by -r option, every runner would be started in different process for running test. e.g. dtr -r runner1,runner2
• DTR master environment options:
  • DTR_MASTER_ENV: this variable would be copied into agent process for sharing info between master and agents. Normally used in agent setup environment command.
  • DTR_AGENT_ENV_SETUP_CMD: this variable would be applied as agent setup environment command when agent have no setup environment command specified by --setup option.
  • DTR_LOG_LEVEL: master process logger level, e.g. ENV['DTR_LOG_LEVEL'] = Logger::DEBUG. Agent process logs would be output in master process log file, so setting this option also changes agent logger level.
  • DTR_RUNNER_NAME: this environment variable would be provided in runner process for test environment to get the runner name, e.g. setting up database configuration.

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

= Other stuff

Author: Li Xiao [e-mail]

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.