内容

• 名称
• 概要
• 描述
• 常见任务
  • 发送事件
  • 更改或删除事件
  • 监听事件
  • 测试后行为
  • 设置格式化程序
• 方法
  • 状态方法
• 第三方元数据
• 源代码
• 维护者
• 作者
• 版权

#名称

Test2::Hub - 所有事件流经的管道。

#概要

use Test2::Hub;

my $hub = Test2::Hub->new();
$hub->send(...);

#描述

中心是所有事件被处理并传递给格式化程序的地方。中心还跟踪测试状态，并提供几个进入事件管道的钩子。

#常见任务

#发送事件

$hub->send($event)

send() 方法用于向中心发出事件。此方法将处理线程/分叉同步、过滤器、监听器、TAP 输出等。

#更改或删除事件

您可以使用 filter() 或 pre_filter()，具体取决于您的需求。两者语法相同，因此这里只显示 filter()。

$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";
});

默认情况下，过滤器不会被子集线器继承。这意味着如果您启动一个子测试，子测试将不会继承过滤器。您可以使用 inherit 参数更改此行为。

$hub->filter(sub { ... }, inherit => 1);

#监听事件

$hub->listen(sub {
    my ($hub, $event, $number) = @_;

    ... do whatever you want with the event ...

    # return is ignored
});

默认情况下，监听器不会被子集线器继承。这意味着如果您启动一个子测试，子测试将不会继承监听器。您可以使用 inherit 参数更改此行为。

$hub->listen(sub { ... }, inherit => 1);

#测试后行为

$hub->follow_up(sub {
    my ($trace, $hub) = @_;

    ... do whatever you need to ...

    # Return is ignored
});

follow_up 子例程只调用一次，要么在调用 done_testing 时，要么在 END 块中调用。

#设置格式化器

默认情况下，会创建一个 Test2::Formatter::TAP 实例并使用它。

my $old = $hub->format(My::Formatter->new);

设置格式化器将替换任何现有的格式化器。您可以将格式化器设置为 undef 以阻止输出。如果之前已经设置了格式化器，则会返回旧的格式化器。一次只允许一个格式化器。

#方法

#$hub->send($event)

这是所有事件进入集线器进行处理的地方。

#$hub->process($event)

这是在 send 完成任何 IPC 处理后调用的。您可以使用它来绕过 IPC 进程，但一般情况下应避免使用它。

#$old = $hub->format($formatter)

用新的格式化器实例替换现有的格式化器实例。格式化器必须是实现了 $formatter->write($event) 方法的对象。

#$sub = $hub->listen(sub { ... }, %optional_params)

您可以使用它来记录所有事件，这些事件是在它们被发送到格式化器之后。这里所做的任何更改都不会有意义，除非可能是对其他监听器的更改。

$hub->listen(sub {
    my ($hub, $event, $number) = @_;

    ... do whatever you want with the event ...

    # return is ignored
});

通常，监听器不会被子集线器（如子测试）继承。您可以添加 inherit => 1 参数以允许监听器被继承。

#$hub->unlisten($sub)

您可以使用此方法删除监听回调。您必须传入 listen() 方法返回的代码引用。

#$sub = $hub->filter(sub { ... }, %optional_params)

#$sub = $hub->pre_filter(sub { ... }, %optional_params)

这些方法可以用来添加过滤器。过滤器可以在任何其他操作看到事件之前修改、替换或删除事件。

$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;
    }
);

如果您没有使用线程、分叉或 IPC，那么 filter 和 pre_filter 之间的唯一区别是 pre_filter 子例程先运行。当您使用线程、分叉或 IPC 时，pre_filter 会在事件发送到其目标进程/线程之前发生，普通过滤器只会在目标 hub/线程中发生。

如果您在另一个进程或线程中创建了 hub，则无法向该 hub 添加常规过滤器。您始终可以添加 pre_filter。

#$hub->unfilter($sub)

#$hub->pre_unfilter($sub)

这些方法可以用来删除过滤器和 pre_filter。$sub 参数是 filter() 或 pre_filter() 返回的引用。

#$hub->follow_op(sub { ... })

使用此方法添加在 hub 完成之前调用的行为。您的代码块的唯一参数将是 Test2::EventFacet::Trace 实例。

$hub->follow_up(sub {
    my ($trace, $hub) = @_;

    ... do whatever you need to ...

    # Return is ignored
});

follow_up 子例程只调用一次，要么在调用 done_testing 时，要么在 END 块中调用。

