Test2::API::InterceptResult::Event

(原始碼, CPAN)

版本 1.302194

#名稱

Test2::API::InterceptResult::Event - 用於測試其他測試工具的事件表示。

#說明

intercept { ... } 來自 Test2::API 會傳回 Test2::API::InterceptResult 的一個已祝福的陣列參考，而 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
);

#方法

#!!! 重要設計注意事項 !!!

請注意這些回傳值，許多在適用的情況下會回傳一個純量，或是在不適用的情況下回傳一個空清單（而不是 undef）。許多也會總是回傳一個包含 0 個或更多項目的清單。有些總是回傳一個純量。請注意，沒有任何方法會在意內容，它們的行為會保持一致，無論是純量、清單或空內容。

這樣做的原因是，這個類別特別設計成用於清單中，並在大量作業中產生更多清單。有時在一個映射中，你希望事件中沒有任何東西顯示出來，而且你不想在它的位置上出現一個 undef。一般來說，單一事件實例不會單獨使用，儘管這是允許的。

作為一個一般規則，任何以 the_ 為前綴的方法都表示事件應該有且僅有 1 個指定項目，而且如果項目有 0 個或多於 1 個，就會擲出例外。

#屬性

#$hashref = $event->facet_data: 這將會回傳 facet 資料 hashref，這是 Test2 在任何給定的事件中所關心的所有內容。
#$class = $event->result_class: 這通常是 Test2::API::InterceptResult。這是設定在建構時，以便子測試結果可以依需求轉換成它的實例。

#複製

#$copy = $event->clone: 建立事件的深度複製。修改任一事件都不會影響另一個事件。

#$bool = $event->causes_failure

#$bool = $event->causes_fail

這兩個都是相同功能的別名。

這將總是回傳一個 true 值或一個 false 值。這從不回傳一個清單。

這個方法可能會相對慢（仍然非常快），因為它透過建立 Test2::Hub 的實例並要求它處理事件來判定通過或失敗，然後再向 hub 詢問它的通過/失敗狀態。這比建立邏輯來進行檢查要慢，但它更可靠，因為它會總是告訴你 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)

如果您知道您將只有一個切面實例，您可以呼叫這個。

如果您正確，並且只有一個切面實例，它總是會傳回 hashref。

如果切面實例為 0，這會傳回未定義，而不是空清單。

如果實例超過 1 個，這會擲回例外，因為您的假設不正確。

#@list_of_facets = $event->trace

待辦事項

#$undef_or_hashref = $event->the_trace

這會傳回追蹤 hashref，或如果不存在，則傳回未定義。

#$undef_or_arrayref = $event->frame

如果存在追蹤，並且有一個呼叫者框架，這會是一個陣列參考

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

如果追蹤不存在，或沒有呼叫者框架，這會傳回未定義。

#$undef_or_string = $event->trace_details

這通常是未定義，但偶爾會有一個字串覆寫檔案/行號偵錯，通常在測試失敗時提供追蹤。

#$undef_or_string = $event->trace_package

與 (caller())[0] 相同，追蹤架構的第一個元素。

如果不存在，將為 undef。

#$undef_or_string = $event->trace_file

與 (caller())[1] 相同，追蹤架構的第二個元素。

如果不存在，將為 undef。

#$undef_or_integer = $event->trace_line

與 (caller())[2] 相同，追蹤架構的第三個元素。

如果不存在，將為 undef。

#$undef_or_string = $event->trace_subname

#$undef_or_string = $event->trace_tool

相同事物的別名

與 (caller($level))[4] 相同，追蹤架構的第四個元素。

如果不存在，將為 undef。

#$undef_or_string = $event->trace_signature

追蹤的唯一簽章字串。如果單一內容產生多個事件，它們都將具有相同的簽章。這可用於在事後將斷言和作為獨立事件發送的診斷聯繫在一起。

#$bool = $event->has_assert: 如果事件有斷言層面，傳回 true，否則傳回 false。
#$undef_or_hashref = $event->the_assert: 如果存在，傳回斷言層面，如果不存在，傳回 undef。
#@list_of_facets = $event->assert: 待辦事項
#EMPTY_LIST_OR_STRING = $event->assert_brief: 如果存在斷言，傳回提供斷言簡述的字串。如果沒有斷言，傳回空清單。

#$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 個 hashref 的清單。如果要求中斷，則 hashref 將會是控制切面。
#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

待辦事項

#$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

#原始碼

Test2 的原始碼儲存庫可以在 http://github.com/Test-More/test-more/ 找到。

#維護人員

#Chad Granum <exodist@cpan.org>

#作者

#Chad Granum <exodist@cpan.org>

#版權

這個程式是自由軟體；你可以根據 Perl 本身的條款重新散布或修改它。

請參閱 http://dev.perl.org/licenses/

目錄

#名稱

#說明

#語法

#方法

#!!! 重要設計注意事項 !!!

#屬性

#複製

#濃縮多面相資料

#直接任意切面存取

#追蹤切面

#ASSERT FACET

#SUBTESTS (PARENT FACET)

#控制切面（中斷、編碼）

#計畫切面

#特赦切面（待辦事項和略過）

#ERROR FACET (CAPTURED EXCEPTIONS)

#INFO FACET (DIAG, NOTE)

#原始碼

#維護人員

#作者

#版權