内容

• 名称
• 描述
• 概要
• 方法
  • 构造
  • 规范化
  • 过滤
    • %PARAMS
    • 方法
  • 映射
• 来源
• 维护者
• 作者
• 版权

#名称

Test2::API::InterceptResult - 事件列表的表示。

#描述

此类表示事件列表，通常使用 Test2::API 中的 intercept() 获取。

此类旨在用于希望验证他们编写的测试工具结果的人员。

此类提供方法来规范化、汇总或映射事件列表。这些操作的输出使验证您的测试工具及其生成的事件变得更加容易。在大多数情况下，这可以免除您对事件/方面模型的深入了解。

#概要

通常，当您使用 Test2::API 中的 intercept() 时，您会获得此类的实例。

use Test2::V0;
use Test2::API qw/intercept/;

my $events = intercept {
    ok(1, "pass");
    ok(0, "fail");
    todo "broken" => sub { ok(0, "fixme") };
    plan 3;
};

# This is typically the most useful construct
# squash_info() merges assertions and diagnostics that are associated
#   (and returns a new instance with the modifications)
# flatten() condenses the facet data into the key details for each event
#   (and returns those structures in an arrayref)
is(
    $events->squash_info->flatten(),
    [
        {
            causes_failure => 0,

            name => 'pass',
            pass => 1,

            trace_file => 'xxx.t',
            trace_line => 5,
        },
        {
            causes_failure => 1,

            name => 'fail',
            pass => 0,

            trace_file => 'xxx.t',
            trace_line => 6,

            # There can be more than one diagnostics message so this is
            # always an array when present.
            diag => ["Failed test 'fail'\nat xxx.t line 6."],
        },
        {
            causes_failure => 0,

            name => 'fixme',
            pass => 0,

            trace_file => 'xxx.t',
            trace_line => 7,

            # There can be more than one diagnostics message or todo
            # reason, so these are always an array when present.
            todo => ['broken'],

            # Diag message was turned into a note since the assertion was
            # TODO
            note => ["Failed test 'fixme'\nat xxx.t line 7."],
        },
        {
            causes_failure => 0,

            plan => 3,

            trace_file => 'xxx.t',
            trace_line => 8,
        },
    ],
    "Flattened events look like we expect"
);

有关 flatten() 为每个事件提供的完整描述，请参阅 Test2::API::InterceptResult::Event。

#方法

请注意，除非要求这样做，否则任何方法都不会修改原始实例。

#构造

#$events = Test2::API::InterceptResult->new(@EVENTS)

#$events = Test2::API::InterceptResult->new_from_ref(\@EVENTS)

这些方法从给定的事件创建新的 Test2::API::InterceptResult 实例。

第一个形式返回一个新的 blessed 数组引用。在 'new_from_ref' 形式中，您传入的引用将直接被 blessed。

如果在 void 上下文中调用这两个方法，它们都会抛出异常。这对于下面列出的 'filtering' 方法来说尤其重要，这些方法通常会返回一个新的实例，但在这种情况下它们会抛出异常，因为这可能意味着有人想要就地过滤原始实例。

#$clone = $events->clone()

创建一个原始事件的克隆。请注意，这是一个深层复制，整个结构都被复制了。这使用来自 Storable 的 dclone 来实现深层克隆。

#规范化

#@events = $events->event_list

这将以列表形式返回所有事件。

#$hub = $events->hub

这将返回一个新的 Test2::Hub 实例，该实例已处理了实例中包含的所有事件。这为您提供了一种简单的方法来检查事件导致的状态变化。

#$state = $events->state

这将返回处理完所有事件后集线器状态的摘要。

{
    count        => 2,      # Number of assertions made
    failed       => 1,      # Number of test failures seen
    is_passing   => 0,      # Boolean, true if the test would be passing
                            # after the events are processed.

    plan         => 2,      # Plan, either a number, undef, 'SKIP', or 'NO PLAN'
    follows_plan => 1,      # True if there is a plan and it was followed.
                            # False if the plan and assertions did not
                            # match, undef if no plan was present in the
                            # event list.

    bailed_out   => undef,  # undef unless there was a bail-out in the
                            # events in which case this will be a string
                            # explaining why there was a bailout, if no
                            # reason was given this will simply be set to
                            # true (1).

    skip_reason  => undef,  # If there was a skip_all this will give the
                            # reason.
}

#$new = $events->upgrade

#$events->upgrade(in_place => $BOOL)

注意：这通常会返回一个新的实例，而不会改变原始实例。如果您在 void 上下文中调用它，它将抛出异常。如果您想修改原始实例，则必须传入 in_place => 1 选项。当您要求就地修改时，您可以在 void 上下文中调用此方法。就地形式返回被修改的实例，以便您可以链接方法。

这将创建一个列表的克隆，其中所有事件都已转换为 Test2::API::InterceptResult::Event 实例。这非常有用，因为 Test2::API::InterceptResult::Event 提供了更好的事件处理接口。这使您可以避免考虑旧的事件类型。

这也意味着，即使您正在测试的工具随机更改了它生成的事件类型（例如，从 Test2::Event::Ok 更改为 Test2::Event::Pass，两者都会进行断言，并且两者都会规范化为相同的（或足够接近的） Test2::API::InterceptResult::Event 实例），您的测试也不会变得脆弱。

实际上，您几乎总是想要这样做，唯一的原因是它没有自动完成，是为了确保 intercept() 工具向后兼容。

#$new = $events->squash_info

#$events->squash_info(in_place => $BOOL)

注意：这通常会返回一个新的实例，而不会改变原始实例。如果您在 void 上下文中调用它，它将抛出异常。如果您想修改原始实例，则必须传入 in_place => 1 选项。当您要求就地修改时，您可以在 void 上下文中调用此方法。就地形式返回被修改的实例，以便您可以链接方法。