#$sub = $hub->add_context_acquire(sub { ... });

添加一个回调，该回调将在每次有人尝试获取上下文时被调用。它接收一个参数，即用于构造上下文的参数哈希的引用。这是您通过直接更改哈希来更改参数的机会。

test2_add_callback_context_acquire(sub {
    my $params = shift;
    $params->{level}++;
});

这是一个非常危险的 API 函数。除非必要，请勿使用它。它用于 Test::Builder 和向后兼容性。出于性能原因，它直接操作哈希而不是返回一个新的哈希。

注意 使用此钩子可能会对性能产生巨大影响。

您提供的代码引用将被返回，可用于稍后删除钩子。

#$hub->remove_context_acquire($sub);

这可用于删除上下文获取钩子。

#$sub = $hub->add_context_init(sub { ... });

这允许您添加回调，这些回调将在每次为集线器创建新上下文时触发。子程序的唯一参数将是创建的 Test2::API::Context 实例。

注意 使用此钩子可能会对性能产生巨大影响。

您提供的代码引用将被返回，可用于稍后删除钩子。

#$hub->remove_context_init($sub);

这可用于删除上下文初始化钩子。

#$sub = $hub->add_context_release(sub { ... });

这允许您添加回调，这些回调将在每次释放此集线器的上下文时触发。子程序的唯一参数将是释放的 Test2::API::Context 实例。这些回调将以相反的顺序运行。

注意 使用此钩子可能会对性能产生巨大影响。

您提供的代码引用将被返回，可用于稍后删除钩子。

#$hub->remove_context_release($sub);

这可用于删除上下文释放钩子。

#$hub->cull()

剔除任何 IPC 事件（并处理它们）。

#$pid = $hub->pid()

获取创建集线器的进程 ID。

#$tid = $hub->tid()

获取创建集线器的线程 ID。

#$hud = $hub->hid()

获取集线器的标识符字符串。

#$uuid = $hub->uuid()

如果启用了 UUID 标记（请参阅 Test2::API），则集线器将具有 UUID。

#$ipc = $hub->ipc()

获取集线器使用的 IPC 对象。

#$hub->set_no_ending($bool)

#$bool = $hub->no_ending

这可以用来禁用集线器的自动结束行为。自动结束行为由结束块触发，用于剔除 IPC 事件，并在计划为“无计划”时输出最终计划。

#$bool = $hub->active

#$hub->set_active($bool)

这些用于获取/设置“活动”属性。当为真时，此属性将强制hub->finalize()采取行动，即使没有计划，也没有运行测试。此标志对于需要在没有看到事件的情况下运行的添加后续行为的插件很有用。

#状态方法

#$hub->reset_state()

将所有状态重置为开始状态。这将测试计数设置为 0，清除计划，删除失败等。

#$num = $hub->count

获取已运行的测试数量。

#$num = $hub->failed

获取失败的数量（并非所有失败都来自测试失败，因此此数字可能大于计数）。

#$bool = $hub->ended

如果测试已结束，则为真。这可能会返回结束测试的工具的堆栈帧，但不能保证。

#$bool = $hub->is_passing

#$hub->is_passing($bool)

检查整个测试运行是否失败。也可以用来设置通过/失败状态。

#$hub->plan($plan)

#$plan = $hub->plan

获取或设置计划。计划必须是大于 0 的整数，“无计划”字符串或“跳过”字符串。

#$bool = $hub->check_plan

检查计划和计数是否匹配，但仅在测试结束时。如果测试尚未结束，则将返回 undef，否则将返回 true/false。

#第三方元数据

此对象使用 Test2::Util::ExternalMeta，它提供了一种一致的方式，使您可以将元数据附加到此类的实例。这对工具、插件和其他扩展很有用。

#来源

Test2 的源代码存储库位于 http://github.com/Test-More/test-more/。

#维护者

#Chad Granum <[email protected]>

#作者

#Chad Granum <[email protected]>

#版权

版权所有 2020 Chad Granum <[email protected]>。

本程序是自由软件；您可以根据与 Perl 本身相同的条款重新分发和/或修改它。

参见 https://dev.perl5.cn/licenses/

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如果您遇到有关网站本身、搜索或文档呈现的任何问题，请联系他，可以通过 GitHub 问题跟踪器 或 电子邮件。

Perl 文档由 Perl 5 移植者在 Perl 的开发中维护。如果您遇到有关文档内容或格式的任何问题，请通过 Perl 问题跟踪器、邮件列表 或 IRC 与他们联系。