/ 
Test-BrewBuild-2.06
River stage zero No dependents
/ brewbuild

NAME

brewbuild - Automate module and reverse-dependency testing, on Windows and Unix

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

Send a basic test run to remote testers (see bbdispatch for more complex dispatching):

brewbuild -D -t localhost -t 192.168.252.90 -t 192.168.252.96 -t 192.168.252.95

192.168.252.95 - x86_64-linux

5.22.1 :: PASS

192.168.252.90 - MSWin32-x64-multi-thread

5.18.4 :: PASS
5.22.1 :: PASS

localhost - MSWin32-x64-multi-thread

5.22.1 :: FAIL

192.168.252.96 - amd64-freebsd

5.22.1 :: PASS
5.23.7 :: PASS
5.8.9 :: FAIL
5.10.1 :: FAIL
5.18.4 :: FAIL

All FAIL log files are stored locally when dispatching to identify the issues:

192.168.252.96_5.10.1-FAIL.bblog
192.168.252.96_5.18.4-FAIL.bblog
192.168.252.96_5.8.9-FAIL.bblog
localhost_5.22.1-FAIL.bblog

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.

It also allows you to dispatch basic test runs to remote testing servers.

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

Many of the options listed below can be saved in a configuration file if you want to set them permanently, or override defaults. Arguments passed in on the command line override those in the configuration file. See Test::BrewBuild::brewbuild.conf.

-o, --on

Perl version number to run against (can be supplied multiple times). Can not be used on Windows at this time.

-R, --revdep

Run tests, install, then run tests on all CPAN reverse dependency modules.

-d, --debug

0-7, sets logging verbosity, default is 0.

-n, --new

How many random versions of perl to install (-1 to install all). On Windows, we'll default to installing 64-bit versions only, if a 64 bit perl is available for the version desired. See the --install flag if you'd like to install 32-bit versions, where both versions are present.

-i, --install

Number portion of an available perl version according to *brew available. Multiple versions can be sent in at once.

On Windows, by default, we install only 64-bit versions. You can append the _32 or _64 suffixes as displayed by berrybrew available to override the default. If you're dispatching to both Unix and Windows systems, we'll strip this suffix on the Unix systems before performing any actions.

-r, --remove

Remove all installed perls (less the currently used one).

-D, --dispatch

Sends a basic test run to remote Test::BrewBuild test servers, which are specified with the -t|--tester flag. We'll get the repository inforation out of your current working directory, and simply run brewbuild with no arguments on the testers (all other flags are removed if -D is used).

For more expansive dispatching functionality, see bbdispatch.

-t, --tester

Used only with the -D flag, specify a tester for the dispatcher to dispatch to, in the form host_or_ip[:port].

-N, --notest

Do not run tests. Allows you to --remove and --install without testing.

-S, --save

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.

-l, --legacy

Operate on perls less than 5.8.x. The default plugins won't work with this flag set if a lower version is installed.

-p, --plugin

Optional module name of the exec command plugin to use. You can also specify a file name if the module is not installed.

-a, --args

List of args to pass into the plugin (one arg per loop).

-T, --selftest

Test::BrewBuild development testing only. Prevents recursive test loops.

-s, --setup

Display test platform setup instructions.

-h, --help

Print out the command line usage information.

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 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)

Note: I have forked and hacked berrybrew with a few changes which makes it play nicer with brewbuild (and adds the --with feature for exec) if you're interested. My changes haven't been merged yet, so you can fetch it from here.

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:

http://perlbrew.pl

Remote testing server:

brewbuild

Remote testing server API:

Test::BrewBuild::Tester

Dispatching to remote testers:

See brewbuild -h, in the Dispatching Server options section.

Dispatcher API:

Test::BrewBuild::Dispatch

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.