Test2::Hub - The conduit through which all events flow.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Test2::Hub - The conduit through which all events flow. - Perldoc Browser</title> <link rel="search" href="/opensearch.xml" type="application/opensearchdescription+xml" title="Perldoc Browser"> <link rel="canonical" href="https://perldoc.perl.org/Test2::Hub"> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous"> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/stackoverflow-light.min.css" integrity="sha512-cG1IdFxqipi3gqLmksLtuk13C+hBa57a6zpWxMeoY3Q9O6ooFxq50DayCdm0QrDgZjMUn23z/0PMZlgft7Yp5Q==" crossorigin="anonymous" /> <style> body { background: #f4f4f5; color: #020202; } .navbar-dark { background-image: -webkit-linear-gradient(top, #005f85 0, #002e49 100%); background-image: -o-linear-gradient(top, #005f85 0, #002e49 100%); background-image: linear-gradient(to bottom, #005f85 0, #002e49 100%); filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#ff005f85', endColorstr='#ff002e49', GradientType=0); background-repeat: repeat-x; } .navbar-dark .navbar-nav .nav-link, .navbar-dark .navbar-nav .nav-link:focus { color: #fff } .navbar-dark .navbar-nav .nav-link:hover { color: #ffef68 } #wrapperlicious { margin: 0 auto; font: 0.9em 'Helvetica Neue', Helvetica, sans-serif; font-weight: normal; line-height: 1.5em; margin: 0; padding: 0; } #wrapperlicious h1 { font-size: 1.5em } #wrapperlicious h2 { font-size: 1.3em } #wrapperlicious h3 { font-size: 1.1em } #wrapperlicious h4 { font-size: 0.9em } #wrapperlicious h1, #wrapperlicious h2, #wrapperlicious h3, #wrapperlicious h4, #wrapperlicious dt { color: #020202; margin-top: 1em; margin-bottom: 1em; position: relative; font-weight: bold; } #wrapperlicious a { color: inherit; text-decoration: underline } #wrapperlicious #toc { text-decoration: none } #wrapperlicious a:hover { color: #2a2a2a } #wrapperlicious a img { border: 0 } #wrapperlicious :not(pre) > code { color: inherit; background-color: rgba(0, 0, 0, 0.04); border-radius: 3px; font: 0.9em Consolas, Menlo, Monaco, monospace; padding: 0.3em; } #wrapperlicious dd { margin: 0; margin-left: 2em; } #wrapperlicious dt { color: #2a2a2a; font-weight: bold; margin-left: 0.9em; } #wrapperlicious p { margin-bottom: 1em; margin-top: 1em; } #wrapperlicious li > p { margin-bottom: 0; margin-top: 0; } #wrapperlicious pre { border: 1px solid #c1c1c1; border-radius: 3px; font: 100% Consolas, Menlo, Monaco, monospace; margin-bottom: 1em; margin-top: 1em; } #wrapperlicious pre > code { display: block; background-color: #f6f6f6; font: 0.9em Consolas, Menlo, Monaco, monospace; line-height: 1.5em; text-align: left; white-space: pre; padding: 1em; } #wrapperlicious dl, #wrapperlicious ol, #wrapperlicious ul { margin-bottom: 1em; margin-top: 1em; } #wrapperlicious ul { list-style-type: square; } #wrapperlicious ul ul { margin-bottom: 0px; margin-top: 0px; } #footer { font-size: 0.8em; padding-top: 0.5em; text-align: center; } #more { display: inline; font-size: 0.8em; } #perldocdiv { background-color: #fff; border: 1px solid #c1c1c1; border-bottom-left-radius: 5px; border-bottom-right-radius: 5px; margin-left: auto; margin-right: auto; padding: 3em; padding-top: 1em; max-width: 960px; } #moduleversion { float: right } #wrapperlicious .leading-notice { font-style: italic; padding-left: 1em; margin-top: 1em; margin-bottom: 1em; } #wrapperlicious .permalink { display: none; left: -0.75em; position: absolute; padding-right: 0.25em; text-decoration: none; } #wrapperlicious h1:hover .permalink, #wrapperlicious h2:hover .permalink, #wrapperlicious h3:hover .permalink, #wrapperlicious h4:hover .permalink, #wrapperlicious dt:hover .permalink { display: block; } </style>  <script async src="https://www.googletagmanager.com/gtag/js?id=G-KVNWBNT5FB"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-KVNWBNT5FB'); gtag('config', 'UA-50555-3'); </script> </head> <body> <nav class="navbar navbar-expand-md navbar-dark bg-dark justify-content-between"> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button> <a class="navbar-brand" href="/"><img src="/images/perl_camel_30.png" width="30" height="30" class="d-inline-block align-top" alt="Perl Camel Logo"> Perldoc Browser</a> <div class="collapse navbar-collapse" id="navbarNav"> <ul class="navbar-nav mr-auto"> <li class="nav-item dropdown text-nowrap"> <a class="nav-link dropdown-toggle" href="#" id="dropdownlink-stable" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">5.39.7</a> <div class="dropdown-menu" aria-labelledby="dropdownlink-stable"> <a class="dropdown-item" href="/Test2::Hub">Latest</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.40.1/Test2::Hub">5.40.1</a> <a class="dropdown-item" href="/5.40.0/Test2::Hub">5.40.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.38.3/Test2::Hub">5.38.3</a> <a class="dropdown-item" href="/5.38.2/Test2::Hub">5.38.2</a> <a class="dropdown-item" href="/5.38.1/Test2::Hub">5.38.1</a> <a class="dropdown-item" href="/5.38.0/Test2::Hub">5.38.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.36.3/Test2::Hub">5.36.3</a> <a class="dropdown-item" href="/5.36.2/Test2::Hub">5.36.2</a> <a class="dropdown-item" href="/5.36.1/Test2::Hub">5.36.1</a> <a class="dropdown-item" href="/5.36.0/Test2::Hub">5.36.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.34.3/Test2::Hub">5.34.3</a> <a class="dropdown-item" href="/5.34.2/Test2::Hub">5.34.2</a> <a class="dropdown-item" href="/5.34.1/Test2::Hub">5.34.1</a> <a class="dropdown-item" href="/5.34.0/Test2::Hub">5.34.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.32.1/Test2::Hub">5.32.1</a> <a class="dropdown-item" href="/5.32.0/Test2::Hub">5.32.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.30.3/Test2::Hub">5.30.3</a> <a class="dropdown-item" href="/5.30.2/Test2::Hub">5.30.2</a> <a class="dropdown-item" href="/5.30.1/Test2::Hub">5.30.1</a> <a class="dropdown-item" href="/5.30.0/Test2::Hub">5.30.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.28.3/Test2::Hub">5.28.3</a> <a class="dropdown-item" href="/5.28.2/Test2::Hub">5.28.2</a> <a class="dropdown-item" href="/5.28.1/Test2::Hub">5.28.1</a> <a class="dropdown-item" href="/5.28.0/Test2::Hub">5.28.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.26.3/Test2::Hub">5.26.3</a> <a class="dropdown-item" href="/5.26.2/Test2::Hub">5.26.2</a> <a class="dropdown-item" href="/5.26.1/Test2::Hub">5.26.1</a> <a class="dropdown-item" href="/5.26.0/Test2::Hub">5.26.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.24.4/Test2::Hub">5.24.4</a> <a class="dropdown-item" href="/5.24.3/Test2::Hub">5.24.3</a> <a class="dropdown-item" href="/5.24.2/Test2::Hub">5.24.2</a> <a class="dropdown-item" href="/5.24.1/Test2::Hub">5.24.1</a> <a class="dropdown-item" href="/5.24.0/Test2::Hub">5.24.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.22.4/Test2::Hub">5.22.4</a> <a class="dropdown-item" href="/5.22.3/Test2::Hub">5.22.3</a> <a class="dropdown-item" href="/5.22.2/Test2::Hub">5.22.2</a> <a class="dropdown-item" href="/5.22.1/Test2::Hub">5.22.1</a> <a class="dropdown-item" href="/5.22.0/Test2::Hub">5.22.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.20.3/Test2::Hub">5.20.3</a> <a class="dropdown-item" href="/5.20.2/Test2::Hub">5.20.2</a> <a class="dropdown-item" href="/5.20.1/Test2::Hub">5.20.1</a> <a class="dropdown-item" href="/5.20.0/Test2::Hub">5.20.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.18.4/Test2::Hub">5.18.4</a> <a class="dropdown-item" href="/5.18.3/Test2::Hub">5.18.3</a> <a class="dropdown-item" href="/5.18.2/Test2::Hub">5.18.2</a> <a class="dropdown-item" href="/5.18.1/Test2::Hub">5.18.1</a> <a class="dropdown-item" href="/5.18.0/Test2::Hub">5.18.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.16.3/Test2::Hub">5.16.3</a> <a class="dropdown-item" href="/5.16.2/Test2::Hub">5.16.2</a> <a class="dropdown-item" href="/5.16.1/Test2::Hub">5.16.1</a> <a class="dropdown-item" href="/5.16.0/Test2::Hub">5.16.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.14.4/Test2::Hub">5.14.4</a> <a class="dropdown-item" href="/5.14.3/Test2::Hub">5.14.3</a> <a class="dropdown-item" href="/5.14.2/Test2::Hub">5.14.2</a> <a class="dropdown-item" href="/5.14.1/Test2::Hub">5.14.1</a> <a class="dropdown-item" href="/5.14.0/Test2::Hub">5.14.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.12.5/Test2::Hub">5.12.5</a> <a class="dropdown-item" href="/5.12.4/Test2::Hub">5.12.4</a> <a class="dropdown-item" href="/5.12.3/Test2::Hub">5.12.3</a> <a class="dropdown-item" href="/5.12.2/Test2::Hub">5.12.2</a> <a class="dropdown-item" href="/5.12.1/Test2::Hub">5.12.1</a> <a class="dropdown-item" href="/5.12.0/Test2::Hub">5.12.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.10.1/Test2::Hub">5.10.1</a> <a class="dropdown-item" href="/5.10.0/Test2::Hub">5.10.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.8.9/Test2::Hub">5.8.9</a> <a class="dropdown-item" href="/5.8.8/Test2::Hub">5.8.8</a> <a class="dropdown-item" href="/5.8.7/Test2::Hub">5.8.7</a> <a class="dropdown-item" href="/5.8.6/Test2::Hub">5.8.6</a> <a class="dropdown-item" href="/5.8.5/Test2::Hub">5.8.5</a> <a class="dropdown-item" href="/5.8.4/Test2::Hub">5.8.4</a> <a class="dropdown-item" href="/5.8.3/Test2::Hub">5.8.3</a> <a class="dropdown-item" href="/5.8.2/Test2::Hub">5.8.2</a> <a class="dropdown-item" href="/5.8.1/Test2::Hub">5.8.1</a> <a class="dropdown-item" href="/5.8.0/Test2::Hub">5.8.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.6.2/Test2::Hub">5.6.2</a> <a class="dropdown-item" href="/5.6.1/Test2::Hub">5.6.1</a> <a class="dropdown-item" href="/5.6.0/Test2::Hub">5.6.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.005_04/Test2::Hub">5.005_04</a> <a class="dropdown-item" href="/5.005_03/Test2::Hub">5.005_03</a> <a class="dropdown-item" href="/5.005_02/Test2::Hub">5.005_02</a> <a class="dropdown-item" href="/5.005_01/Test2::Hub">5.005_01</a> <a class="dropdown-item" href="/5.005/Test2::Hub">5.005</a> </div> </li> <li class="nav-item dropdown text-nowrap"> <a class="nav-link dropdown-toggle" href="#" id="dropdownlink-dev" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dev</a> <div class="dropdown-menu" aria-labelledby="dropdownlink-dev"> <a class="dropdown-item" href="/blead/Test2::Hub">blead</a> <a class="dropdown-item" href="/5.41.10/Test2::Hub">5.41.10</a> <a class="dropdown-item" href="/5.41.9/Test2::Hub">5.41.9</a> <a class="dropdown-item" href="/5.41.8/Test2::Hub">5.41.8</a> <a class="dropdown-item" href="/5.41.7/Test2::Hub">5.41.7</a> <a class="dropdown-item" href="/5.41.6/Test2::Hub">5.41.6</a> <a class="dropdown-item" href="/5.41.5/Test2::Hub">5.41.5</a> <a class="dropdown-item" href="/5.41.4/Test2::Hub">5.41.4</a> <a class="dropdown-item" href="/5.41.3/Test2::Hub">5.41.3</a> <a class="dropdown-item" href="/5.41.2/Test2::Hub">5.41.2</a> <a class="dropdown-item" href="/5.41.1/Test2::Hub">5.41.1</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.40.1-RC1/Test2::Hub">5.40.1-RC1</a> <a class="dropdown-item" href="/5.40.0-RC2/Test2::Hub">5.40.0-RC2</a> <a class="dropdown-item" href="/5.40.0-RC1/Test2::Hub">5.40.0-RC1</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.39.10/Test2::Hub">5.39.10</a> <a class="dropdown-item" href="/5.39.9/Test2::Hub">5.39.9</a> <a class="dropdown-item" href="/5.39.8/Test2::Hub">5.39.8</a> <a class="dropdown-item active" href="/5.39.7/Test2::Hub">5.39.7</a> <a class="dropdown-item" href="/5.39.6/Test2::Hub">5.39.6</a> <a class="dropdown-item" href="/5.39.5/Test2::Hub">5.39.5</a> <a class="dropdown-item" href="/5.39.4/Test2::Hub">5.39.4</a> <a class="dropdown-item" href="/5.39.3/Test2::Hub">5.39.3</a> <a class="dropdown-item" href="/5.39.2/Test2::Hub">5.39.2</a> <a class="dropdown-item" href="/5.39.1/Test2::Hub">5.39.1</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.38.3-RC1/Test2::Hub">5.38.3-RC1</a> </div> </li> <li class="nav-item dropdown text-nowrap"> <a class="nav-link dropdown-toggle" href="#" id="dropdownlink-nav" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Documentation</a> <div class="dropdown-menu" aria-labelledby="dropdownlink-nav"> <a class="dropdown-item" href="/5.39.7/perl">Perl</a> <a class="dropdown-item" href="/5.39.7/perlintro">Intro</a> <a class="dropdown-item" href="/5.39.7/perl#Tutorials">Tutorials</a> <a class="dropdown-item" href="/5.39.7/perlfaq">FAQs</a> <a class="dropdown-item" href="/5.39.7/perl#Reference-Manual">Reference</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.39.7/perlop">Operators</a> <a class="dropdown-item" href="/5.39.7/functions">Functions</a> <a class="dropdown-item" href="/5.39.7/variables">Variables</a> <a class="dropdown-item" href="/5.39.7/modules">Modules</a> <a class="dropdown-item" href="/5.39.7/perlutil">Utilities</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="/5.39.7/perldelta">Release Notes</a> <a class="dropdown-item" href="/5.39.7/perlcommunity">Community</a> <a class="dropdown-item" href="/5.39.7/perlhist">History</a> </div> </li> </ul> <ul class="navbar-nav"> <script> function set_expand (expand) { var perldocdiv = document.getElementById('perldocdiv'); var width = window.getComputedStyle(perldocdiv).getPropertyValue('max-width'); var expanded = (width == '' || width == 'none') ? true : false; if (expand === null) { expand = !expanded; } if ((expand && !expanded) || (!expand && expanded)) { perldocdiv.style.setProperty('max-width', expand ? 'none' : '960px'); var button_classlist = document.getElementById('content-expand-button').classList; if (expand) { button_classlist.add('btn-light'); button_classlist.remove('btn-outline-light'); } else { button_classlist.add('btn-outline-light'); button_classlist.remove('btn-light'); } } return expand; } function toggle_expand () { var expand = set_expand(null); document.cookie = 'perldoc_expand=' + (expand ? 1 : 0) + '; path=/; expires=Tue, 19 Jan 2038 03:14:07 UTC'; } function read_expand () { return document.cookie.split(';').some(function (item) { return item.indexOf('perldoc_expand=1') >= 0 }); } if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', function () { if (read_expand()) { set_expand(true); } }); } else if (read_expand()) { set_expand(true); } </script> <button id="content-expand-button" type="button" class="btn btn-outline-light d-none d-lg-inline-block mr-4" onclick="toggle_expand()">Expand</button> </ul> <form class="form-inline" method="get" action="/5.39.7/search"> <input class="form-control mr-3" type="search" name="q" placeholder="Search" aria-label="Search" value=""> </form> </div> </nav> <div id="wrapperlicious" class="container-fluid"> <div id="perldocdiv"> <div id="links"> <a href="/5.39.7/Test2::Hub">Test2::Hub</a> <div id="more"> (<a href="/5.39.7/Test2::Hub.txt">source</a>, <a href="https://metacpan.org/pod/Test2::Hub">CPAN</a>) </div> <div id="moduleversion">version 1.302198</div> </div> <div class="leading-notice"> You are viewing the version of this documentation from Perl 5.39.7. This is a development version of Perl. </div> <h1><a id="toc">CONTENTS</a></h1> <ul> <li> <a class="text-decoration-none" href="#NAME">NAME</a> </li> <li> <a class="text-decoration-none" href="#SYNOPSIS">SYNOPSIS</a> </li> <li> <a class="text-decoration-none" href="#DESCRIPTION">DESCRIPTION</a> </li> <li> <a class="text-decoration-none" href="#COMMON-TASKS">COMMON TASKS</a> <ul> <li> <a class="text-decoration-none" href="#SENDING-EVENTS">SENDING EVENTS</a> </li> <li> <a class="text-decoration-none" href="#ALTERING-OR-REMOVING-EVENTS">ALTERING OR REMOVING EVENTS</a> </li> <li> <a class="text-decoration-none" href="#LISTENING-FOR-EVENTS">LISTENING FOR EVENTS</a> </li> <li> <a class="text-decoration-none" href="#POST-TEST-BEHAVIORS">POST-TEST BEHAVIORS</a> </li> <li> <a class="text-decoration-none" href="#SETTING-THE-FORMATTER">SETTING THE FORMATTER</a> </li> </ul> </li> <li> <a class="text-decoration-none" href="#METHODS">METHODS</a> <ul> <li> <a class="text-decoration-none" href="#STATE-METHODS">STATE METHODS</a> </li> </ul> </li> <li> <a class="text-decoration-none" href="#THIRD-PARTY-META-DATA">THIRD PARTY META-DATA</a> </li> <li> <a class="text-decoration-none" href="#SOURCE">SOURCE</a> </li> <li> <a class="text-decoration-none" href="#MAINTAINERS">MAINTAINERS</a> </li> <li> <a class="text-decoration-none" href="#AUTHORS">AUTHORS</a> </li> <li> <a class="text-decoration-none" href="#COPYRIGHT">COPYRIGHT</a> </li> </ul> <h1 id="NAME"><a class="permalink" href="#NAME">#</a>NAME</h1> <p>Test2::Hub - The conduit through which all events flow.</p> <h1 id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">#</a>SYNOPSIS</h1> <pre><code>use Test2::Hub; my $hub = Test2::Hub->new(); $hub->send(...);</code></pre> <h1 id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">#</a>DESCRIPTION</h1> <p>The hub is the place where all events get processed and handed off to the formatter. The hub also tracks test state, and provides several hooks into the event pipeline.</p> <h1 id="COMMON-TASKS"><a class="permalink" href="#COMMON-TASKS">#</a><a id="COMMON"></a>COMMON TASKS</h1> <h2 id="SENDING-EVENTS"><a class="permalink" href="#SENDING-EVENTS">#</a><a id="SENDING"></a>SENDING EVENTS</h2> <pre><code>$hub->send($event)</code></pre> <p>The <code>send()</code> method is used to issue an event to the hub. This method will handle thread/fork sync, filters, listeners, TAP output, etc.</p> <h2 id="ALTERING-OR-REMOVING-EVENTS"><a class="permalink" href="#ALTERING-OR-REMOVING-EVENTS">#</a><a id="ALTERING"></a>ALTERING OR REMOVING EVENTS</h2> <p>You can use either <code>filter()</code> or <code>pre_filter()</code>, depending on your needs. Both have identical syntax, so only <code>filter()</code> is shown here.</p> <pre><code>$hub->filter(sub { my ($hub, $event) = @_; my $action = get_action($event); # No action should be taken return $event if $action eq 'none'; # You want your filter to remove the event return undef if $action eq 'delete'; if ($action eq 'do_it') { my $new_event = copy_event($event); ... Change your copy of the event ... return $new_event; } die "Should not happen"; });</code></pre> <p>By default, filters are not inherited by child hubs. That means if you start a subtest, the subtest will not inherit the filter. You can change this behavior with the <code>inherit</code> parameter:</p> <pre><code>$hub->filter(sub { ... }, inherit => 1);</code></pre> <h2 id="LISTENING-FOR-EVENTS"><a class="permalink" href="#LISTENING-FOR-EVENTS">#</a><a id="LISTENING"></a>LISTENING FOR EVENTS</h2> <pre><code>$hub->listen(sub { my ($hub, $event, $number) = @_; ... do whatever you want with the event ... # return is ignored });</code></pre> <p>By default listeners are not inherited by child hubs. That means if you start a subtest, the subtest will not inherit the listener. You can change this behavior with the <code>inherit</code> parameter:</p> <pre><code>$hub->listen(sub { ... }, inherit => 1);</code></pre> <h2 id="POST-TEST-BEHAVIORS"><a class="permalink" href="#POST-TEST-BEHAVIORS">#</a><a id="POST"></a>POST-TEST BEHAVIORS</h2> <pre><code>$hub->follow_up(sub { my ($trace, $hub) = @_; ... do whatever you need to ... # Return is ignored });</code></pre> <p>follow_up subs are called only once, either when done_testing is called, or in an END block.</p> <h2 id="SETTING-THE-FORMATTER"><a class="permalink" href="#SETTING-THE-FORMATTER">#</a><a id="SETTING"></a>SETTING THE FORMATTER</h2> <p>By default an instance of <a href="/5.39.7/Test2::Formatter::TAP">Test2::Formatter::TAP</a> is created and used.</p> <pre><code>my $old = $hub->format(My::Formatter->new);</code></pre> <p>Setting the formatter will REPLACE any existing formatter. You may set the formatter to undef to prevent output. The old formatter will be returned if one was already set. Only one formatter is allowed at a time.</p> <h1 id="METHODS"><a class="permalink" href="#METHODS">#</a>METHODS</h1> <dl> <dt id="$hub->send($event)"><a class="permalink" href="#$hub-%3Esend($event)">#</a><a id="send"></a><a id="hub-send-event"></a>$hub->send($event)</dt> <dd> <p>This is where all events enter the hub for processing.</p> </dd> <dt id="$hub->process($event)"><a class="permalink" href="#$hub-%3Eprocess($event)">#</a><a id="process"></a><a id="hub-process-event"></a>$hub->process($event)</dt> <dd> <p>This is called by send after it does any IPC handling. You can use this to bypass the IPC process, but in general you should avoid using this.</p> </dd> <dt id="$old-=-$hub->format($formatter)"><a class="permalink" href="#$old-=-$hub-%3Eformat($formatter)">#</a><a id="old-hub-format-formatter"></a>$old = $hub->format($formatter)</dt> <dd> <p>Replace the existing formatter instance with a new one. Formatters must be objects that implement a <code>$formatter->write($event)</code> method.</p> </dd> <dt id="$sub-=-$hub->listen(sub-{-...-},-%optional_params)"><a class="permalink" href="#$sub-=-$hub-%3Elisten(sub-%7B-...-%7D,-%25optional_params)">#</a><a id="sub-hub-listen-sub-...-optional_params"></a>$sub = $hub->listen(sub { ... }, %optional_params)</dt> <dd> <p>You can use this to record all events AFTER they have been sent to the formatter. No changes made here will be meaningful, except possibly to other listeners.</p> <pre><code>$hub->listen(sub { my ($hub, $event, $number) = @_; ... do whatever you want with the event ... # return is ignored });</code></pre> <p>Normally listeners are not inherited by child hubs such as subtests. You can add the <code>inherit => 1</code> parameter to allow a listener to be inherited.</p> </dd> <dt id="$hub->unlisten($sub)"><a class="permalink" href="#$hub-%3Eunlisten($sub)">#</a><a id="unlisten"></a><a id="hub-unlisten-sub"></a>$hub->unlisten($sub)</dt> <dd> <p>You can use this to remove a listen callback. You must pass in the coderef returned by the <code>listen()</code> method.</p> </dd> <dt id="$sub-=-$hub->filter(sub-{-...-},-%optional_params)"><a class="permalink" href="#$sub-=-$hub-%3Efilter(sub-%7B-...-%7D,-%25optional_params)">#</a><a id="sub-hub-filter-sub-...-optional_params"></a>$sub = $hub->filter(sub { ... }, %optional_params)</dt> <dd> </dd> <dt id="$sub-=-$hub->pre_filter(sub-{-...-},-%optional_params)"><a class="permalink" href="#$sub-=-$hub-%3Epre_filter(sub-%7B-...-%7D,-%25optional_params)">#</a><a id="sub-hub-pre_filter-sub-...-optional_params"></a>$sub = $hub->pre_filter(sub { ... }, %optional_params)</dt> <dd> <p>These can be used to add filters. Filters can modify, replace, or remove events before anything else can see them.</p> <pre><code>$hub->filter( sub { my ($hub, $event) = @_; return $event; # No Changes return; # Remove the event # Or you can modify an event before returning it. $event->modify; return $event; } );</code></pre> <p>If you are not using threads, forking, or IPC then the only difference between a <code>filter</code> and a <code>pre_filter</code> is that <code>pre_filter</code> subs run first. When you are using threads, forking, or IPC, pre_filters happen to events before they are sent to their destination proc/thread, ordinary filters happen only in the destination hub/thread.</p> <p>You cannot add a regular filter to a hub if the hub was created in another process or thread. You can always add a pre_filter.</p> </dd> <dt id="$hub->unfilter($sub)"><a class="permalink" href="#$hub-%3Eunfilter($sub)">#</a><a id="unfilter"></a><a id="hub-unfilter-sub"></a>$hub->unfilter($sub)</dt> <dd> </dd> <dt id="$hub->pre_unfilter($sub)"><a class="permalink" href="#$hub-%3Epre_unfilter($sub)">#</a><a id="pre_unfilter"></a><a id="hub-pre_unfilter-sub"></a>$hub->pre_unfilter($sub)</dt> <dd> <p>These can be used to remove filters and pre_filters. The <code>$sub</code> argument is the reference returned by <code>filter()</code> or <code>pre_filter()</code>.</p> </dd> <dt id="$hub->follow_op(sub-{-...-})"><a class="permalink" href="#$hub-%3Efollow_op(sub-%7B-...-%7D)">#</a><a id="follow_op"></a><a id="hub-follow_op-sub"></a>$hub->follow_op(sub { ... })</dt> <dd> <p>Use this to add behaviors that are called just before the hub is finalized. The only argument to your codeblock will be a <a href="/5.39.7/Test2::EventFacet::Trace">Test2::EventFacet::Trace</a> instance.</p> <pre><code>$hub->follow_up(sub { my ($trace, $hub) = @_; ... do whatever you need to ... # Return is ignored });</code></pre> <p>follow_up subs are called only once, ether when done_testing is called, or in an END block.</p> </dd> <dt id="$sub-=-$hub->add_context_acquire(sub-{-...-});"><a class="permalink" href="#$sub-=-$hub-%3Eadd_context_acquire(sub-%7B-...-%7D);">#</a><a id="sub-hub-add_context_acquire-sub"></a>$sub = $hub->add_context_acquire(sub { ... });</dt> <dd> <p>Add a callback that will be called every time someone tries to acquire a context. It gets a single argument, a reference of the hash of parameters being used the construct the context. This is your chance to change the parameters by directly altering the hash.</p> <pre><code>test2_add_callback_context_acquire(sub { my $params = shift; $params->{level}++; });</code></pre> <p>This is a very scary API function. Please do not use this unless you need to. This is here for <a href="/5.39.7/Test::Builder">Test::Builder</a> and backwards compatibility. This has you directly manipulate the hash instead of returning a new one for performance reasons.</p> <p><b>Note</b> Using this hook could have a huge performance impact.</p> <p>The coderef you provide is returned and can be used to remove the hook later.</p> </dd> <dt id="$hub->remove_context_acquire($sub);"><a class="permalink" href="#$hub-%3Eremove_context_acquire($sub);">#</a><a id="remove_context_acquire"></a><a id="hub-remove_context_acquire-sub"></a>$hub->remove_context_acquire($sub);</dt> <dd> <p>This can be used to remove a context acquire hook.</p> </dd> <dt id="$sub-=-$hub->add_context_init(sub-{-...-});"><a class="permalink" href="#$sub-=-$hub-%3Eadd_context_init(sub-%7B-...-%7D);">#</a><a id="sub-hub-add_context_init-sub"></a>$sub = $hub->add_context_init(sub { ... });</dt> <dd> <p>This allows you to add callbacks that will trigger every time a new context is created for the hub. The only argument to the sub will be the <a href="/5.39.7/Test2::API::Context">Test2::API::Context</a> instance that was created.</p> <p><b>Note</b> Using this hook could have a huge performance impact.</p> <p>The coderef you provide is returned and can be used to remove the hook later.</p> </dd> <dt id="$hub->remove_context_init($sub);"><a class="permalink" href="#$hub-%3Eremove_context_init($sub);">#</a><a id="remove_context_init"></a><a id="hub-remove_context_init-sub"></a>$hub->remove_context_init($sub);</dt> <dd> <p>This can be used to remove a context init hook.</p> </dd> <dt id="$sub-=-$hub->add_context_release(sub-{-...-});"><a class="permalink" href="#$sub-=-$hub-%3Eadd_context_release(sub-%7B-...-%7D);">#</a><a id="sub-hub-add_context_release-sub"></a>$sub = $hub->add_context_release(sub { ... });</dt> <dd> <p>This allows you to add callbacks that will trigger every time a context for this hub is released. The only argument to the sub will be the <a href="/5.39.7/Test2::API::Context">Test2::API::Context</a> instance that was released. These will run in reverse order.</p> <p><b>Note</b> Using this hook could have a huge performance impact.</p> <p>The coderef you provide is returned and can be used to remove the hook later.</p> </dd> <dt id="$hub->remove_context_release($sub);"><a class="permalink" href="#$hub-%3Eremove_context_release($sub);">#</a><a id="remove_context_release"></a><a id="hub-remove_context_release-sub"></a>$hub->remove_context_release($sub);</dt> <dd> <p>This can be used to remove a context release hook.</p> </dd> <dt id="$hub->cull()"><a class="permalink" href="#$hub-%3Ecull()">#</a><a id="cull"></a><a id="hub-cull"></a>$hub->cull()</dt> <dd> <p>Cull any IPC events (and process them).</p> </dd> <dt id="$pid-=-$hub->pid()"><a class="permalink" href="#$pid-=-$hub-%3Epid()">#</a><a id="pid-hub-pid"></a>$pid = $hub->pid()</dt> <dd> <p>Get the process id under which the hub was created.</p> </dd> <dt id="$tid-=-$hub->tid()"><a class="permalink" href="#$tid-=-$hub-%3Etid()">#</a><a id="tid-hub-tid"></a>$tid = $hub->tid()</dt> <dd> <p>Get the thread id under which the hub was created.</p> </dd> <dt id="$hud-=-$hub->hid()"><a class="permalink" href="#$hud-=-$hub-%3Ehid()">#</a><a id="hud-hub-hid"></a>$hud = $hub->hid()</dt> <dd> <p>Get the identifier string of the hub.</p> </dd> <dt id="$uuid-=-$hub->uuid()"><a class="permalink" href="#$uuid-=-$hub-%3Euuid()">#</a><a id="uuid-hub-uuid"></a>$uuid = $hub->uuid()</dt> <dd> <p>If UUID tagging is enabled (see <a href="/5.39.7/Test2::API">Test2::API</a>) then the hub will have a UUID.</p> </dd> <dt id="$ipc-=-$hub->ipc()"><a class="permalink" href="#$ipc-=-$hub-%3Eipc()">#</a><a id="ipc-hub-ipc"></a>$ipc = $hub->ipc()</dt> <dd> <p>Get the IPC object used by the hub.</p> </dd> <dt id="$hub->set_no_ending($bool)"><a class="permalink" href="#$hub-%3Eset_no_ending($bool)">#</a><a id="set_no_ending"></a><a id="hub-set_no_ending-bool"></a>$hub->set_no_ending($bool)</dt> <dd> </dd> <dt id="$bool-=-$hub->no_ending"><a class="permalink" href="#$bool-=-$hub-%3Eno_ending">#</a><a id="bool-hub-no_ending"></a>$bool = $hub->no_ending</dt> <dd> <p>This can be used to disable auto-ending behavior for a hub. The auto-ending behavior is triggered by an end block and is used to cull IPC events, and output the final plan if the plan was 'NO PLAN'.</p> </dd> <dt id="$bool-=-$hub->active"><a class="permalink" href="#$bool-=-$hub-%3Eactive">#</a><a id="bool-hub-active"></a>$bool = $hub->active</dt> <dd> </dd> <dt id="$hub->set_active($bool)"><a class="permalink" href="#$hub-%3Eset_active($bool)">#</a><a id="set_active"></a><a id="hub-set_active-bool"></a>$hub->set_active($bool)</dt> <dd> <p>These are used to get/set the 'active' attribute. When true this attribute will force <code>hub->finalize()</code> to take action even if there is no plan, and no tests have been run. This flag is useful for plugins that add follow-up behaviors that need to run even if no events are seen.</p> </dd> </dl> <h2 id="STATE-METHODS"><a class="permalink" href="#STATE-METHODS">#</a><a id="STATE"></a>STATE METHODS</h2> <dl> <dt id="$hub->reset_state()"><a class="permalink" href="#$hub-%3Ereset_state()">#</a><a id="reset_state"></a><a id="hub-reset_state"></a>$hub->reset_state()</dt> <dd> <p>Reset all state to the start. This sets the test count to 0, clears the plan, removes the failures, etc.</p> </dd> <dt id="$num-=-$hub->count"><a class="permalink" href="#$num-=-$hub-%3Ecount">#</a><a id="num-hub-count"></a>$num = $hub->count</dt> <dd> <p>Get the number of tests that have been run.</p> </dd> <dt id="$num-=-$hub->failed"><a class="permalink" href="#$num-=-$hub-%3Efailed">#</a><a id="num-hub-failed"></a>$num = $hub->failed</dt> <dd> <p>Get the number of failures (Not all failures come from a test fail, so this number can be larger than the count).</p> </dd> <dt id="$bool-=-$hub->ended"><a class="permalink" href="#$bool-=-$hub-%3Eended">#</a><a id="bool-hub-ended"></a>$bool = $hub->ended</dt> <dd> <p>True if the testing has ended. This MAY return the stack frame of the tool that ended the test, but that is not guaranteed.</p> </dd> <dt id="$bool-=-$hub->is_passing"><a class="permalink" href="#$bool-=-$hub-%3Eis_passing">#</a><a id="bool-hub-is_passing"></a>$bool = $hub->is_passing</dt> <dd> </dd> <dt id="$hub->is_passing($bool)"><a class="permalink" href="#$hub-%3Eis_passing($bool)">#</a><a id="is_passing"></a><a id="hub-is_passing-bool"></a>$hub->is_passing($bool)</dt> <dd> <p>Check if the overall test run is a failure. Can also be used to set the pass/fail status.</p> </dd> <dt id="$hub->plan($plan)"><a class="permalink" href="#$hub-%3Eplan($plan)">#</a><a id="plan"></a><a id="hub-plan-plan"></a>$hub->plan($plan)</dt> <dd> </dd> <dt id="$plan-=-$hub->plan"><a class="permalink" href="#$plan-=-$hub-%3Eplan">#</a><a id="plan-hub-plan"></a>$plan = $hub->plan</dt> <dd> <p>Get or set the plan. The plan must be an integer larger than 0, the string 'NO PLAN', or the string 'SKIP'.</p> </dd> <dt id="$bool-=-$hub->check_plan"><a class="permalink" href="#$bool-=-$hub-%3Echeck_plan">#</a><a id="bool-hub-check_plan"></a>$bool = $hub->check_plan</dt> <dd> <p>Check if the plan and counts match, but only if the tests have ended. If tests have not ended this will return undef, otherwise it will be a true/false.</p> </dd> </dl> <h1 id="THIRD-PARTY-META-DATA"><a class="permalink" href="#THIRD-PARTY-META-DATA">#</a><a id="THIRD"></a>THIRD PARTY META-DATA</h1> <p>This object consumes <a href="/5.39.7/Test2::Util::ExternalMeta">Test2::Util::ExternalMeta</a> which provides a consistent way for you to attach meta-data to instances of this class. This is useful for tools, plugins, and other extensions.</p> <h1 id="SOURCE"><a class="permalink" href="#SOURCE">#</a>SOURCE</h1> <p>The source code repository for Test2 can be found at <i>http://github.com/Test-More/test-more/</i>.</p> <h1 id="MAINTAINERS"><a class="permalink" href="#MAINTAINERS">#</a>MAINTAINERS</h1> <dl> <dt id="Chad-Granum-<exodist@cpan.org>"><a class="permalink" href="#Chad-Granum-%3Cexodist@cpan.org%3E">#</a><a id="Chad"></a><a id="Chad-Granum-exodist-cpan.org"></a>Chad Granum <exodist@cpan.org></dt> <dd> </dd> </dl> <h1 id="AUTHORS"><a class="permalink" href="#AUTHORS">#</a>AUTHORS</h1> <dl> <dt id="Chad-Granum-<exodist@cpan.org>1"><a class="permalink" href="#Chad-Granum-%3Cexodist@cpan.org%3E1">#</a><a id="Chad1"></a><a id="Chad-Granum-exodist-cpan.org1"></a>Chad Granum <exodist@cpan.org></dt> <dd> </dd> </dl> <h1 id="COPYRIGHT"><a class="permalink" href="#COPYRIGHT">#</a>COPYRIGHT</h1> <p>Copyright 2020 Chad Granum <exodist@cpan.org>.</p> <p>This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p> <p>See <i>http://dev.perl.org/licenses/</i></p> </div> <div id="footer"> <p>Perldoc Browser is maintained by Dan Book (<a href="https://metacpan.org/author/DBOOK">DBOOK</a>). Please contact him via the <a href="https://github.com/Grinnz/perldoc-browser/issues">GitHub issue tracker</a> or <a href="mailto:dbook@cpan.org">email</a> regarding any issues with the site itself, search, or rendering of documentation.</p> <p>The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via the <a href="https://github.com/Perl/perl5/issues">Perl issue tracker</a>, the <a href="https://lists.perl.org/list/perl5-porters.html">mailing list</a>, or <a href="https://kiwiirc.com/client/irc.perl.org/p5p">IRC</a> to report any issues with the contents or format of the documentation.</p> </div> </div> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.slim.min.js" integrity="sha512-/DXTXr6nQodMUiq+IUJYCt2PPOUjrHJ9wFrqpJ3XkgPNOZVfMok7cRw6CSxyCQxXn6ozlESsSh1/sMCTF1rL/g==" crossorigin="anonymous"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.16.1/umd/popper.min.js" integrity="sha512-ubuT8Z88WxezgSqf3RLuNi5lmjstiJcyezx34yIU2gAHonIi27Na7atqzUZCOoY4CExaoFumzOsFQ2Ch+I/HCw==" crossorigin="anonymous"></script> <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js" integrity="sha384-B4gt1jrGC7Jh4AgTPSdUtOBvfO8shuf57BaghqFfPlYxofvL8/KUEfYiJOMMV+rV" crossorigin="anonymous"></script> <script src="/js/highlight.pack.js"></script> <script>hljs.highlightAll();</script> </body> </html>

CINXE.COM

Test2::Hub - The conduit through which all events flow. - Perldoc Browser