.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Needs 3"
.TH Test::Needs 3 2023-07-26 "perl v5.38.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::Needs \- Skip tests when modules not available
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  # need one module
\&  use Test::Needs \*(AqSome::Module\*(Aq;
\&
\&  # need multiple modules
\&  use Test::Needs \*(AqSome::Module\*(Aq, \*(AqSome::Other::Module\*(Aq;
\&
\&  # need a given version of a module
\&  use Test::Needs {
\&    \*(AqSome::Module\*(Aq => \*(Aq1.005\*(Aq,
\&  };
\&
\&  # check later
\&  use Test::Needs;
\&  test_needs \*(AqSome::Module\*(Aq;
\&
\&  # skips remainder of subtest
\&  use Test::More;
\&  use Test::Needs;
\&  subtest \*(Aqmy subtest\*(Aq => sub {
\&    test_needs \*(AqSome::Module\*(Aq;
\&    ...
\&  };
\&
\&  # check perl version
\&  use Test::Needs { perl => 5.020 };
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Skip test scripts if modules are not available.  The requested modules will be
loaded, and optionally have their versions checked.  If the module is missing,
the test script will be skipped.  Modules that are found but fail to compile
will exit with an error rather than skip.
.PP
If used in a subtest, the remainder of the subtest will be skipped.
.PP
Skipping will work even if some tests have already been run, or if a plan has
been declared.
.PP
Versions are checked via a \f(CW\*(C`$module\->VERSION($wanted_version)\*(C'\fR call.
Versions must be provided in a format that will be accepted.  No extra
processing is done on them.
.PP
If \f(CW\*(C`perl\*(C'\fR is used as a module, the version is checked against the running perl
version ($]).  The version can be specified as a number,
dotted-decimal string, v\-string, or version object.
.PP
If the \f(CW\*(C`RELEASE_TESTING\*(C'\fR environment variable is set, the tests will fail
rather than skip.  Subtests will be aborted, but the test script will continue
running after that point.
.SH EXPORTS
.IX Header "EXPORTS"
.SS test_needs
.IX Subsection "test_needs"
Has the same interface as when using Test::Needs in a \f(CW\*(C`use\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP Test::Requires 4
.IX Item "Test::Requires"
A similar module, with some important differences.  Test::Requires will act
as a \f(CW\*(C`use\*(C'\fR statement (despite its name), calling the import sub.  Under
\&\f(CW\*(C`RELEASE_TESTING\*(C'\fR, it will BAIL_OUT if a module fails to load rather than
using a normal test fail.  It also doesn't distinguish between missing modules
and broken modules.
.IP Test2::Require::Module 4
.IX Item "Test2::Require::Module"
Part of the Test2 ecosystem.  Only supports running as a \f(CW\*(C`use\*(C'\fR command to
skip an entire plan.
.IP Test2::Require::Perl 4
.IX Item "Test2::Require::Perl"
Part of the Test2 ecosystem.  Only supports running as a \f(CW\*(C`use\*(C'\fR command to
skip an entire plan.  Checks perl versions.
.IP Test::If 4
.IX Item "Test::If"
Acts as a \f(CW\*(C`use\*(C'\fR statement.  Only supports running as a \f(CW\*(C`use\*(C'\fR command to skip
an entire plan.  Can skip based on subref results.
.SH AUTHORS
.IX Header "AUTHORS"
haarg \- Graham Knop (cpan:HAARG) <haarg@haarg.org>
.SH CONTRIBUTORS
.IX Header "CONTRIBUTORS"
None so far.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2016 the Test::Needs "AUTHORS" and "CONTRIBUTORS"
as listed above.
.PP
This library is free software and may be distributed under the same terms
as perl itself. See <http://dev.perl.org/licenses/>.