rubytest(1) - ruby test via rubytest api

1. rubytest(1)
3. rubytest(1)

## NAME

`rubytest` - 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 /
- Support /
- Development

## 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)

2. July 2014
3. rubytest(1)