内容

• 名称
• 描述
• 概要
• 方法
  • !!! 设计中的重要说明 !!!
  • 属性
  • 重复
  • 浓缩的多面数据
  • 直接任意面访问
  • 跟踪面
  • 断言面
  • 子测试（父面）
  • 控制面（退出、编码）
  • 计划面
  • 特赦面（TODO 和 SKIP）
  • 错误面（捕获的异常）
  • 信息面（诊断、注释）
• 源
• 维护人员
• 作者
• 版权

#名称

Test2::API::InterceptResult::Event - 用于测试其他测试工具的事件表示。

#描述

intercept { ... } from Test2::API 返回 Test2::API::InterceptResult 的实例，它是 Test2::API::InterceptResult::Event 对象的已祝福数组引用。

此 POD 文档记录了这些事件的方法，主要供你在测试测试工具时使用。

#概要

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

my $events = intercept {
    ok(1, "A passing assertion");
    plan(1);
};

# This will convert all events into instances of
# Test2::API::InterceptResult::Event. Until we do this they are the
# original Test::Event::* instances
$events->upgrade(in_place => 1);

# Now we can get individual events in this form
my $assert = $events->[0];
my $plan   = $events->[1];

# Or we can operate on all events at once:
my $flattened = $events->flatten;
is(
    $flattened,
    [
      {
        causes_failure => 0,

        name => 'A passing assertion',
        pass => 1,

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

        plan => 1,

        trace_file => 'xxx.t',
        trace_line => 6,
      },
    ],
    "Flattened both events and returned an arrayref of the results
);

#方法

#!!! 设计中的重要说明 !!!

请注意这些方法的返回值，许多方法在适用时返回标量，在不适用时返回空列表（而不是未定义值）。许多方法还始终返回 0 个或更多个项目的列表。有些方法始终返回标量。请注意，没有一个方法关心上下文，无论标量、列表还是空上下文，它们的行为都是一致的。

这样做是因为此类专门设计为在列表中使用，并在批量操作中生成更多列表。有时在地图中，您希望事件中没有任何内容显示，并且不希望在其位置出现未定义。一般来说，单个事件实例不会单独使用，尽管这是允许的。

作为一般规则，任何以 the_ 为前缀的方法都意味着事件应该恰好有 1 个指定项，并且如果该项有 0 个或多于 1 个，则会抛出异常。

#属性

#$hashref = $event->facet_data

这将返回 facet 数据哈希引用，这是 Test2 关注的任何给定事件的所有内容。

#$class = $event->result_class

这通常是 Test2::API::InterceptResult。这在构建时设置，以便可以根据需要将子测试结果转换为它的实例。

#复制

#$copy = $event->clone

创建事件的深度副本。修改任一事件都不会影响另一个事件。

#浓缩的多面数据

#$bool = $event->causes_failure

#$bool = $event->causes_fail

它们都是同一功能的别名。

这将始终返回真值或假值。它从不返回列表。

此方法可能相对较慢（仍然非常快），因为它通过创建 Test2::Hub 的实例并要求它处理事件来确定通过或失败，然后向中心询问其通过/失败状态。这比构建逻辑来执行检查要慢，但它更可靠，因为它将始终告诉您中心的想法，因此逻辑永远不会相对于实际关心的 Test2 逻辑过时。

#STRING_OR_EMPTY_LIST = $event->brief

并非所有事件都有摘要，一些事件未由格式化程序呈现，其他事件没有值得查看的“摘要”数据。如果是这种情况，则返回一个空列表。这样做是有意为之，以便可以在映射操作中使用它，而无需在结果中包含 undef。

当可以生成摘要时，它始终是一个单行字符串，并且按原样返回，而不是列表。

可能的摘要

# From control facets
"BAILED OUT"
"BAILED OUT: $why"

# From error facets
"ERROR"
"ERROR: $message"
"ERROR: $partial_message [...]"
"ERRORS: $first_error_message [...]"

# From assert facets
"PASS"
"FAIL"
"PASS with amnesty"
"FAIL with amnesty"

# From plan facets
"PLAN $count"
"NO PLAN"
"SKIP ALL"
"SKIP ALL: $why"

