Test::Block(3pm)

📦
version 0.13 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

🦋 Test::Block — the manual, but make it make sense

okay so bestie, welcome to the docs for Test::Block, a little Perl module from the User Contributed Perl Documentation corner of the universe. It's Test::Block(3pm) if you're being formal about it. Sit down, grab a boba, we're gonna talk about test plans that are ✨granular✨.

✨ NAME ✨

Test::Block — DEPRECIATED: Specify fine granularity test plans

(no cap, that's the actual word in the docs — we keep it exactly as the author wrote it 💅)

🌸 SYNOPSIS 🌸

  use Test::More 'no_plan';
  use Test::Block qw($Plan);

  {
      # This block should run exactly two tests
      local $Plan = 2;
      pass 'first test';
      # oops. forgot second test
  };

  SKIP: {
      local $Plan = 3;
      pass('first test in second block');
      skip "skip remaining tests" => $Plan;
  };

  ok( Test::Block->all_in_block, 'all test run in blocks' );
  is( Test::Block->block_count, 2, 'two blocks ran' );

  # This produces...

  ok 1 - first test
  not ok 2 - block expected 2 test(s) and ran 1
  #     Failed test (foo.pl at line 6)
  ok 3 - first test in second block
  ok 4 # skip skip remaining tests
  ok 5 # skip skip remaining tests
  ok 6 - all test run in blocks
  ok 7 - two blocks ran
  1..7
  # Looks like you failed 1 tests of 7.

see how the block snitched on itself when a test went missing? iconic behaviour honestly 🫶

💖 DESCRIPTION 💖

NOTE: This module was written before subtests existed in TAP and Test::More. These days subtests will probably be a better option for you.

fr fr, read that twice. This module is old-school cool, but subtests are the modern glow-up.

So what does it actually do? It lets you specify the number of expected tests at a finer level of granularity than an entire test script. Not the whole file — just a block. A little zone. A vibe-contained region of tests 🎀

It's built with Test::Builder and plays happily with Test::More and friends. Besties, they get along.

If you are not already familiar with Test::More, now would be the time to go take a look. Like, go. We'll wait. 🌈

🧚 Creating test blocks

Test::Block supplies a special variable $Plan that you can localize to specify the number of tests in a block, like this:

    use Test::More 'no_plan';
    use Test::Block qw($Plan);

    {
        local $Plan = 2;
        pass('first test');
        pass('second test');
    };

that's it. that's the whole thing. local $Plan = 2; and the block knows its destiny ✨

😭 What if the block runs a different number of tests?

If a block doesn't run the number of tests specified in $Plan, then Test::Block will automatically produce a failing test. Like, it will call you out. Gently. Publicly.

For example:

    {
        local $Plan = 2;
        pass('first test');
        # oops - forgot second test
    };

will output

    ok 1 - first test
    not ok 2 - block 1 expected 2 test(s) and ran 1

"block 1 expected 2 test(s) and ran 1" — read it and weep 🥲

👑 Tracking the number of remaining tests

During the execution of a block, $Plan will contain the number of remaining tests that are expected to run. So:

    {
        local $Plan = 2;
        diag "$Plan tests to run";
        pass('first test');
        diag "$Plan tests to run";
        pass('second test');
        diag "$Plan tests to run";
    };

will produce

    # 2 tests to run
    ok 1 - first test
    # 1 tests to run
    ok 2 - second test
    # 0 tests to run

the countdown realness!! ⏳

This can make skip blocks easier to write and maintain, for example:

    SKIP: {
        local $Plan = 5;
        pass('first test');
        pass('second test');
        skip "debug tests" => $Plan unless DEBUG > 0;
        pass('third test');
        pass('fourth test');
        skip "high level debug tests" => $Plan unless DEBUG > 2;
        pass('fifth test');
    };

🎀 Named blocks

To make debugging easier you can give your blocks an optional name like this:

    {
        local $Plan = { example => 2 };
        pass('first test');
        # oops - forgot second test
    };

which would output

    ok 1 - first test
    not ok 2 - block example expected 2 test(s) and ran 1

now the failure has a name. it's giving personalized disappointment 💀

💅 Test::Block objects

The $Plan is implemented using a tied variable that stores and retrieves Test::Block objects. If you want to avoid the tied interface you can use Test::Block objects directly.

plan

      # create a block expecting 4 tests
      my $block = Test::Block->plan(4);

      # create a named block with two tests
      my $block = Test::Block->plan('test name' => 2);

You create Test::Block objects with the "plan" method. When the object is destroyed it outputs a failing test if the expected number of tests have not run. (yes, destruction = judgement. that's the deal 🫠)

remaining

You can find out the number of remaining tests in the block by calling the "remaining" method on the object.

Test::Block objects overload "" and "0+" to return the result of the remaining method. so it stringifies and numifies into the remaining count — cute, useful, slay.

builder

Returns Test::Builder object used by Test::Block. For example:

      Test::Block->builder->skip('skip a test');

See Test::Builder for more information.

block_count

A class method that returns the number of blocks that have been created. You can use this to check that the expected number of blocks have run by doing something like:

      is( Test::Block->block_count, 5, 'five blocks run' );

at the end of your test script. it's the receipts for your blocks 🧾

all_in_block

Returns true if all tests so far run have been inside the scope of a Test::Block object.

      ok( Test::Block->all_in_block, 'all tests run in blocks' );

💀 BUGS 💀

None known at the time of writing.

If you find any please let me know by e-mail, or report the problem with http://rt.cpan.org/.

🌈 COMMUNITY 🌈

perl-qa

If you are interested in testing using Perl I recommend you visit http://qa.perl.org/ and join the excellent perl-qa mailing list. See http://lists.perl.org/showlist.cgi?name=perl-qa for details on how to subscribe.

perlmonks

You can find users of Test::Block, including the module author, on http://www.perlmonks.org/. Feel free to ask questions on Test::Block there.

CPAN::Forum

The CPAN Forum is a web forum for discussing Perl's CPAN modules. The Test::Block forum can be found at http://www.cpanforum.com/dist/Test-Block.

AnnoCPAN

AnnoCPAN is a web site that allows community annotations of Perl module documentation. The Test::Block annotations can be found at http://annocpan.org/~ADIE/Test-Block/.

⭐ TO DO ⭐

If you think this module should do something that it doesn't (or does something that it shouldn't) please let me know.

You can see my current to do list at http://adrianh.tadalist.com/lists/public/15423, with an RSS feed of changes at http://adrianh.tadalist.com/lists/feed_public/15423.

🫶 ACKNOWLEDGMENTS 🫶

Thanks to chromatic and Michael G Schwern for the excellent Test::Builder, without which this module wouldn't be possible.

Thanks to Michael G Schwern and Tony Bowden for the mails on perl-qa@perl.org that sparked the idea for this module. Thanks to Fergal Daly for suggesting named blocks. Thanks to Michael G Schwern for suggesting $Plan. Thanks to Nadim Khemir for feedback and Andreas Koenig for spotting bugs.

🌸 AUTHOR 🌸

Adrian Howard <adrianh@quietstars.com>

If you can spare the time, please drop me a line if you find this module useful.

👑 SEE ALSO 👑

Test::Group

A framework for grouping related tests in a test suite

Test::Class

Test::Class is an xUnit testing framework for Perl. It allows you to group tests into methods with independent test plans.

Test::Builder

Support module for building test libraries.

Test::Simple & Test::More

Basic utilities for writing tests.

http://qa.perl.org/test-modules.html

Overview of some of the many testing modules available on CPAN.

💖 LICENCE 💖

Copyright 2003-2006 Adrian Howard, All Rights Reserved.

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

and that's the whole page bestie!! 🎀 this doc came to you courtesy of perl v5.36.0, dated 2022-12-07, and no, we did not touch a single flag, default, or URL in the making of this vibe check. go forth and local $Plan responsibly. periodt. ✨💅🦋

📦 where this page comes from