rubytest(1) - ruby test via rubytest api
========================================

## DESCRIPTION

The rubytest command is a command line interface for running tests 
for RubyTest-based test frameworks.


## OVERVIEW

The rubytest command-line tool follows many of the usual conventions
so it's use is farily straightforward. The `-h/--help` option is 
available to detail all its options. Here is a basic example of usage. 

    $ rubytest -Ilib test/*_test.rb

This would add `lib` to Ruby's $LOAD_PATH and then load all the 
test files matching the `test/*_test.rb` glob.

When running tests, you need to be sure to load in your test framework
or your framework's Ruby Test adapter. This is usually done via a helper
script in the test files, but might also be done via command line options,
e.g.

    $ rubytest -r lemon -r ae test/test_*.rb

Of course, it can become tedious having to type such a long command over and over.
This can be dealt with via a configuration file. To utilize, add an `etc/test.rb`
file to a project and add `Test.run` (an alias for `Test.configure`) entries to it.

    Test.run do |r|
      r.loadpath 'lib'
      r.test_files << 'test/*_test.rb'
    end

    Test.run 'coverage' do |r|
      r.loadpath 'lib'
      r.test_files << 'test/*_test.rb'
      r.before do
        require 'simplecov'
        Simplecov.setup do |s|
          s.filter 'test/'
          s.command_name File.basename($0)
          s.coverage_dir 'log/coverage'    
        end
        # to ensure proper coverage
        require 'myapp'
      end
    end

Now when rubytest is used, the first configuration will apply. To use
the 'coverage' configuration use `-p/--profile` option.

    $ rubytest -p coverage

In this manner a project can have any number of different test configurations,
and it is easy to select between them.

Note that the above example could have used `Test.configure` instead
of `Test.run`. They do the same thing. But do not use `Test.run!` because
that will cause testing to be run immediately.

The configuration file can be in the `config` directory instead of `etc`, which
is nice for Rails projects. But if you prefer a file in the project's root 
then either `Testfile` or `.test` can be also be used instead. All of these
locations are supported simply because no one configuration convention has 
taken a solid hold in the Ruby community. However, we highly recommend using
`etc/test.rb`. In the end that seems like the best overall convention.


## USAGE

    rubytest [options] [files ...]


## OPTIONS

  * `-p` `--profile <NAME>`
    Use configuration profile.

  * `-f` `--format <NAME>`
    Report format.

  * `y` `--tapy`
    Shortcut for -f tapy.

  * `-j` `--tapj`
    Shortcut for -f tapj.

  * `-t` `--tag <TAG>`
    Select tests by tag.

  * `-u` `--unit <TAG>`
    Select tests by software unit.

  * `-m` `--match <TEXT>`
    Select tests by description.

  * `-A` `--autopath`
    Automatically add paths to $LOAD_PATH.

  * `-I` `--loadpath <PATH>`
    Add given path to $LOAD_PATH.

  * `-C` `--chdir <DIR>`
    Change directory before running tests.

  * `-R` `--chroot`
    Change to project root directory before running tests.

  * `-r` `--require <FILE>`
    Require file.

  * `-c` `--config <FILE>`
    Use alternate config file.

  * `-V` `--verbose`
    Provide extra detail in reports.

  * `--[no-]ansi`
    Turn on/off ANSI colors.

  * `--debug`
    Turn on debugging mode.

  * `--about`
    Display information about rubytest.

  * `--version`
    Display rubytest version.

  * `-h` `--help`
    Display this help message.


## RESOURCES

* [Website](http://rubyworks.github.com/rubytest-cli) /
* [Support](http://github.com/rubyworks/rubytest-cli/issues) /
* [Development](http://github.com/rubyworks/rubytest-cli) &nbsp; &nbsp;
* [![Build Status](https://secure.travis-ci.org/rubyworks/rubytest.png)](http://travis-ci.org/rubyworks/rubytest-cli)
* [![Gem Version](https://badge.fury.io/rb/rubytest.png)](http://badge.fury.io/rb/rubytest-cli)


## COPYRIGHT

Rubytest is copyrighted open-source software.

    Copyright (c) 2013 Rubyworks. All rights reserved.

It is redistributable and modifiable in accordance with the terms of the
BSD-2-Clause license.


## SEE ALSO

ruby(1)