请注意，仅返回第一个适用的摘要。这本质上是一个差劲的 TAP，它仅包含可能（但不一定）导致故障的方面。

#$hashref = $event->flatten

#$hashref = $event->flatten(include_subevents => 1)

这始终返回一个哈希引用。这将最有趣方面的最有用的所有数据放入一个哈希引用中，以便于验证。

如果没有有意义的方面，这将返回一个空哈希引用。

如果给定“include_subevents”参数，它还将包括子测试数据

以下是每个可能字段的列表。如果某个字段不适用，则不会出现。

#始终存在

causes_failure => 1,    # Always present

#如果事件具有跟踪方面，则存在

trace_line    => 42,
trace_file    => 'Foo/Bar.pm',
trace_details => 'Extra trace details',    # usually not present

#如果存在断言

pass => 0,
name => "1 + 1 = 2, so math works",

#如果存在计划

plan => $count_or_SKIP_ALL_or_NO_PLAN,

#如果存在特赦方面

对于存在的每种类型，您都会得到一个数组。

todo => [    # Yes you could be under multiple todos, this will list them all.
    "I will fix this later",
    "I promise to fix these",
],

skip => ["This will format the main drive, do not run"],

... => ["Other amnesty"]

#如果存在信息（注释/诊断）方面

对于任何存在的方面，您都会得到一个数组引用，如果不存在，则不会定义键。

diag => [
    "Test failed at Foo/Bar.pm line 42",
    "You forgot to tie your boots",
],

note => ["Your boots are red"],

...  => ["Other info"],

#如果存在错误方面

始终是一个数组引用

error => [
    "non fatal error (does not cause test failure, just an FYI",
    "FATAL: This is a fatal error (causes failure)",
],

# Errors can have alternative tags, but in practice are always 'error',
# listing this for completeness.
... => [ ... ]

#如果事件是子测试，则存在

subtest => {
    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 => "foo",    # if there was a bail-out in the
                            # events in 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 => "foo",   # If there was a skip_all this will give the
                            # reason.
},

如果将 (include_subtest => 1) 作为参数提供，则将包括以下内容。这是将所有子测试子事件转换为 Test2::API::InterceptResult 实例并在其上调用 flatten 方法的结果。

subevents => Test2::API::InterceptResult->new(@child_events)->flatten(...),

#如果请求保释

如果没有给出原因，则将其设置为 1。

bailed_out => "reason",

#$hashref = $event->summary()

这返回一个有限的摘要。请参阅 flatten()，它通常是一个更好的选择。

{
    brief => $event->brief || '',

    causes_failure => $event->causes_failure,

    trace_line    => $event->trace_line,
    trace_file    => $event->trace_file,
    trace_tool    => $event->trace_subname,
    trace_details => $event->trace_details,

    facets => [ sort keys(%{$event->{+FACET_DATA}}) ],
}

#直接任意切面访问

#@list_of_facets = $event->facet($name)

这始终返回一个包含 0 个或更多项的列表。这从事件中获取切面实例。对于“assert”之类的切面，这将始终返回 0 或 1 个项。对于“info”（诊断、注释）之类的事件，这将返回 0 个或更多实例，每个切面实例一个。

这些将被祝福为适当的 Test2::EventFacet 子类。如果找不到子类，它将被祝福为 Test2::API::InterceptResult::Facet 通用切面类。

#$undef_or_facet = $event->the_facet($name)

如果您知道您将拥有一个切面的 1 个实例，则可以调用此方法。

如果您正确并且切面只有一个实例，它将始终返回哈希引用。

如果切面有 0 个实例，这将返回未定义，而不是空列表。

如果有多个实例，这将抛出异常，因为您的假设不正确。

#跟踪切面

#@list_of_facets = $event->trace

待办事项

#$undef_or_hashref = $event->the_trace

这返回跟踪哈希引用，如果不存在，则返回未定义。

#$undef_or_arrayref = $event->frame

如果存在跟踪并且有调用者框架，这将是一个数组引用

[$package, $file, $line, $subname]

如果跟踪不存在或没有调用者框架，这将返回未定义。

#$undef_or_string = $event->trace_details

