.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "RUBYTEST" "1" "July 2014" "" ""
.
.SH "NAME"
\fBrubytest\fR \- ruby test via rubytest api
.
.SH "DESCRIPTION"
The rubytest command is a command line interface for running tests for RubyTest\-based test frameworks\.
.
.SH "OVERVIEW"
The rubytest command\-line tool follows many of the usual conventions so it\'s use is farily straightforward\. The \fB\-h/\-\-help\fR option is available to detail all its options\. Here is a basic example of usage\.
.
.IP "" 4
.
.nf

$ rubytest \-Ilib test/*_test\.rb
.
.fi
.
.IP "" 0
.
.P
This would add \fBlib\fR to Ruby\'s $LOAD_PATH and then load all the test files matching the \fBtest/*_test\.rb\fR glob\.
.
.P
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\.
.
.IP "" 4
.
.nf

$ rubytest \-r lemon \-r ae test/test_*\.rb
.
.fi
.
.IP "" 0
.
.P
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 \fBetc/test\.rb\fR file to a project and add \fBTest\.run\fR (an alias for \fBTest\.configure\fR) entries to it\.
.
.IP "" 4
.
.nf

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
.
.fi
.
.IP "" 0
.
.P
Now when rubytest is used, the first configuration will apply\. To use the \'coverage\' configuration use \fB\-p/\-\-profile\fR option\.
.
.IP "" 4
.
.nf

$ rubytest \-p coverage
.
.fi
.
.IP "" 0
.
.P
In this manner a project can have any number of different test configurations, and it is easy to select between them\.
.
.P
Note that the above example could have used \fBTest\.configure\fR instead of \fBTest\.run\fR\. They do the same thing\. But do not use \fBTest\.run!\fR because that will cause testing to be run immediately\.
.
.P
The configuration file can be in the \fBconfig\fR directory instead of \fBetc\fR, which is nice for Rails projects\. But if you prefer a file in the project\'s root then either \fBTestfile\fR or \fB\.test\fR 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 \fBetc/test\.rb\fR\. In the end that seems like the best overall convention\.
.
.SH "USAGE"
.
.nf

rubytest [options] [files \.\.\.]
.
.fi
.
.SH "OPTIONS"
.
.IP "\(bu" 4
\fB\-p\fR \fB\-\-profile <NAME>\fR Use configuration profile\.
.
.IP "\(bu" 4
\fB\-f\fR \fB\-\-format <NAME>\fR Report format\.
.
.IP "\(bu" 4
\fBy\fR \fB\-\-tapy\fR Shortcut for \-f tapy\.
.
.IP "\(bu" 4
\fB\-j\fR \fB\-\-tapj\fR Shortcut for \-f tapj\.
.
.IP "\(bu" 4
\fB\-t\fR \fB\-\-tag <TAG>\fR Select tests by tag\.
.
.IP "\(bu" 4
\fB\-u\fR \fB\-\-unit <TAG>\fR Select tests by software unit\.
.
.IP "\(bu" 4
\fB\-m\fR \fB\-\-match <TEXT>\fR Select tests by description\.
.
.IP "\(bu" 4
\fB\-A\fR \fB\-\-autopath\fR Automatically add paths to $LOAD_PATH\.
.
.IP "\(bu" 4
\fB\-I\fR \fB\-\-loadpath <PATH>\fR Add given path to $LOAD_PATH\.
.
.IP "\(bu" 4
\fB\-C\fR \fB\-\-chdir <DIR>\fR Change directory before running tests\.
.
.IP "\(bu" 4
\fB\-R\fR \fB\-\-chroot\fR Change to project root directory before running tests\.
.
.IP "\(bu" 4
\fB\-r\fR \fB\-\-require <FILE>\fR Require file\.
.
.IP "\(bu" 4
\fB\-c\fR \fB\-\-config <FILE>\fR Use alternate config file\.
.
.IP "\(bu" 4
\fB\-V\fR \fB\-\-verbose\fR Provide extra detail in reports\.
.
.IP "\(bu" 4
\fB\-\-[no\-]ansi\fR Turn on/off ANSI colors\.
.
.IP "\(bu" 4
\fB\-\-debug\fR Turn on debugging mode\.
.
.IP "\(bu" 4
\fB\-\-about\fR Display information about rubytest\.
.
.IP "\(bu" 4
\fB\-\-version\fR Display rubytest version\.
.
.IP "\(bu" 4
\fB\-h\fR \fB\-\-help\fR Display this help message\.
.
.IP "" 0
.
.SH "RESOURCES"
.
.IP "\(bu" 4
Website \fIhttp://rubyworks\.github\.com/rubytest\-cli\fR /
.
.IP "\(bu" 4
Support \fIhttp://github\.com/rubyworks/rubytest\-cli/issues\fR /
.
.IP "\(bu" 4
Development \fIhttp://github\.com/rubyworks/rubytest\-cli\fR \~ \~
.
.IP "\(bu" 4
 \fIhttp://travis\-ci\.org/rubyworks/rubytest\-cli\fR
.
.IP "\(bu" 4
 \fIhttp://badge\.fury\.io/rb/rubytest\-cli\fR
.
.IP "" 0
.
.SH "COPYRIGHT"
Rubytest is copyrighted open\-source software\.
.
.IP "" 4
.
.nf

Copyright (c) 2013 Rubyworks\. All rights reserved\.
.
.fi
.
.IP "" 0
.
.P
It is redistributable and modifiable in accordance with the terms of the BSD\-2\-Clause license\.
.
.SH "SEE ALSO"
ruby(1)