=pod

=head1 NAME

Test::Builder::SubtestSelection - Select subtests by name or by number

=head1 SYNOPSIS

  # content of t/basic.t test script
  use strict; use warnings;

  # create test builder singleton instance first
  use Test::Builder::SubtestSelection;

  # use test builder based testing framework
  use Test::More tests => 2;

  subtest 'this' => sub {
    # this group of related test function calls
  };

  subtest 'or that' => sub {
    # or that  group of related test function calls
  };

  # at the command-line
  # run all subtests
  prove -v -b t/basic.t

  # run "this"
  prove -v -b t/basic.t :: -s 1

  # run "or that"
  prove -v -b t/basic.t :: --subtest 'or that'

=head1 DESCRIPTION

This subclass of the L<Test::Builder> class allows you to select subtests by
name or by number before running them. In your test script you have to use the
subclass before your test builder based testing framework. At the command-line
B<prove> runs your test script and the subtest selection is based on the value
given to the C<--subtest> option.

=head1 BACKGROUND

The Modern Perl blog entries referred to in the L</"SEE ALSO"> section
describe how usual Perl functions can be used to group related test function
calls inside a test script. By convention the name of each such a grouping
function should start with the C<test_> prefix. If the groups of test function
calls are independent within the test script, which is anyway a good test
discipline, it should be possible to run them individually. The L<Test::Named>
module supports this approach.

The C<Test::Builder::SubtestSelection> class is a subclass of L<Test::Builder>
that overrides its C<subtest()> method. It assumes that L<Test::Builder>
subtests are used to group related test function calls inside a test script.
The class allows you to select subtests by name or by number before running
them. The name of a subtest is more like a description. Any string is allowed
and no special naming convention needs to be followed. If possible each string
is treated as a regular expression; otherwise meta characters are properly
quoted. The selection process itself applies to top-level (not nested) subtests
only! The selection criteria (name or number) is the value of either the short
C<-s> or long C<--subtest> option that have to be supplied together as
arguments to the test script. To do so separate the arguments from B<prove>'s
own arguments with the arisdottle (C<::>).

=head1 SEE ALSO

=over 2

=item *

L<Organizing Perl Test Files|http://www.modernperlbooks.com/mt/2013/05/organizing-perl-test-files.html>

=item *

L<Running Named Perl Tests from Prove|http://www.modernperlbooks.com/mt/2013/05/running-named-perl-tests-from-prove.html>

=item *

L<Test::Named>

=back

=head1 AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Sven Willenbuecher.

This is free software; you can redistribute it and/or modify it under the
same terms as the Perl 5 programming language system itself.

=cut