注意：新实例或修改后的实例中的所有事件都将转换为 Test2::API::InterceptResult::Event 实例。无法避免这种情况，压缩操作需要升级的事件类。

Test::More 和许多其他遗留工具会将注释、诊断和断言作为单独的事件发送。 Test::More 中的子测试将发送一个带有子测试名称的注释、子测试断言，以及如果子测试失败，则最终发送一个诊断事件。此方法将通过将注释和诊断压缩到与子测试相同的事件中来规范化事物（这与将它们放入子测试中不同，这不是发生的事情）。

#过滤

注意：这些通常会返回新的实例，而不会更改原始实例。如果您在 void 上下文中调用它们，它们将抛出异常。如果您想修改原始实例，则必须传入 in_place => 1 选项。当您要求就地修改它们时，您可以在 void 上下文中调用它们。就地形式返回被修改的实例，以便您可以链接方法。

#%PARAMS

这些都接受相同的 2 个可选参数

#in_place => $BOOL

如果为真，该方法将就地修改实例，而不是返回新实例。

#args => \@ARGS

如果您希望将参数传递到用于过滤的事件方法中，您可以在此处执行此操作。

#方法

#$events->grep($CALL, %PARAMS)

这实际上是

Test2::API::InterceptResult->new(
    grep { $_->$CALL( @{$PARAMS{args}} ) } $self->event_list,
);

注意： $CALL 在事件的升级版本上调用，但返回的事件是原始事件，而不是升级后的事件。

$CALL 可以是 Test2::API::InterceptResult::Event 上的方法名称，也可以是代码引用。

#$events->asserts(%PARAMS)

这实际上是

$events->grep(has_assert => @{$PARAMS{args}})

它返回一个新实例，其中只包含进行了断言的事件。

#$events->subtests(%PARAMS)

这实际上是

$events->grep(has_subtest => @{$PARAMS{args}})

它返回一个新实例，其中只包含具有子测试的事件。

#$events->diags(%PARAMS)

这实际上是

$events->grep(has_diags => @{$PARAMS{args}})

它返回一个新实例，其中只包含具有诊断信息的事件。

#$events->notes(%PARAMS)

这实际上是

$events->grep(has_notes => @{$PARAMS{args}})

它返回一个新实例，其中只包含具有注释的事件。

#$events->errors(%PARAMS)

注意： 错误与失败的断言不同。失败的断言是另一回事。

这实际上是

$events->grep(has_errors => @{$PARAMS{args}})

它返回一个新实例，其中只包含具有错误的事件。

#$events->plans(%PARAMS)

这实际上是

$events->grep(has_plan => @{$PARAMS{args}})

它返回一个新实例，其中只包含设置计划的事件。

#$events->causes_fail(%PARAMS)

#$events->causes_failure(%PARAMS)

这些实际上是

$events->grep(causes_fail    => @{$PARAMS{args}})
$events->grep(causes_failure => @{$PARAMS{args}})

注意： causes_fail() 和 causes_failure() 在事件中是彼此的别名，因此这些方法在这里实际上也是别名。

它返回一个新实例，其中只包含导致失败的事件。

#映射

这些方法始终返回一个数组引用。

注意： Test2::API::InterceptResult::Event 上的方法不会以任何方式更改事件。

关于事件的重要说明:

Test2::API::InterceptResult::Event 是专门为事件列表而设计的。大多数不适用于特定事件的方法将返回一个空列表，因此您通常不必担心出现意外的 undef 值或异常。对事件方法进行映射是一种扩展使用方式，因此它非常适合生成列表。

规则的例外情况

某些方法，例如 causes_fail，始终为所有事件返回布尔值 true 或 false。任何以 the_ 为前缀的方法都表示该事件应该恰好包含一个东西，因此当该条件不满足时，这些方法将抛出异常。

#$arrayref = $events->map($CALL, %PARAMS)

这实际上是

[ map { $_->$CALL(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

$CALL 可以是 Test2::API::InterceptResult::Event 上的方法名称，也可以是代码引用。

#$arrayref = $events->flatten(%PARAMS)

这实际上是

[ map { $_->flatten(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的扁平化结构列表。

有关 flatten() 返回内容的详细信息，请参阅 Test2::API::InterceptResult::Event。

#$arrayref = $events->briefs(%PARAMS)

这实际上是

[ map { $_->briefs(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的事件摘要列表。

有关 brief() 返回内容的详细信息，请参阅 Test2::API::InterceptResult::Event。

#$arrayref = $events->summaries(%PARAMS)

这实际上是

[ map { $_->summaries(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的事件摘要列表。

有关 summary() 返回内容的详细信息，请参阅 Test2::API::InterceptResult::Event。

#$arrayref = $events->subtest_results(%PARAMS)

这实际上是

[ map { $_->subtest_result(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的事件摘要列表。

有关 subtest_result() 返回内容的详细信息，请参阅 Test2::API::InterceptResult::Event。

#$arrayref = $events->diag_messages(%PARAMS)

这实际上是

[ map { $_->diag_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的诊断消息（字符串）列表。

有关 diag_messages() 返回内容的详细信息，请参阅 Test2::API::InterceptResult::Event。

#$arrayref = $events->note_messages(%PARAMS)

这实际上是

[ map { $_->note_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的通知消息（字符串）列表。

有关 note_messages() 返回内容的详细信息，请参阅 Test2::API::InterceptResult::Event。

#$arrayref = $events->error_messages(%PARAMS)

这实际上是

[ map { $_->error_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];

它返回一个新的错误消息列表（字符串）。

有关 error_messages() 返回内容的详细信息，请参见 Test2::API::InterceptResult::Event。

#来源

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 与他们联系。