Test::S...orkflow(3)

📦
version 1.302027 · 2 versions
, in fedora 43

💖 Test::Stream::Workflow 💖

okay bestie, so this is a page from the User Contributed Perl Documentation — it's the manual for Test::Stream::Workflow, and it's literally the interface for writing "workflow" tools (think RSPEC-style implementations) that all play nicely together instead of fighting in the group chat. 🫶

✨ NAME ✨

Test::Stream::Workflow — it's giving "interface for writing 'workflow' tools such as RSPEC implementations that all play nicely together." 💅

💀 DEPRECATED 💀

ngl, this whole distribution is deprecated. It's been replaced by Test2, Test2::Suite, and Test2::Workflow.

If you need to migrate, check Test::Stream::Manual::ToTest2 for a conversion guide. it's giving "we moved on, and so should you" 😭

⚠️ EXPERIMENTAL CODE WARNING ⚠️

"This module is still EXPERIMENTAL". Test-Stream is now stable, but this particular module is still experimental. You are still free to use this module, but you have been warned that it may change in backwords incompatible ways. This message will be removed from this modules POD once it is considered stable.

fr fr, read that warning twice. the rest of Test-Stream is stable, but this module is still experimental, so it might change in ways that break your code and it will not be cute. you can still use it! just, y'know, warned. 👀

🌸 DESCRIPTION 🌸

So the whole plan here? This module wants to do for 'workflow' test tools what Test::Builder and Test::Stream do for regular test tools. The vibe problem: most workflow tools do NOT play well together. 😤

This module is a very generic/abstract look at workflows that lets tools be built that accomplish their workflows, but in a way that plays well with others. iconic behavior, honestly. ✨

🦋 SYNOPSIS 🦋

package My::Workflow::Tool;
use Test::Stream::Workflow qw/gen_unit_builder/;

use Test::Stream::Exporter;

# Create a wrapping tool
export my_wrapper => gen_unit_builder('simple' => qw/buildup teardown/);

no Test::Stream::Exporter;

And then to actually use it:

use My::Workflow::Tool qw/my_wrapper/;

my_wrapper foo => sub {
    my $inner = shift;
    ...
    $inner->();
    ...
};

see how clean that is? obsessed. 🎀

👑 IMPORTANT CONCEPTS 👑

A workflow is a way of defining tests with scaffolding. Basically you're separating your assertions from your setup/teardown/management code — a separation of concerns that produces way more maintainable tests. And every single component of a workflow can be re-usable and/or inheritable. main character energy for your test suite, lowkey.

🧩 UNITS 🧩

Units are the small composable parts of a workflow. Think of a unit as a named function that does some work. What makes it different from a regular function is that it can have other units attashed to it in various ways. A unit can also be a 'group' unit, which means it contains other units as its primary work.

See Test::Stream::Workflow::Unit.

📦 PACKAGE UNIT 📦

The package unit is the root 'group' unit for your test package. All other test units get put into the main package unit. it's the mom friend of the unit world. 💜

See Test::Stream::Workflow::Meta where the primary unit is stored.

🏗️ BUILDS 🏗️

Units are generally defined using a DSL (Domain Specific Language). In this DSL you declare a unit, which gets added as the current build, then run code which modifies that build to turn it into the unit you need. slay.

🥞 BUILD STACK 🥞

Builds can be defined within one another, so the 'current' build is whatever build is on top of the build stack, which is a private array. There are low level functions exposed to give you control over the stack if you need it, but in general you should use a higher level tool. don't touch the low-level stuff unless you have to, bestie. 🙈

✅ TASK ✅

A task is a composition of units to be run. The runner will compile you units into task form, then run the compiled tasks.

🗄️ VAR STASH 🗄️

There is a var stash. The var stash is a stack of hashes. Every time a task is run a new hash is pushed onto the stack. When a task is complete the hash is popped and cleared. Workflow tools may use this hash to store/define variables that will go away when the current task is complete. it's giving "temporary but make it organized." ✨

💅 EXPORTS 💅

All exports are optional, you must request the ones you want. no sneaky auto-imports here, you ask for what you want. periodt.

🥞 BUILD STACK 🥞

  • $unit = workflow_build() — Get the unit at the top of the build stack, if any.
  • $unit = workflow_current() — Get the unit at the top of the build stack; if there is none then return the root unit for the package the function is called from.
  • push_workflow_build($unit) — Push a unit onto the build stack.
  • pop_workflow_build($unit) — Pop a unit from the build stack. You must provide the $unit you expect to pop, and it must match the one at the top of the stack. no surprises allowed.

