The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

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'

DESCRIPTION

This subclass of the 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 prove runs your test script and the subtest selection is based on the value given to the --subtest option.

BACKGROUND

The Modern Perl blog entries referred to in the "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 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 Test::Named module supports this approach.

The Test::Builder::SubtestSelection class is a subclass of Test::Builder that overrides its subtest() method. It assumes that 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 -s or long --subtest option that have to be supplied together as arguments to the test script. To do so separate the arguments from prove's own arguments with the arisdottle (::).

SEE ALSO

AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

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.