=head1 NAME



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


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

The call to the C<Test::Chimps::Server> constructor passes three
arguments.  The C<base_dir> argument specifies that C</home/chimps>
will be where the Chimps server will store its database, rate
limiting file, and templates.  The C<list_template> argument says
that the file C<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
C<list.tmpl> into C</home/chimps/templates>.  Finally,
C<variables_validation_spec> tells the Chimps server which report
variables the server will require.  See L<Test::Chimps/"REPORT
VARIABLES"> for more information about report variables.  There are
also many more options that can be passed to the
C<Test::Chimps::Server> constructor for specifying where things
should be stored and how to serve smoke reports.

You should now be able to hit
C<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.


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 C<chimps-smoker.pl> in
the C<bin> subdirectory.  You are going to want to copy this to

Before you can usefully run it, you are going to need to create
configuration file.  This smoker will smoke the
C<Test::Dependencies> module.  Put the following in

      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 L<Test::Chimps::Smoker/"CONFIGURATION FILE">), but
C<revision> probably needs a word of warning.  When setting up your
first project, you should set the C<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 B<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 C<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 C<Test::Chimps::Client>, which takes care
of uploading data to the server.  Take a look at
C<chimps-client.pl> in the examples subdirectory of the
Test-Chimps-Client distribution.

=head1 AUTHOR

Zev Benjamin, C<< <zev at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-test-chimps at rt.cpan.org>, or through the web interface at
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

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

    perldoc Test::Chimps

You can also look for information at:

=over 4

=item * Mailing list

Chimps has a mailman mailing list at
L<chimps@bestpractical.com>.  You can subscribe via the web
interface at

=item * AnnoCPAN: Annotated CPAN documentation


=item * CPAN Ratings


=item * RT: CPAN's request tracker


=item * Search CPAN




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.