Test2::Workflow(3perl)

📦

version 5.44.0 · 8 versions

💖 Test2::Workflow — the `Test2::Workflow(3perl)` page, but make it slay 💖

okay bestie, so this is the manual for Test2::Workflow from the Perl Programmers Reference Guide, and it's genuinely one of those "once you get it you're obsessed" modules. let's go 🫶

✨ NAME ✨

Test2::Workflow — a test workflow is a way of structuring tests using composable units. periodt.

🌸 DESCRIPTION 🌸

A test workflow is a way of structuring tests using composable units. like, you build tests out of little Lego pieces instead of one giant sad script. The most famous example of a test workflow is RSPEC (that's at http://rspec.info/ if you wanna peek). And RSPEC? it's implemented using Test2::Workflow inside Test2::Tools::Spec, plus a handful of extensions. no cap. 💅

👑 IMPORTANT CONCEPTS 👑

these are the main characters, learn their names:

🎀 BUILD 🎀

Test2::Workflow::Build

A Build is used to compose tasks. Usually a build object is pushed to the stack before running code that adds tasks to the build. Once the build sub is complete, the build is popped and returned. Usually a build is converted into a root task or task group. it's giving assembly line, fr fr ✨

🦋 RUNNER 🦋

Test2::Workflow::Runner

A runner takes the composed tasks and executes them in the proper order. that's it, that's the job, and it eats every time. 🔥

🧚 TASK 🧚

Test2::Workflow::Task

A task is a unit of work to accomplish. There are 2 main types of task, and they're a whole duo:

💜 ACTION 💜

An action is the most simple unit used in composition. An action is essentially a name and a codeblock to run. small, iconic, does one thing.

💜 GROUP 💜

A group is a task that is composed of other tasks. it's a task made of tasks. inception but make it organized. 🌀

⭐ EXPORTS ⭐

💡 All exports are optional, bestie — you must request the ones you want. nothing shows up uninvited.

$parsed = parse_args(args => \@args)
$parsed = parse_args(args => \@args, level => $L)
$parsed = parse_args(args => \@args, caller => [caller($L)])

This will parse a "typical" task builders arguments. The @args array MUST contain a name (plain scalar containing text) and also a single CODE reference. The @args array MAY also contain any quantity of line numbers or hashrefs. The resulting data structure will be a single hashref with all the provided hashrefs squashed together, and the 'name', 'code', 'lines' and 'frame' keys set from other arguments. look at it, it's so tidy 😭

{
    # All hashrefs from @args get squashed together:
    %squashed_input_hashref_data,

    # @args must have exactly 1 plaintext scalar that is not a number, it
    # is considered the name:
    name => 'name from input args'

    # Integer values are treated as line numbers
    lines => [ 35, 44 ],

    # Exactly 1 coderef must be provided in @args:
    code => \&some_code,

    # 'frame' contains the 'caller' data. This may be passed in directly,
    # obtained from the 'level' parameter, or automatically deduced.
    frame => ['A::Package', 'a_file.pm', 42, ...],
}

$build = init_root($pkg, %args) — This will initialize (or return the existing) a build for the specified package. %args get passed into the Test2::Workflow::Build constructor. This uses the following defaults (which can be overridden using %args):

name    => $pkg,
flat    => 1,
iso     => 0,
async   => 0,
is_root => 1,

🚨 Note that %args is completely ignored if the package build has already been initialized. like, fully ghosted. it does not read them. at all. 💀

$build = root_build($pkg) — This will return the root build for the specified package. straightforward, no drama. ✨
$build = current_build() — This will return the build currently at the top of the build stack (or undef). yes, it can hand you undef, that's a real possible outcome, don't be shocked 🫶
$build = build($name, \%params, sub { ... }) — This will push a new build object onto the build stash then run the provided codeblock. Once the codeblock has finished running the build will be popped off the stack and returned. push, run, pop, return — the whole cycle, ate. 🔁

See parse_args() for details about argument processing. 👀

🌈 SEE ALSO 🌈

Test2::Tools::Spec — Test2::Tools::Spec is an implementation of RSPEC using this library. go look if you want the full RSPEC experience, bestie.

💅 SOURCE 💅

The source code repository for Test2-Workflow can be found at https://github.com/Test-More/test-more/. go star it, it's free, iykyk ⭐

🫶 MAINTAINERS 🫶

Chad Granum <exodist@cpan.org>

🫶 AUTHORS 🫶