/ 
Test2-Plugin-SubtestFilter-0.01
/ Test2::Plugin::SubtestFilter

NAME

Test2::Plugin::SubtestFilter - Filter subtests by name

SYNOPSIS

# t/test.t
use Test2::V0;
use Test2::Plugin::SubtestFilter;

subtest 'foo' => sub {
    ok 1;
    subtest 'bar' => sub { ok 1 };
};

subtest 'baz' => sub {
    ok 1;
};

done_testing;

Then run with filtering:

# Run only 'foo' subtest and all its children
$ SUBTEST_FILTER=foo prove -lv t/test.t

# Run nested 'bar' subtest (and its parent 'foo')
$ SUBTEST_FILTER=bar prove -lv t/test.t

# Use regex patterns
$ SUBTEST_FILTER='ba' prove -lv t/test.t  # Matches 'bar' and 'baz'

# Run all tests (no filtering)
$ prove -lv t/test.t

DESCRIPTION

Test2::Plugin::SubtestFilter is a Test2 plugin that allows you to selectively run specific subtests based on environment variables. This is useful when you want to run only a subset of your tests during development or debugging.

FILTERING BEHAVIOR

The plugin matches subtest names using partial matching (substring or regex pattern). For nested subtests, the full name is constructed by joining parent and child names with spaces.

How Matching Works

  • Simple match

    subtest 'foo' => sub { ... };
# SUBTEST_FILTER=foo matches 'foo'
# SUBTEST_FILTER=fo  matches 'foo' (partial match)

  • Nested subtest match

    subtest 'parent' => sub {
    subtest 'child' => sub { ... };
};
# Full name is: 'parent child'
# SUBTEST_FILTER=child         matches 'parent child'
# SUBTEST_FILTER='parent child' matches 'parent child'

  • When parent matches

    When a parent subtest matches the filter, ALL its children are executed.

    SUBTEST_FILTER=parent prove -lv t/test.t
# Executes 'parent' and all nested subtests inside it

  • When child matches

    When a nested child matches the filter, its parent is executed but only the matching children run. Non-matching siblings are skipped.

    SUBTEST_FILTER=child prove -lv t/test.t
# Executes 'parent' (to reach 'child') but skips other children

  • No match

    Subtests that don't match the filter are skipped.

  • No filter set

    When SUBTEST_FILTER is not set, all tests run normally.

ENVIRONMENT VARIABLES

  • SUBTEST_FILTER

    Regular expression pattern for partial matching against subtest names. Supports both substring matching and full regex patterns.

    SUBTEST_FILTER=foo      # Matches 'foo', 'foobar', 'my foo test', etc.
SUBTEST_FILTER='foo.*'  # Matches 'foo', 'foobar', 'foo_test', etc.
SUBTEST_FILTER='foo|bar' # Matches 'foo' or 'bar'

CAVEATS

  • This plugin must be loaded AFTER Test2::V0 or Test2::Tools::Subtest, as it needs to override the subtest function that they export.

  • The plugin modifies the subtest function in the caller's namespace, which may interact unexpectedly with other code that also modifies subtest.

SEE ALSO

LICENSE

Copyright (C) kobaken.

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

AUTHOR

kobaken <kentafly88@gmail.com>