这通常是未定义的，但偶尔会有一个字符串覆盖测试失败时跟踪通常提供的文件/行号调试。

#$undef_or_string = $event->trace_package

与 (caller())[0] 相同，跟踪框架的第一个元素。

如果不存在，将为未定义。

#$undef_or_string = $event->trace_file

与 (caller())[1] 相同，跟踪框架的第二个元素。

如果不存在，将为未定义。

#$undef_or_integer = $event->trace_line

与 (caller())[2] 相同，跟踪框架的第三个元素。

如果不存在，将为未定义。

#$undef_or_string = $event->trace_subname

#$undef_or_string = $event->trace_tool

同一事物的别名

与 (caller($level))[4] 相同，跟踪框架的第四个元素。

如果不存在，将为未定义。

#$undef_or_string = $event->trace_signature

一个字符串，是跟踪的唯一签名。如果一个单一的上下文生成多个事件，它们将具有相同的签名。这可用于在事后将断言和作为单独事件发送的诊断联系在一起。

#ASSERT FACET

#$bool = $event->has_assert

如果事件有断言方面，则返回真，如果没有，则返回假。

#$undef_or_hashref = $event->the_assert

如果存在，则返回断言方面，如果不存在，则返回未定义。

#@list_of_facets = $event->assert

待办事项

#EMPTY_LIST_OR_STRING = $event->assert_brief

如果存在断言，则返回一个字符串，简要说明断言。如果不存在断言，则返回一个空列表。

#SUBTESTS (PARENT FACET)

#$bool = $event->has_subtest

如果此事件中存在子测试，则返回 True。

#$undef_or_hashref = $event->the_subtest

如果存在，则获取一个子测试，否则返回未定义。

#@list_of_facets = $event->subtest

待办事项

#EMPTY_LIST_OR_OBJECT = $event->subtest_result

如果没有子测试，则返回一个空列表。

获取表示子测试的 Test2::API::InterceptResult 实例。

#控制方面（退出、编码）

#$bool = $event->has_bailout

如果退出，则返回 True

#$undef_hashref = $event->the_bailout

如果控制方面请求退出，则返回控制方面。

#EMPTY_LIST_OR_HASHREF = $event->bailout

获取 0 或 1 个哈希引用列表。如果请求退出，则哈希引用将是控制方面。

#EMPTY_LIST_OR_STRING = $event->bailout_brief

如果存在，则获取退出简报。

#EMPTY_LIST_OR_STRING = $event->bailout_reason

获取退出原因，如果没有提供原因，则返回空字符串，如果没有退出，则返回空列表。

#计划方面

待办事项

#$bool = $event->has_plan

#$undef_or_hashref = $event->the_plan

#@list_if_hashrefs = $event->plan

#EMPTY_LIST_OR_STRING $event->plan_brief

#赦免方面（TODO 和 SKIP）

待办事项

#$event->has_amnesty

#$event->the_amnesty

#$event->amnesty

#$event->amnesty_reasons

#$event->has_todos

#$event->todos

#$event->todo_reasons

#$event->has_skips

#$event->skips

#$event->skip_reasons

#$event->has_other_amnesty

#$event->other_amnesty

#$event->other_amnesty_reasons

#错误方面（捕获的异常）

待办事项

#$event->has_errors

#$event->the_errors

#$event->errors

#$event->error_messages

#$event->error_brief

#信息方面（诊断、注释）

待办事项

#$event->has_info

#$event->the_info

#$event->info

#$event->info_messages

#$event->has_diags

#$event->diags

#$event->diag_messages

#$event->has_notes

#$event->notes

#$event->note_messages

#$event->has_other_info

#$event->other_info

#$event->other_info_messages

#SOURCE

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

#MAINTAINERS

#Chad Granum <[email protected]>

#AUTHORS

#Chad Granum <[email protected]>

#COPYRIGHT

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

此程序是免费软件；您可以在与 Perl 自身相同的条款下重新分发和/或修改它。

请参阅 https://dev.perl5.cn/licenses/

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

Perl 文档由 Perl 5 Porters 在 Perl 开发中维护。如有任何有关文档内容或格式的问题，请联系他们，方式为通过 Perl 问题跟踪器、邮件列表 或 IRC。