Rake Runner Documentation

Added by Yegor Yarko, last edited by Roman Chernyatchik on May 26, 2008  (view change)

Rake Runner Documentation

This document covers:

Installation

  1. Download the plugin archive: rakeRunnerPlugin-XXXX.zip
  2. Unpack the content of rakeRunnerPlugin-XXXX.zip/webapps/ROOT directory into <TeamCity web application directory>
    <TeamCity web application directory> is <TeamCity home>/webapps/ROOT for .exe and tar.gz TeamCity installations.

Environment Setup

  1. Build Agent Requirements
    Install Ruby 1.8.6 with the following gems:
    You can install several Ruby interpreters in different folders. Then you should add several environment variables (or setup them in build agent configuration properties) and then you will be able to use them in Rake Runner Configuration (see Known Issues section below, RSpec bug). Or install one Ruby interpreter and add it to PATH variable.
    • rake 0.7.3 or higher
    • builder
      'rake' and 'builder' gems are mandatory and must be installed.
    • rspec 1.1.3 (optional)
    • All necessary gems for your Ruby (or ROR) projects
      To install a gem execute: 
      gem install <gem's name>

      You can refer to the Ruby Gems Manuals for more information.

  2. Set up Build Configuration
    1. Set up build configuration and set "Rake" build runner.
    2. Setup runner options:
      1. In the Rake tasks field enter names of Rake tasks
      2. If Ruby Interpreter isn't in the PATH on build agents, enter path in Ruby interpreter path text field (see Rake Build Runner Settings for description of other parameters).
      3. Save configuration and run build.

Rake Build Runner Settings

This section contains reference information about the Rake Build Runner fields.

Option Description
Build runner Select Rake from the drop-down list.

Rake Parameters

Option Description
Path to a Rakefile file Enter Rakefile path if you don't want to use a default one. Specified path should be relative to the checkout directory.
Rakefile content Enter the Rakefile content in Web UI instead of using existing Rakefile. Plugin will create corresponding Rakefile dynamically before running Rake.
Working directory Optional, specify if differs from the checkout directory.
Rake tasks Enter tasks names separated by space character if you don't want to use 'default' task. For example: 
test:functionals

or

mytask:test mytask:test2
Additional Rake command line parameters If not empty, these parameters will be added to 'rake' command line. The command line will look like 
ruby rake <Additional Rake command line parameters> <Teamcity Rake Runner options, e.g TESTOPTS> <tasks names>

Launching Parameters

Option Description
Ruby interpreter path Path to Ruby interpreter (Ruby or JRruby). If not specified the interpreter will be searched in the PATH.
In Ruby interpreter path field you can use values of environment and system variables. For example: 
%env.I_AM_DEFINED_IN_BUILDAGENT_CONFIGURATION%
Debug Track invoke/execute stages — if selected, Invoke stage will be also shown in the build log.

Tests Parameters

Option Description
Tests options(TESTOPTS) Additional options of Test::Unit test runner. If specified Rake will be invoked with a "TESTOPTS={options}".
RSpec options(SPEC_OPTS) Additional options of RSpec specs runner. If specified Rake will be invoked with a "SPEC_OPTS={options}". For example: 
--format html:rspec_html_resut.html

Including HTML Reports into the Build Results

You can include RCov and RSpec HTML reports right in the build results. See corresponding TeamCity documentation section.

  1. Add 
    --format html:rspec_html_resut.html

    to the Rake Runner RSpec options (SPEC_OPTS) on the Rake Runner Settings page

  2. Add 
    coverage=>coverage, rspec_html_resut.html

    to the build configuration artifacts on the General Settings page of the Build Configuration.

  3. Add 
    <report-tab title="RSpec Report" basePath="." startPage="rspec_html_resut.html" />
<report-tab title="RCov Report" basePath="coverage" />

    to the <TeamCity data directory>/config/main-config.xml file

  4. Update your build script to delete coverage folder and rspec_html_resut.html file from your project sources's directory to ensure previous build results does not affect new build run. By default, TeamCity does not delete those folder and file from the sources.

Miscellaneous

  • Ruby's pending specs are shown as Ignored Tests in the Overwiew tab.
  • Rake Runner plugin uses its own unit tests runner and loads it using RUBYLIB environment variable. You need to ensure your program doesn't clear this environment variable, but you may append your paths to it.
  • If you run RSpec with the '--color' option enabled under Windows OS, RSpec will suggest you install the win32console gem. This warning will appear in your build log, but you can ignore it. TeamCity Rake Runner Plugin doesn't support coloured output in the build log and doesn't use this feature.
  • If you want to run builds, tests and specs on JRuby, you should disable pretty output capturing by defining an environment variable teamcity.rake.runner.debug.output.capturer.disabled in the build configuration properties. All captured output will be displayed at the end of the build log.
  • Rake Runner Plugin runs spec examples with a custom formatter. If you use additional console formatter, your build log will contain redundant information.
  • Spec::Rake::SpecTask.spec_opts is affected by SPEC_OPTS command line parameter. Rake Runner Plugin always uses SPEC_OPTS to setup its custom formatter. Thus you should set up Spec Options in Web UI.
  • When reporting issues, you can look up version of the Rake Runner plugin in rakeRunnerPluginAgent.zip/version (agent plugin), and rakeRunnerPluginServer.jar/version (server plugin).

Known Issues

  1. RSpec bug : [#18447] Problem with running spec task when several ruby interpreters are installed(or http://rspec.lighthouseapp.com : [#345]).
  2. If your Rake tasks run in parallel in the scope of one build, the build output and tests results will be inaccurate.

Labels