/ 
Test-Chimps-0.07
River stage one • 1 direct dependent • 1 total dependent
/ Test::Chimps::Howto

NAME

Test::Chimps::Howto

SYNOPSIS

This document briefly describes how to set up a Chimps server and a Chimps smoker to smoke a project.

THE SERVER

We will be setting up a smoke server for an imaginary company called Bananas 2.0, who make a trendy AJAX website for ordering bananas for primates online. To install the Chimps server, install the Test::Chimps package from CPAN on the machine that will be hosting the server CGI (in this case gorilla.bananas2.com).

root@gorilla:~# cpan Test::Chimps

This will install the various libraries that Chimps needs on the server-side. Next, you are going to need to create the server CGI. There is an example in the Test-Chimps distribution that looks a lot like this:

#!/usr/bin/env perl

use Test::Chimps::Server;

my $server = Test::Chimps::Server->new(
  base_dir                  => '/home/chimps',
  list_template             => 'list.tmpl',
  variables_validation_spec => {
    project   => 1,
    revision  => 1,
    committer => 1,
    duration  => 1,
    osname    => 1,
    osvers    => 1,
    archname  => 1
  }
);

$server->handle_request;

This file should be put somewhere where the webserver can execute CGIs. In this case, it will be dropped in /usr/lib/cgi-bin and called chimps-server.pl.

The call to the Test::Chimps::Server constructor passes three arguments. The base_dir argument specifies that /home/chimps will be where the Chimps server will store its database, rate limiting file, and templates. The list_template argument says that the file list.tmpl will be used as the template for the front page (where smoke reports are listed). This file can be found in the examples subdirectory of the Test-Chimps distribution (and it's too large to reproduce here). You should drop list.tmpl into /home/chimps/templates. Finally, variables_validation_spec tells the Chimps server which report variables the server will require. See "REPORT VARIABLES" in Test::Chimps for more information about report variables. There are also many more options that can be passed to the Test::Chimps::Server constructor for specifying where things should be stored and how to serve smoke reports.

You should now be able to hit http://gorilla.banana2.com/cgi-bin/chimps-server.pl and see an empty listing of smoke reports. We'll fix the problem of it being empty in the next section.

THE SMOKER

One common way of running a smoke server is for one box to run both the server CGI and the smoker process. We are going to adopt this model because I don't want to have to come up with another monkey-related hostname, but the smoker could just as easily run on another box.

Install the Chimps client utilities by installing Test::Chimps::Client from CPAN:

root@gorilla:~# cpan Test::Chimps::Client

The distribution comes with program called chimps-smoker.pl in the bin subdirectory. You are going to want to copy this to /home/chimps/bin.

Before you can usefully run it, you are going to need to create configuration file. This smoker will smoke the Test::Dependencies module. Put the following in /home/chimps/smoker-config.yml:

---
Test-Dependencies:
  configure_cmd: perl Makefile.PL --defaultdeps && make
  revision: 5751
  root_dir: .
  svn_uri: svn://svn.bestpractical.com/svn/bps-public/Test-Dependencies/trunk

Most of the options are pretty straightforward (you can read about the rest in "CONFIGURATION FILE" in Test::Chimps::Smoker), but revision probably needs a word of warning. When setting up your first project, you should set the revision number to some relatively recent revision of your repository. If you set it to 0, chimps will try to smoke every revision of your project. You probably do not want this!

Now, just start up the smoker. You might want to run it in a screen session so that it doesn't die when your terminal exits. You also probably want to redirect its output to a file so that you can look at what went wrong if your projects fail tests.

chimps@gorilla:~$ bin/chimps-smoker.pl -s http://gorilla.banana2.com/cgi-bin/chimps-server.pl &> log

That's it! You now have a smoker that will continually check out new revisions of Test::Dependencies, run the test suite, and upload the results to the Chimps server for display on your website. You can add more projects as necessary to the configuration file.

OTHER CONFIGURATIONS

You do not have to run a smoker. If you'd rather have smoke tests part of your build process (and maybe allow anyone building your module to submit smoke reports), or do something else more complicated, you can use Test::Chimps::Client, which takes care of uploading data to the server. Take a look at chimps-client.pl in the examples subdirectory of the Test-Chimps-Client distribution.

AUTHOR

Zev Benjamin, <zev at cpan.org>

BUGS

Please report any bugs or feature requests to bug-test-chimps at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Chimps. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Test::Chimps

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2006 Best Practical Solutions.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.