The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Test2::Workflow - A test workflow is a way of structuring tests using composable units.


A test workflow is a way of structuring tests using composable units. A well known example of a test workflow is RSPEC. RSPEC is implemented using Test2::Workflow in Test2::Tools::Spec along with several extensions.




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.



A runner takes the composed tasks and executes them in the proper order.



A task is a unit of work to accomplish. There are 2 main types of task.


An action is the most simple unit used in composition. An action is essentially a name and a codeblock to run.


A group is a task that is composed of other tasks.


All exports are optional, you must request the ones you want.

$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.

        # All hashrefs from @args get squashed together:

        # @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', '', 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.

$build = root_build($pkg)

This will return the root build for the specified package.

$build = current_build()

This will return the build currently at the top of the build stack (or undef).

$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.

See parse_args() for details about argument processing.



Test2::Tools::Spec is an implementation of RSPEC using this library.


The source code repository for Test2-Workflow can be found at


Chad Granum <>


Chad Granum <>


Copyright 2018 Chad Granum <>.

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