=begin pod

=head1 NAME

Test::When - Selectively run tests based on the environment and installed modules and libs

=head1 SYNOPSIS

=begin code :lang<raku>
use Test::When <release author>,
  :modules<Extra::Features  More::Options>,
  :libs( 'someClib', any(<sqlite3 mysql pg>) );
=end code

=head1 UNIMPLEMENTED / SPEC

The C<:modules> and C<:libs> restrictions aren't yet implemented, but will
be soon. Checkout the L<SPECIFICATION|SPECIFICATION.md> for details on what
they will do.

=head1 DESCRIPTION

This module lets you write selective tests that will only run when user
requested, say, network tests to run, or when the runner of the tests
explicitly requested any interactive tests to be avoided. These checks
are heavily based on the decisions by the
L<Lancaster Consensus|https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md#environment-variables-for-testing-contexts>.

*Currently unimplemented.* The module also allows run tests only when a
specific module or C library are installed. This is handy when your
module offers extra optional functionality dependent on extra stuff, for
example.

=head1 USAGE

The type of tests your test file represents is specified on the C<use>
line of C<Test::When> module.

=head2 Environmental Variable Controlled Tests

=begin code :lang<raku>
use Test::When <author extended>;
=end code

The type of test environment to look for is set by positional arguments
provided on the C<use> line. Multiple positional arguments can be
combined. Whether your tests run depends on the set environmental
variables.

The following positional arguments are supported:

=head3 smoke

=begin code :lang<raku>
use Test::When <smoke>;
=end code

Tests to run when either C<AUTOMATED_TESTING> or C<ALL_TESTING> env
vars are true.

=head3 interactive

=begin code :lang<raku>
use Test::When <interactive>;
=end code

Tests must B<NOT> be run when C<NONINTERACTIVE_TESTING> is set to true,
unless C<ALL_TESTING> is also set to true.

=head3 extended

=begin code :lang<raku>
use Test::When <extended>;
=end code

Tests to be run when either C<EXTENDED_TESTING>, C<RELEASE_TESTING>,
or C<ALL_TESTING> env var is set to true.

=head3 release

=begin code :lang<raku>
use Test::When <release>;
=end code

Tests to be run when C<RELEASE_TESTING> or C<ALL_TESTING> env var is
set to true.

=head3 author

=begin code :lang<raku>
use Test::When <author>;
=end code

Tests to be run when C<AUTHOR_TESTING> or C<ALL_TESTING> env var is
set to true.

=head3 online

=begin code :lang<raku>
use Test::When <online>;
=end code

Tests to be run when C<ONLINE_TESTING> or C<ALL_TESTING> env var is
set to true.

=head3 Meaning of the Respected Environmental Variables

=item C<AUTOMATED_TESTING>: if true, tests are being run by an automated
testing facility and not as part of the installation of a module; smokers
must set this to true; clients (e.g. C<zef>) must not set this.

=item C<NONINTERACTIVE_TESTING>: if true, tests should not attempt to
interact with a user; output may not be seen and prompts will not be
answered.

=item C<EXTENDED_TESTING>: if true, the user or process running tests
is willing to run optional tests that may take extra time or resources
to complete. Such tests must not include any development or QA tests.
Only tests of runtime functionality should be included.

=item C<RELEASE_TESTING>: if true, tests are being run as part of a
release QA process; clients must not set this variable.

=item C<AUTHOR_TESTING>: if true, tests are being run as part of an
author's personal development process; such tests may or may not be
run prior to release. clients must not set this variable. Distribution
packagers (ppm, deb, rpm, etc.) should not set this variable.

=item C<ONLINE_TESTING>: unless true, tests must not attempt to
access a network resource (such a website or attempt to query a
network interface).

=item C<ALL_TESTING>: if true, all possible tests will be run. That
is, this module will NOT skip any tests it could possibly skip under
other environment. This B<includes> tests that require a particular
module or C library to be installed.

=head1 AUTHOR

Zoffix Znet

=head1 COPYRIGHT AND LICENSE

Copyright 2016 - 2017 Zoffix Znet

Copyright 2020 - 2026 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4
