/ 
hub-standard-04.00.012
/ hubtest

NAME

hubtest - Hub Library Testcase Extraction

SYNOPSIS

Test cases are embedded in source code. This helps code stability by allowing the maintainer to comprehend and update method APIs. Moreover, testcase extraction allows the correct usage to be detailed in the documentation (which is likely easier to understand than the author's description.)

DESCRIPTION

Tests are extracted from the source-code comments. The beginning of the test is identified by '#|test(...)', and continues on all consecutive lines which begin with '#|':

#|test(false)   my $var = "abc";
#|              $var =~ /[A-Z]/;

Alternatively, test blocks may be in POD syntax, as:

=test(false)

    my $var = "abc";
    $var =~ /[A-Z]/;

=cut

Test types

Test types (the word within parenthesis) are restricted to the following:

[!]true     returns a true value
[!]false    returns a false value
[!]defined  returns a defined value
[!]abort    aborts via die|carp|croak|...
[!]match    (see below)
[!]regex    like 'match', except the pattern is considered a regex

When the type is [!]match, the result of the test is listed after the test, and prefixed with '#~'. Decorative white-space is removed from lines which begin with '#|' or '#~':

#|test(match)   my ($state) = $address =~ /([A-Z][A-Z]), \\d+\\Z/;
#|              return $state;
#| 
#~              WA
#~

Additionally, [!]match test results may be written on the test-line:

#|test(match,ABC) uc('abc')

POD Syntax

Test blocks in POD syntax, use '=result' to specify the result:

=test(match)

    uc('abc');

=result

    ABC

=cut

White space

If the decorative white-space is critical in testing the return value, we use '#=' instead of '#~':

#|test(match)   my $fh = IO::File->new();
#|              open $fh, "</etc/passwd" or die "$\!: /etc/passwd";
#|              my @lines = <$fh>;
#|              close $fh;
#|              map { print $_ } @lines;
#~
#=SYSTEM:*:18:544:,S-1-5-18::
#=Administrators:*:544:544:,S-1-5-32-544::
#=...
#~

POD syntax always removes the decorative white-space.

The '#|', '#~', and '#=' identifiers must be at the beginning of the line. This these considered a normal comments:

##| Does not match "^#"
  #| White-space (indenting) not honored

Documentation

For documentation purposes, the test may have a one-line summary, which is formed when either: The test-line only contains a comment

#|test(match) # Test for empty files
#|...

Or, the test is a single line which ends with a comment:

#|test(true) my $s = "Abc"; $s =~ /\A[A-Z][a-z]+\Z/; # Capital word

In this second case, the triggering pattern is ';\s*#\s*(.*)\Z', meaning that the semicolon (;) before the comment is crucial.

EXAMPLES

Four ways to do the same thing:

#|test(match,ABC) uc('abc')

#|test(match) uc('abc')
#=ABC

=test(match,ABC) uc('abc')
=cut

=test(match) uc('abc')
=result ABC
=cut

AUTHOR

Ryan Gies (ryangies@livesite.net)

COPYRIGHT

Copyright (C) 2006-2007 by Livesite Networks, LLC. All rights reserved.

Copyright (C) 2000-2005 by Ryan Gies. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

* Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

* The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To the best of our knowledge, no patented algorithms have been used. However, we do not have the resources to carry out a patent search, and therefore cannot give any guarantee of the above statement.

UPDATED

06/09/2007