=head1 NAME

Test::Chimps::Howto

=head1 SYNOPSIS

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

=head1 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 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.

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

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
C</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 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.

=head1 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 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
L<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.

=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
L<http://lists.bestpractical.com/cgi-bin/mailman/listinfo/chimps>.

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Test-Chimps>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Test-Chimps>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Chimps>

=item * Search CPAN

L<http://search.cpan.org/dist/Test-Chimps>

=back

=head1 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.

=cut