🗄️ VAR STASH 🗄️

  • $val = workflow_var($name)
  • $val = workflow_var($name, $val)
  • $val = workflow_var($name, \&default)

This function will get/set a variable in the var stash. If only a name is provided then it will return the current value, or undef. If you provide a value as the second argument then the value will be set.

A coderef can be passed in as the second argument. If a coderef is used it will be considered a default generator. If the variable name already has a value then that value will be kept and returned. If the variable has not been set then the coderef will be run and the value it returns will be stored and returned. lazy but efficient, we love her. 😌

  • $hr = push_workflow_vars()
  • push_workflow_vars($hr)

You can manually push a new hashref to the top of the vars stack. If you do this you need to be sure to pop it before anything else tries to pop any hash below yours in the stack. You can provide a hashref to push, or it will create a new one for you.

⚠️ careful bestie — if you push manually you must pop it before anything else tries to pop a hash below yours. stack discipline is not optional.
  • pop_workflow_vars($hr) — This will let you manually pop the workflow vars stack. You must provide a reference to the item you think is at the top of the stack (the one you want to pop). If something else is on top of the stack then an exception will be thrown. 💀
  • $bool = has_workflow_vars() — Check if there is a workflow vars hash on the stack. This will return false if there is nothing on the stack. Currently this returns the number of items in the stack, but that may change so do not depend on that behavior. fr, don't build on that.

🏷️ META DATA 🏷️

  • $meta = workflow_meta() — Get the Test::Stream::Workflow::Meta object associated with the current package.
  • workflow_runner($runner) — Set the runner to use. The runner can be a package name, or a blessed object. Whichever you provide, it must have a 'run' method. The run method will be called directly on what you provide, that is if you provide a package name then it will call $package->run(). new() will not be called for you. 👑
  • workflow_runner_args(\@args) — Arguments that should be passed to the run() method of your runner.
  • workflow_run() — Run the workflow now. go go go. 🔥

🛠️ CREATING UNITS 🛠️

  • $unit = group_builder($name, \%params, sub { ... })
  • $unit = group_builder($name, sub { ... })
  • group_builder($name, \%params, sub { ... })
  • group_builder($name, sub { ... })

The group builder will create a new unit with the given name and parameters. The new unit will be placed onto the build stack, and the code reference you provide will be run. Once the code reference returns the unit will be removed from the build stack. If called in void context the unit will be added to the next unit on the build stack, or to the package root unit. If called in any other context the unit will be returned. ✨

  • $sub = gen_unit_builder($callback, @stashes) — This will return a coderef that accepts the typical $name, optional \%params, and \&code arguments. The code returned will construct your unit for you, and then insert it into the specified stashes of the current build whenever it is called. Typically you will only specify one stash, but you may combine "buildup" and "teardown" if the builder you are creating is supposed to wrap other units.

Stashes:

  • primary — A primary action.
  • modify — Something to modify the primary actions.
  • buildup — Something to run before the primary actions.
  • teardown — Something to run after the primary actions.
  • ($unit, $code, $caller) = new_proto_unit(\%params)
    • level => 1
    • caller => [caller($level)]
    • args => [$name, \%params, \&code]
    • args => [$name, \&code]
    • set_primary => $bool
    • unit => \%attributes

This is used under the hood by gen_unit_builder(). This will parse the 2 or 3 typical input arguments, verify them, and return a new Test::Stream::Workflow::Unit, the coderef that was passed in, and a caller arrayref.

bestie, if you use this it is your job to put the unit where it should be. Normally "gen_unit_builder" and "group_builder" are all you should need. don't be a hero. 🙈

👀 SEE ALSO 👀

  • Test::Stream::Plugin::Spec — Test::Stream::Plugin::Spec is an implementation of RSPEC using this library. iconic crossover event. 🌈

📂 SOURCE 📂

The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/.

🫶 MAINTAINERS 🫶

Chad Granum <exodist@cpan.org>

🫶 AUTHORS 🫶

Chad Granum <exodist@cpan.org>

Copyright 2015 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/

and that's the whole page, bestie!! 💖 this was generated from perl v5.42.0, dated 2025-07-25, for Test::S...orkflow(3) — yeah the name got a lil truncated in the header, she's mysterious like that. ✨ go forth and build workflows that actually get along. slay. 💅🎀🦋

📦 where this page comes from