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"
);請參閱 Test2::API::InterceptResult::Event 以取得 flatten() 為每個事件提供的完整說明。
請注意，除非要求，否則沒有方法會修改原始實例。
這些會從給定的事件建立 Test2::API::InterceptResult 的新實例。
在第一個形式中，會傳回新的祝福陣列參考。在 'new_from_ref' 形式中，您傳入的參考會直接受到祝福。
如果在無效內容中呼叫，這兩個都會擲回例外。這對於下面列出的「篩選」方法來說非常重要，這些方法通常會傳回新的實例，它們會在這種情況下擲回例外，因為這可能表示有人打算在原地篩選原始實例。
複製原始事件。請注意，這是深度複製，整個結構會被複製。這會使用 Storable 中的 dclone 來達成深度複製。
這會以清單形式傳回所有事件。
這會傳回新的 Test2::Hub 實例，該實例已處理實例中包含的所有事件。這提供一個簡單的方法來檢查事件造成的狀態變更。
這會傳回處理所有事件後樞紐狀態的摘要。
{
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.
}注意：這通常會傳回新的實例，讓原始實例保持不變。如果您在無效內容中呼叫它，它會擲回例外。如果您想要修改原始實例，您必須傳入 in_place => 1 選項。當您要求在原地修改時，您可以在無效內容中呼叫它。原地形式會傳回已修改的實例，以便您可以串連方法。
這將建立一個清單的複製，其中所有事件都已轉換為 Test2::API::InterceptResult::Event 執行個體。這非常有用，因為 Test2::API::InterceptResult::Event 提供了一個更好的介面，可用於處理事件。這讓您可以避免思考舊式事件類型。
這也表示，如果您正在測試的工具隨機變更它所產生的事件類型（例如，從 Test2::Event::Ok 變更為 Test2::Event::Pass），則針對清單執行的測試不會脆弱，因為這兩個都會進行斷言，而且兩個都會正規化為相同的（或足夠接近的）Test2::API::InterceptResult::Event 執行個體。
您幾乎總是需要這個，之所以不會自動執行，只是為了確保 intercept() 工具具有向後相容性。
注意：這通常會傳回新的實例，讓原始實例保持不變。如果您在無效內容中呼叫它，它會擲回例外。如果您想要修改原始實例，您必須傳入 in_place => 1 選項。當您要求在原地修改時，您可以在無效內容中呼叫它。原地形式會傳回已修改的實例，以便您可以串連方法。
注意：新或修改執行個體中的所有事件都將轉換為 Test2::API::InterceptResult::Event 執行個體。沒有辦法避免這一點，壓縮操作需要升級的事件類別。
Test::More 和許多其他舊式工具會將註解、診斷和斷言作為分開的事件傳送。Test::More 中的子測試會傳送一個包含子測試名稱的註解、子測試斷言，以及最後一個診斷事件（如果子測試失敗）。此方法會透過將註解和診斷壓縮到與子測試相同的事件中來正規化事件（這不同於將它們放入子測試中，這並非發生的事情）。
注意：這些通常會傳回新的執行個體，讓原始執行個體保持不變。如果您在無效內容中呼叫它們，它們會擲回例外。如果您想要修改原始執行個體，您必須傳入 in_place => 1 選項。當您要求在原處修改它們時，您可以在無效內容中呼叫它們。原處形式會傳回已修改的執行個體，讓您可以串接方法。
這些都接受相同的 2 個選用參數
這基本上是
Test2::API::InterceptResult->new(
grep { $_->$CALL( @{$PARAMS{args}} ) } $self->event_list,
);注意： $CALL 會在事件的升級版本上呼叫，但傳回的事件會是原始事件，而不是升級的事件。
$CALL 可以是 Test2::API::InterceptResult::Event 上方法的名稱，或是 coderef。
這基本上是
$events->grep(has_assert => @{$PARAMS{args}})它傳回一個新的實例，其中只包含執行斷言的事件。
這基本上是
$events->grep(has_subtest => @{$PARAMS{args}})它傳回一個新的實例，其中只包含具有子測試的事件。
這基本上是
$events->grep(has_diags => @{$PARAMS{args}})它傳回一個新的實例，其中只包含具有診斷的事件。
這基本上是
$events->grep(has_notes => @{$PARAMS{args}})它傳回一個新的實例，其中只包含具有備註的事件。
注意：錯誤並非失敗的斷言。失敗的斷言是不同的東西。
這基本上是
$events->grep(has_errors => @{$PARAMS{args}})它傳回一個新的實例，其中只包含具有錯誤的事件。
這基本上是
$events->grep(has_plan => @{$PARAMS{args}})它傳回一個新的實例，其中只包含設定計畫的事件。
它們基本上是
$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_ 為字首的方法傳達的意圖是事件應該有某項的 1 個，因此當該條件不為 true 時，這些方法會引發例外。
這基本上是
[ map { $_->$CALL(@{ $PARAMS{args} }) } $events->upgrade->event_list ];$CALL 可以是 Test2::API::InterceptResult::Event 上方法的名稱，或是 coderef。
這基本上是
[ map { $_->flatten(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一個新的扁平化結構清單。
請參閱 Test2::API::InterceptResult::Event 以取得 flatten() 傳回內容的詳細資料。
這基本上是
[ map { $_->briefs(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一個新的事件摘要清單。
請參閱 Test2::API::InterceptResult::Event 以取得 brief() 傳回內容的詳細資料。
這基本上是
[ map { $_->summaries(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一個新的事件摘要清單。
請參閱 Test2::API::InterceptResult::Event 以取得 summary() 傳回內容的詳細資料。
這基本上是
[ map { $_->subtest_result(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一個新的事件摘要清單。
請參閱 Test2::API::InterceptResult::Event 以取得 subtest_result() 傳回內容的詳細資料。
這基本上是
[ map { $_->diag_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一個新的診斷訊息清單（字串）。
請參閱 Test2::API::InterceptResult::Event 以取得 diag_messages() 傳回內容的詳細資料。
這基本上是
[ map { $_->note_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一組新的通知訊息（字串）。
請參閱 Test2::API::InterceptResult::Event，以瞭解 note_messages() 傳回的詳細資料。
這基本上是
[ map { $_->error_messages(@{ $PARAMS{args} }) } $events->upgrade->event_list ];它會傳回一組新的錯誤訊息（字串）。
請參閱 Test2::API::InterceptResult::Event，以瞭解 error_messages() 傳回的詳細資料。
Test2 的原始碼儲存庫可在 http://github.com/Test-More/test-more/ 中找到。
版權所有 2020 Chad Granum <exodist@cpan.org>。
此程式為免費軟體；您可以在與 Perl 相同的條款下重新散布或修改它。
請參閱 http://dev.perl.org/licenses/