The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Test-Builder-Clutch-0.03
River stage zero No dependents
/ Test::Builder::Clutch

NAME

Test::Builder::Clutch - add a clutch to your testing drivechain

VERSION

Version 0.03

SYNOPSIS

   use Test::Builder::Clutch;

   # suspend test output
   Test::Builder::Clutch::disengage;

   # enable test output again
   Test::Builder::Clutch::engage;

   # is the clutch engaged?
   Test::Builder::Clutch::engaged ? 'yes' : 'no';
   Test::Builder::Clutch::disengaged ? 'no' : 'yes';

DESCRIPTION

There are many cases where you have a procedure that you might sometimes want to run in a test-like fashion, and other times just run. Rather than having two subroutines, one that emits tests and one that doesn't, doesn't it make more sense to install a clutch?

Test::Builder::Clutch installs a clutch in Test::Builder. Since Test::Builder is the base class for a great many test modules, and since it's singleton-ish, you have a single interface (most of the time) for engaging and disengaging test output.

Test::Builder augmentations

Test::Builder::Clutch adds an attribute named disengaged to Test::Builder, as well as disengage and engage methods.

The disengaged attribute actually cannot be initialised, since the singleton Test::Builder is created when Test::Builder is loaded. This is the reason the attribute is called disengaged rather than engaged; the "default" is necessarily undefined, and test output must remain enabled when Test::Builder::Clutch is loaded.

   $Test->disengaged(1);  # suspend test output
   $Test->disengaged(0);  # enable test output

   $Test->disengage;  # suspend test output
   $Test->engage;     # enable test output

ok

The original ok method is only invoked if the clutch in engaged, but the is_passing attribute is still set according the first argument.

child

The child Builder's clutch must be disengaged if the parent (that is, the invocant) is disengaged; this wrapper takes care of that.

is_passing

If the clutch is currently engaged, simply defers to the original method. If the clutch is disengaged, the test is considered to be passing only if the original method returns true, and we have also not failed any tests and any point while the clutch was disengaged.

SUBROUTINES

engaged

Return true if the clutch is currently engaged, otherwise false.

disengaged

Return true if the clutch is currently disengaged, otherwise false.

disengage

Disable test output.

engage

Enable test output.

AUTHOR

Fraser Tweedale, <frasert at jumbolotteries.com>

BUGS

Please report any bugs or feature requests to bug-test-clutch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Builder-Clutch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

    perldoc Test::Builder::Clutch

You can also look for information at:

SEE ALSO

Test::Builder provides the test features that can be enabled/disabled courtesy of this module.

Class::MOP is the amazing meta-object protocol that makes all of this possible.

LICENSE AND COPYRIGHT

Copyright 2011 Benon Technologies Pty Ltd

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.