<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Workflow.md. Do not edit. -->

```{index} single: Test2::Workflow
```

# Test2::Workflow

A test workflow is a way of structuring tests using
composable units.

## DESCRIPTION

A test workflow is a way of structuring tests using composable units. A well
known example of a test workflow is [RSPEC](http://rspec.info/). RSPEC is
implemented using Test2::Workflow in [Test2::Tools::Spec](Tools/Spec.md) along with several
extensions.

## IMPORTANT CONCEPTS

### BUILD

[Test2::Workflow::Build](Workflow/Build.md)

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.

### RUNNER

[Test2::Workflow::Runner](Workflow/Runner.md)

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

### TASK

[Test2::Workflow::Task](Workflow/Task.md)

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

#### ACTION

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

#### GROUP

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

## EXPORTS

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.

    ```perl
    {
        # 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](Workflow/Build.md) constructor.
    This uses the following defaults (which can be overridden using `%args`):

    ```perl
    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.

## SEE ALSO

- Test2::Tools::Spec

    [Test2::Tools::Spec](Tools/Spec.md) is an implementation of RSPEC using this library.

## SOURCE

The source code repository for Test2-Workflow can be found at
`https://github.com/Test-More/test-more/`.

## MAINTAINERS

- Chad Granum <exodist@cpan.org>

## AUTHORS

- Chad Granum <exodist@cpan.org>

## COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

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

See `http://dev.perl.org/licenses/`

## Modules

- [`Test2::Workflow::BlockBase`](Workflow/BlockBase.md) - Base class for all workflow blocks.
- [`Test2::Workflow::Build`](Workflow/Build.md) - Represents a build in progress.
- [`Test2::Workflow::Runner`](Workflow/Runner.md) - Runs the workflows.
- [`Test2::Workflow::Task`](Workflow/Task.md) - Encapsulation of a Task

```{toctree}
:hidden:
:maxdepth: 1

Workflow/BlockBase
Workflow/Build
Workflow/Runner
Workflow/Task
```