Rutema Usage: Distro Test

Distro Test: Test as an Example

Distro Test is a system test for testing rutemax functionality with the MinimalXMLParser.
All relevant files are included with the rutema gem - you will find them in test/distro_test in the gem installation directory.
It's also the minimum configuration that is possible for a usable rutema system so it makes a good example to go through for usage.

The parser

The MinimalXMLParser defines the following elements:

  • echo - prints text on stdout
  • command - executes a shell command
  • prompt - asks the user a yes/no question

Attended vs. Unattended

prompt elements require user input.
Tests that include such elements cannot be executed automatically, a tester needs to attend to the execution. These tests are subsequently called attended. You can also call them manual tests. Tests that can be executed without user intervention are called unattended or automatic tests.
rutemax by default attempts to run in unattended mode.

The configuration

The configuration integrates the different parts of rutema. In the configuration you define which parser, tool and reporting addons to use as well as which tests to include for running.
The minimum you need to define is the parser and tests:
The above is the complete configuration for the distro test. It's interesting to talk about the things this configuration will not do:
  • It will not write the results in a database
  • It uses no notification plugins so no emails will be sent etc.
Entries for tools and paths are dictated by the parser implementation, that is to say the DSL we have created for the project. In this case the parser is really minimal, so no extra tools or paths are needed.
Also note that the configuration file is valid Ruby code. It can be written
require 'rake'
The above will include all .spec files for execution, while the original configuration explicitly included only 4 files.

The specifications

Described in Rutema XML Format the specifications follow a general XML schema. The actual final schema is parser and project specific - we strongly advise against using the MinimalXMLParser for anything more than a handful of test cases.


Reports and notifications are handled by Rutema:Reporter derived plugins.
rutema's strength is in providing you with a history of all the test runs, complete with output and execution times. To accomplish this some kind of repository is needed in which to save the test results. The ActiveRecordReporter uses ActiveRecord (obvious isn't it?) to save the test results in an SQLite database.
The configuration for our example using this reporter is:

configuration.reporter={:class=>Rutema::ActiveRecordReporter, :dbfile=>"sample.db"}
Configuration entries for plugins are defined as hashes. The necessary keys are also defined and validated by the plugin class.

Running the examples

The distro test files are included in the test directory of the gem.
Assuming the rutema gem is in rutema_gem_dir you can do the following:
  • rutemax -c rutema_gem_dir/test/distro_test/config/minimal.rutema #this runs all unattended tests defined in the configuration
  • rutemax -c rutema_gem_dir/test/distro_test/config/minimal.rutema attended #this runs all attended tests defined in the configuration
  • rutemax -c rutema_gem_dir/test/distro_test/config/minimal.rutema all #this runs all tests defined in the configuration
  • rutemax -c rutema_gem_dir/test/distro_test/config/database.rutema #this runs unattended tests defined in the configuration and saves them in the database
  • rutemah -c rutema_gem_dir/test/distro_test/config/database.rutemah all #this prints a list of all runs in the database
  • rutemaweb rutema_gem_dir/test/distro_test/config/sample.db #this starts a mini web server on port 7000 that allows you to browse the test database