NAME
brewbuild - Automate module and reverse-dependency testing, on Windows and Unix
NOTICE
This is the first devel release that includes the entire remote dispatching/tester server distributed testing environment. Things can and will change in the next couple of weeks, and there are a lot of edge cases that don't have tests yet (so things may not work completely as expected yet). Once I've got a list of requirements sorted, the POD nice and clean, installation confirmed fully working and more testing done, I'll be bumping the version to 2.00
The module containing the API for this script can be found at Test::BrewBuild.
For running remote tester servers, see bbtester for the script and Test::BrewBuild::Tester for its API.
For the dispatcher service that distributes test runs to the remote testers, see bbdispatch for the script, and Test::BrewBuild::Dispatch for the API.
SYNOPSIS
You must be in the root directory of the distribution you want to test.
Run all unit tests against all installed instances with no other action. Upon a FAIL, a log file will be generated in the current working directory named bblog/version.bblog
brewbuild
# output
5.8.9 :: PASS
5.20.3 :: FAIL
5.22.1 :: PASS
Run tests on the local working copy of the current module, then run all tests of all reverse dependencies of this module (as reported by CPAN), to ensure the down river modules will work with your new build. In this case, FAILs are stored in bblog/revdep-module-name.version.bblog
brewbuild -R
# output, in my Mock::Sub repo directory
reverse dependencies: Test-BrewBuild, File-Edit-Portable,
Devel-Examine-Subs, Devel-Trace-Subs
Test::BrewBuild
5.18.4 :: FAIL
5.22.1 :: PASS
File::Edit::Portable
5.18.4 :: PASS
5.22.1 :: PASS
Devel::Examine::Subs
5.18.4 :: PASS
5.22.1 :: PASS
Devel::Trace::Subs
5.18.4 :: PASS
5.22.1 :: PASS
Print usage information
brewbuild -h
Display test platform setup instructions for Unix and Windows
brewbuild --setup
DESCRIPTION
This brewbuild
script installed by the Test::Brewbuild module allows you to perform your unit tests seamlessly across all of your Perlbrew (Unix) or Berrybrew (Windows) Perl instances, as well as test all of your down-river CPAN modules that rely on your module against the locally updated version, with support for ExtUtils::MakeMaker, Module::Build and Dist::Zilla distributions.
For Windows, you'll need to install Berrybrew (see "SEE ALSO" for details). For Unix, you'll need Perlbrew.
It allows you to remove and reinstall on each test run, install random versions of perl and install specific versions.
All unit tests are run against all installed perl
instances, unless otherwise specified.
USAGE
--on, -o
Perl version number to run against (can be supplied multiple times). Can not be used on Windows at this time.
--revdep, -R
Run tests, install, then run tests on all CPAN reverse dependency modules.
--debug, -d
0-7, sets logging verbosity, default is 0.
--new, -n
How many random versions of perl to install (-1 to install all).
--remove, -r
Remove all installed perls (less the currently used one).
--install, -i
Number portion of an available perl version according to *brew available
. Multiple versions can be sent in at once.
--notest, -N
Do not run tests. Allows you to --remove and --install without testing.
--save, -S
By default, we save logs of FAIL
result logs into the bblog
directory. With this flag, we'll save both the FAIL
logs along with all the PASS
logs as well.
--legacy, -l
Operate on perls less than 5.8.x. The default plugins won't work with this flag set if a lower version is installed.
--plugin, -p
Optional module name of the exec command plugin to use.
--args, -a
List of args to pass into the plugin (one arg per loop).
--selftest, -T
Test::BrewBuild
development testing only. Prevents recursive test loops.
--setup, -s
Display test platform setup instructions.
--help, -h
Print out help contents.
TEST PLATFORM CONFIGURATION
Test::BrewBuild
test platform configuration guide
UNIX
Install perlbrew and related requirements:
cpanm App::perlbrew
perlbrew install-patchperl
perlbrew install-cpanm
Install and switch to your base perl instance, and install Test::BrewBuild
:
perlbrew install 5.22.1
perlbrew switch 5.22.1
cpanm Test::BrewBuild
WINDOWS
Note that the key here is that your %PATH% must be free and clear of anything Perl. That means that if you're using an existing box with Strawberry or ActiveState installed, you *must* remove all traces of them in the PATH environment variable for ``brewbuild'' to work correctly.
Easiest way to guarantee a working environment is using a clean-slate Windows server with nothing on it. For a Windows test platform, I mainly used an Amazon AWS t2.small server.
Download/install git for Windows:
https://git-scm.com/download/win
Create a repository directory, and enter it:
mkdir c:\repos
cd c:\repos
Clone and configure berrybrew
git clone https://github.com/dnmfarrell/berrybrew
cd berrybrew
bin\berrybrew.exe config (type 'y' when asked to install in PATH)
Close the current CMD window and open a new one to update env vars
Check available perls, and install one that'll become your core base install
berrybrew available
berrybrew install 5.22.1_64
berrybrew switch 5.22.1_64
close CMD window, and open new one
Make sure it took
perl -v
Install Test::BrewBuild
cpanm Test::BrewBuild
AUTHOR
Steve Bertrand, <steveb at cpan.org>
CONTRIBUTING
Any and all feedback and help is appreciated. A Pull Request is the preferred method of receiving changes (https://github.com/stevieb9/p5-test-brewbuild), but regular patches through the bug tracker, or even just email discussions are welcomed.
BUGS
https://github.com/stevieb9/p5-test-brewbuild/issues
SUPPORT
You can find documentation for this script and module with the perldoc command.
perldoc brewbuild
perldoc Test::BrewBuild
Documentation for the remote testing service script, and its API:
perldoc bbtester
perldoc Test::BrewBuild::Tester
Documentation for the test dispatching script and its API:
perldoc bbdispatch
perldoc Test::BrewBuild::Dispatch
SEE ALSO
Berrybrew for Windows:
https://github.com/dnmfarrell/berrybrew
Perlbrew for Unixes:
Remote testing server:
<a href="https://metacpan.org/pod/distribution/Test-BrewBuild/bin/bbtester>bbtester</a>
Remote testing server API:
Dispatching to remote testers:
See brewbuild -h
, in the Dispatching Server options
section.
Dispatcher API:
LICENSE AND COPYRIGHT
Copyright 2016 Steve Bertrand.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.