Test::Chimps::Howto
This document briefly describes how to set up a Chimps server and a Chimps smoker to smoke a project.
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.
/usr/lib/cgi-bin
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.
Test::Chimps::Server
base_dir
/home/chimps
list_template
list.tmpl
/home/chimps/templates
variables_validation_spec
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.
http://gorilla.banana2.com/cgi-bin/chimps-server.pl
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.
chimps-smoker.pl
bin
/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
/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!
revision
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.
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.
Test::Chimps::Client
chimps-client.pl
Zev Benjamin, <zev at cpan.org>
<zev at cpan.org>
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.
bug-test-chimps at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Test::Chimps
You can also look for information at:
Mailing list
Chimps has a mailman mailing list at chimps@bestpractical.com. You can subscribe via the web interface at http://lists.bestpractical.com/cgi-bin/mailman/listinfo/chimps.
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Chimps
CPAN Ratings
http://cpanratings.perl.org/d/Test-Chimps
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Chimps
Search CPAN
http://search.cpan.org/dist/Test-Chimps
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.
To install Test::Chimps, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Chimps
CPAN shell
perl -MCPAN -e shell install Test::Chimps
For more information on module installation, please visit the detailed CPAN module installation guide.