Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/frasertweedale/test-builder-clutch

a clutch in your TAP drivechain
https://github.com/frasertweedale/test-builder-clutch

Last synced: 6 days ago
JSON representation

a clutch in your TAP drivechain

Awesome Lists containing this project

README 

        
=head1 NAME



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



=head1 VERSION



Version 0.07



=head1 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';



   # metaprogram non-test "foo" from "foo_ok"

   Test::Builder::Clutch::antitest qw/foo_ok/;



   # metaprogram non-test "is_bar" from "bar_ok"

   Test::Builder::Clutch::antitest { 'bar_ok' => 'is_bar' };



=head1 DESCRIPTION



Perhaps you have a test that does some useful work in its own right,

but you don't want to see all the test output when it's used outside

a testing context.  Rather than writing two subroutines - one that

emits TAP and one that doesn't - you can install

C to turn the TAP on and off at will.



Routines are provided for engaging, disengaging in querying the state

of the clutch, and for metaprogramming non-test variants of test

routines..



=head1 L augmentations



C adds an attribute named C to

L, as well as C and C methods.



The C 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 C rather than C;

the "default" is necessarily undefined, and test output must remain

enabled when C is loaded.



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

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



   $Test->disengage;  # suspend test output

   $Test->engage;     # enable test output



=head2   ok



The original ok method is only invoked if the clutch in engaged, but the

C attribute is still set according the first argument.



=head2   child



The child Builder's clutch must be disengaged if the parent (that is, the

invocant) is disengaged; this wrapper takes care of that.



=head2   is_passing



If the clutch is currently engaged, defer to the original method.

If the clutch is disengaged, the test is considered to be passing

only if the original method returns true and no tests failed while

the clutch was disengaged.



=head1 SUBROUTINES



=head2   engaged



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



=head2   disengaged



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



=head2   disengage



Disable test output.



=head2   engage



Enable test output.



=head2   antitest



Metaprogram non-test versions of test methods in the calling

package.



The argument is a list of strings and hash references.  Simple

strings must refer to an existing method whose name ends with "_ok".

The non-test methods' names will have the "_ok" stripped.



Hashref arguments give test method names as keys, and the desired

names of the corresponding non-test methods as values.



If the resultant non-test methods are called from within the

pacakge, the C call must be executed in a C block.



=head1 AUTHOR



Fraser Tweedale, C<<  >>



=head1 BUGS



Please report any bugs or feature requests to C, or through

the web interface at L.  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::Builder::Clutch



You can also look for information at:



=over 4



=item * RT: CPAN's request tracker



L



=item * AnnoCPAN: Annotated CPAN documentation



L



=item * CPAN Ratings



L



=item * Search CPAN



L



=back



=head1 SEE ALSO



L provides the test features that can be enabled/disabled

courtesy of this module.



L is the amazing meta-object protocol that makes all of this

possible.



=head1 LICENSE AND COPYRIGHT



Copyright 2011 Benon Technologies Pty Ltd

Copyright 2012 Fraser Tweedale



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.