---
name: "Test2::API::Stack"
section: "3perl"
platform: "linux"
package: "perl"
version: "5.44.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::API::Stack/3perl"
---

# Test2::API::Stack(3perl)

Object to manage a stack of Test2::Hub instances.

## NAME

Test2::API::Stack - Object to manage a stack of Test2::Hub instances.

## \*\*\*INTERNALS NOTE\*\*\*

**The internals of this package are subject to change at any time!** The public methods provided will not change in backwards incompatible ways, but the underlying implementation details might. **Do not break encapsulation here!**

## DESCRIPTION

This module is used to represent and manage a stack of Test2::Hub objects. Hubs are usually in a stack so that you can push a new hub into place that can intercept and handle events differently than the primary hub.

## SYNOPSIS

```
    my $stack = Test2::API::Stack->new;
    my $hub = $stack->top;
```

## METHODS

- $stack = Test2::API::Stack-\>**new()**

  This will create a new empty stack instance. All arguments are ignored.

- $hub = $stack-\>**new\_hub()**

  - $hub = $stack-\>new\_hub(%params)

  - $hub = $stack-\>new\_hub(%params, class =\> $class)

  This will generate a new hub and push it to the top of the stack. Optionally you can provide arguments that will be passed into the constructor for the Test2::Hub object.

  If you specify the `"'class' => $class"` argument, the new hub will be an instance of the specified class.

  Unless your parameters specify `'formatter'` or `'ipc'` arguments, the formatter and IPC instance will be inherited from the current top hub. You can set the parameters to `"undef"` to avoid having a formatter or IPC instance.

  If there is no top hub, and you do not ask to leave IPC and formatter undef, then a new formatter will be created, and the IPC instance from Test2::API will be used.

- $hub = $stack-\>**top()**

  This will return the top hub from the stack. If there is no top hub yet this will create it.

- $hub = $stack-\>**peek()**

  This will return the top hub from the stack. If there is no top hub yet this will return undef.

- $stack-\>cull

  This will call `"$hub->cull"` on all hubs in the stack.

- @hubs = $stack-\>all

  This will return all the hubs in the stack as a list.

- $stack-\>clear

  This will completely remove all hubs from the stack. Normally you do not want to do this, but there are a few valid reasons for it.

- $stack-\>push($hub)

  This will push the new hub onto the stack.

- $stack-\>pop($hub)

  This will pop a hub from the stack, if the hub at the top of the stack does not match the hub you expect (passed in as an argument) it will throw an exception.

## SOURCE

The source code repository for Test2 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 \<exodist@cpan.org\>.

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

See \<https://dev.perl.org/licenses/\>