.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::API 3pm" .TH Test::API 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::API \- Test a list of subroutines provided by a module .SH "VERSION" .IX Header "VERSION" version 0.010 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Test::More tests => 3; \& use Test::API; \& \& require_ok( \*(AqMy::Package\*(Aq ); \& \& public_ok ( \*(AqMy::Package\*(Aq, @names ); \& \& import_ok ( \*(AqMy::Package\*(Aq, \& export => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ], \& export_ok => [ \*(Aqbaz\*(Aq, \*(Aqbam\*(Aq ], \& ); \& \& class_api_ok( \*(AqMy::Class\*(Aq, @methods ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This simple test module checks the subroutines provided by a module. This is useful for confirming a planned \s-1API\s0 in testing and ensuring that other functions aren't unintentionally included via import. .SH "USAGE" .IX Header "USAGE" Note: Subroutines starting with an underscore are ignored, as are a number of other methods not intended to be called directly by end-users. .PP .Vb 1 \& import unimport bootstrap \& \& AUTOLOAD BUILD BUILDARGS CLONE CLONE_SKIP DESTROY DEMOLISH \& \& TIESCALAR TIEARRAY TIEHASH TIEHANDLE \& \& FETCH STORE UNTIE FETCHSIZE STORESIZE POP PUSH SHIFT UNSHIFT SPLICE \& DELETE EXISTS EXTEND CLEAR FIRSTKEY NEXTKEY PRINT PRINTF WRITE \& READLINE GETC READ CLOSE BINMODE OPEN EOF FILENO SEEK TELL SCALAR \& \& MODIFY_REF_ATTRIBUTES MODIFY_SCALAR_ATTRIBUTES MODIFY_ARRAY_ATTRIBUTES \& MODIFY_HASH_ATTRIBUTES MODIFY_CODE_ATTRIBUTES MODIFY_GLOB_ATTRIBUTES \& MODIFY_FORMAT_ATTRIBUTES MODIFY_IO_ATTRIBUTES \& \& FETCH_REF_ATTRIBUTES FETCH_SCALAR_ATTRIBUTES FETCH_ARRAY_ATTRIBUTES \& FETCH_HASH_ATTRIBUTES FETCH_CODE_ATTRIBUTES FETCH_GLOB_ATTRIBUTES \& FETCH_FORMAT_ATTRIBUTES FETCH_IO_ATTRIBUTES .Ve .PP Therefore, do not include any of these in a list of expected subroutines. .SS "public_ok" .IX Subsection "public_ok" .Vb 1 \& public_ok( $package, @names ); .Ve .PP This function checks that all of the \f(CW@names\fR provided are available within the \&\f(CW$package\fR namespace and that *only* these subroutines are available. This means that subroutines imported from other modules will cause this test to fail unless they are explicitly included in \f(CW@names\fR. .SS "class_api_ok" .IX Subsection "class_api_ok" .Vb 1 \& class_api_ok( $class, @names ); .Ve .PP A variation of \f(CW\*(C`public_ok\*(C'\fR for object-oriented modules. Allows superclasses to fill in \*(L"missing\*(R" subroutines, but \*(L"extra\*(R" methods provided by superclasses will not cause the test to fail. .SS "import_ok" .IX Subsection "import_ok" .Vb 1 \& import_ok ( $package, %spec ); .Ve .PP This function checks that \f(CW$package\fR correctly exports an expected list of subroutines and *only* these subroutines. The \f(CW%spec\fR generally follows the style used by [Exporter], but in lower case: .PP .Vb 4 \& %spec = ( \& export => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ], # exported automatically \& export_ok => [ \*(Aqbaz\*(Aq, \*(Aqbam\*(Aq ], # optional exports \& ); .Ve .PP For \f(CW\*(C`export_ok\*(C'\fR, the test will check for public functions not listed in \&\f(CW\*(C`export\*(C'\fR or \f(CW\*(C`export_ok\*(C'\fR that can be imported and will fail if any are found. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 Test::ClassAPI \*(-- more geared towards class trees with inheritance .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone https://github.com/dagolden/Test\-API.git .Ve .SH "AUTHOR" .IX Header "AUTHOR" David Golden .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 cpansprout .IP "\(bu" 4 Toby Inkster .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2018 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve