Test2::Event - 事件的基本類別
傳遞至 Test2 的所有事件物件的基本類別。
package Test2::Event::MyEvent;
use strict;
use warnings;
# This will make our class an event subclass (required)
use base 'Test2::Event';
# Add some accessors (optional)
# You are not obligated to use HashBase, you can use any object tool you
# want, or roll your own accessors.
use Test2::Util::HashBase qw/foo bar baz/;
# Use this if you want the legacy API to be written for you, for this to
# work you will need to implement a facet_data() method.
use Test2::Util::Facets2Legacy;
# Chance to initialize some defaults
sub init {
my $self = shift;
# no other args in @_
$self->set_foo('xxx') unless defined $self->foo;
...
}
# This is the new way for events to convey data to the Test2 system
sub facet_data {
my $self = shift;
# Get common facets such as 'about', 'trace' 'amnesty', and 'meta'
my $facet_data = $self->common_facet_data();
# Are you making an assertion?
$facet_data->{assert} = {pass => 1, details => 'my assertion'};
...
return $facet_data;
}
1;取得生成此事件時 Test2::EventFacet::Trace 的快照
檢查 2 個事件是否相關。在此情況下，相關表示其追蹤共用簽章，表示它們使用相同的內容建立（或至少使用共用 ID 的內容建立，這兩者相同，除非有人執行非常糟糕的動作）。
這可用於可靠連結由相同工具建立的多個事件。例如，失敗測試（例如 ok(0, "fail"）會產生 2 個事件，一個是 Test2::Event::Ok，另一個是 Test2::Event::Diag，這兩個事件相關，因為它們在相同內容和相同初始工具下建立（儘管多個工具可能嵌套在初始工具之下）。
如果無法檢查關係，則會傳回 undef，這會發生在任一事件具有不完整或遺失的追蹤時。如果追蹤已完成，但沒有相符，則會傳回 0。如果有相符，則會傳回 1。
這可用於將特赦新增至這個事件。特赦在大部分情況下只會影響失敗的斷言，但有些格式化程式可能會將它們顯示為通過的斷言，甚至是非斷言。
特赦會防止失敗的斷言導致整體測試失敗。換句話說，它將失敗標記為預期和允許的。
注意：這是「TODO」在幕後實作的方式。TODO 本質上是具有「TODO」標籤的特赦。詳細資料是 TODO 的原因。
如果已啟用 UUID 標記（請參閱 Test::API），則任何通過樞紐的事件都會標記 UUID。在大部分情況下，新建立的事件尚未標記。
此方法用於按名稱（或金鑰）載入切面。它會嘗試載入切面類別，如果成功，它會傳回已載入的類別。如果失敗，它會傳回 undef。這會在類別層級快取結果，以便將來的呼叫會更快。
$name 變數應該是 used to access the facet in a facets hashref 的金鑰。例如，斷言切面具有「assert」金鑰，資訊切面具有「info」金鑰，錯誤切面具有「errors」金鑰。您可以在名稱結尾包含或省略「s」，此方法足夠聰明，可以同時嘗試「s」和非「s」形式，它會先檢查您提供的內容，如果找不到，它會新增或移除「s」並再次嘗試。
這會傳回使用 load_facet() 方法載入的所有切面的清單。這不會傳回任何尚未載入的類別，或未載入或未直接呼叫 load_facet() 的類別。
注意：核心切面類型會自動載入並填入此清單。
子類別可以使用此方法來產生起始切面資料雜湊。這會使用追蹤、元資料、特赦和關於切面來填入雜湊。這些切面幾乎總是對所有事件以相同的方式產生。
如果您沒有覆寫這項內容，預設實作將嘗試從舊版 API 產生切面。此產生僅限於舊版 API 能提供的內容。建議您覆寫此方法並寫出明確的切面資料。
這會從 facet_data() 取得雜湊，並將每個切面祝福為適當的 Test2::EventFacet::* 子類別。如果找不到任何給定切面的類別，它將不變地傳遞。
此方法將驗證切面資料並傳回錯誤清單。如果未找到任何錯誤，這將傳回一個空清單。
這可以作為沒有參數的物件方法呼叫，在這種情況下，將呼叫 facet_data() 方法以取得要驗證的切面資料。
當作為物件方法使用時，可以省略 \%facet_data 參數。
當作為類別方法使用時，需要 \%facet_data 參數。
其他參數會被吸入 %params hash。
目前僅定義 1 個參數
設為 true 時（預設為 false），這將會拒絕找不到 facet 類別的任何 facet。通常，沒有類別的 facet 會被假設為自訂，並會被忽略。
Facets 是事件傳達其目的給 Test2 內部和格式化工具的方式。沒有 facets 的事件不會對整體測試狀態造成任何預期效果，也不會顯示在大部分格式化工具中，除了可能會顯示已看到未知類型的事件。
Facets 由 facet_data() 子常式產生，您幾乎總是應該覆寫它。facet_data() 預期會傳回一個 hashref，其中每個鍵都是 facet 類型，而值不是具有該 facet 資料的 hashref，就是 hashref 的陣列。有些 facets 必須定義為單一 hashref，有些必須定義為 hashref 的陣列，沒有 facets 允許同時使用這兩種方式。
facet_data() 不得對它傳回的資料、主 hashref 和巢狀 facet hashref 進行 bless，必須是空的，儘管每個 facet 中包含的項目可以進行 bless。此方法傳回的資料應該是內部資料的副本，以防止意外修改狀態。
facets() 從 facet_data() 取得資料，並將其 bless 到 Test2::EventFacet::* 套件中。然而，這很少使用，EventFacet 套件主要是為了方便和文件編寫。EventFacet 類別完全不會在內部使用，而是使用原始資料。
以下是按套件分類的 facet 類型清單。這些套件不會在內部使用，但每個類型的文件都保存在其中。
注意：每個 facet 類型都有 'details' 欄位。此欄位總是供人閱讀，並應在提供時說明 facet 的「原因」。所有其他欄位都是特定於 facet 的。
這包含事件本身的資訊，例如事件套件名稱。此面向的 details 欄位是事件的整體摘要。
如果進行了斷言，則使用此面向。此面向的 details 欄位是斷言的描述。
此面向用於告訴 Test2::Event::Hub 事件導致的特殊動作。例如停止所有測試、終止目前的測試等。在此面向中，details 欄位說明採取任何特殊動作的原因。
注意：這就是實作終止的方式。
元面向包含附加到事件的所有元資料。在這種情況下，details 欄位沒有特殊意義，但如果某些東西設定事件上的「details」元金鑰，則可能會存在。
此面向包含巢狀事件和子測試的類似詳細資料。在此面向中，details 欄位通常會是子測試的名稱。
此面向告訴系統已設定計畫。此面向的 details 欄位通常會留空，但如果存在，則會說明計畫為何如此，如果計畫是要全部略過，這最有用。
此面向包含與事件何時何地產生的相關資訊。這就是已知失敗的測試檔案和行號的方式。此面向也可以幫助您判斷測試是否相關。
在此面向中，details 欄位會覆寫斷言失敗時提供的「在 test_file.t 第 42 行失敗」訊息。
特赦面向是清單，而不是單一項目，這很重要，因為特赦可以同時來自多個地方。
對於每個特赦的執行個體，details 欄位會說明為什麼會授予特赦。
注意：在格式化程式之外，特赦只會用來原諒一個失敗的斷言。
errors 面向是一個清單，而不是單一項目，可以列出任意數量的錯誤。在此面向中，details 會描述錯誤，或可能包含原始錯誤訊息本身（例如例外）。在 Perl 中，例外可能是已賜福的物件，因此此面向的原始資料可能包含已賜福的巢狀項目。
並非所有錯誤都被視為致命錯誤，有一個 fail 欄位，必須設定為錯誤，才會導致測試失敗。
注意：此面向的獨特之處在於，欄位名稱為「errors」，而套件為「Error」。這是因為這是唯一同時為清單，且名稱的複數形式與單數形式不同的面向類型。這可能會造成一些混淆，但我認為它會比其他選項更不混淆。
「info」面向是一個清單，而不是單一項目，可以將任何數量的額外資訊附加到事件中。有些資訊可能是重要的診斷，有些可能只是性質上的註解，這由 debug 旗標決定。
對於此面向，details 旗標就是資訊本身。此資訊可以是字串，也可以是資料結構以供顯示。這是少數可能包含已賜福項目的面向類型之一。
如果此事件應導致測試失敗，則傳回 true。一般來說，這應該是 false。
如果此事件應導致測試計數增加，則應為 true。
如果您的事件需要對 Test2::Hub 產生額外影響，您可以覆寫此方法。
這會在您的事件傳遞給格式化程式之前呼叫。
如果此事件巢狀在其他事件中，這應該是巢狀深度。（這主要是針對子測試）
如果您的事件是全域性的，請將此設定為 true，也就是說，不論何時何地產生，所有執行緒和程序都應該看到它。這不是常見的需求，它是由 bail-out 和 skip_all 使用來結束測試。
這會在您的事件傳遞給格式化程式之後呼叫。這通常應該傳回 undef，只有當您的事件應該立即結束測試時才變更這個設定。
如果您要這個事件結束測試，您應該在此傳回結束代碼。結束代碼 0 表示結束成功，任何其他整數表示結束失敗。
這由 Test2::Event::Plan 使用，當計畫為 'skip_all' 時結束 0。這也由 Test2::Event:Bail 使用，以強制測試結束失敗。
這會在事件傳送給格式化程式之後呼叫，以確保事件被看到並理解。
這旨在成為事件的人類可讀摘要。這理想上應該只有一行長，但必要時可以使用多行。這旨在供人類使用。您不需要讓機器容易理解。
預設值是僅傳回事件套件名稱。
檢查這個事件是否設定測試計畫。如果沒有，它會傳回一個空清單。如果它設定計畫，它會傳回一個包含 1 到 3 個項目順序的清單：預期的測試計數、測試指令、指令原因。
如果事件包含診斷資訊，則為 True。這很有用，因為非詳細的測試架構可能會選擇隱藏不屬於這個類別的事件。有些格式化程式可能會選擇將這些傳送至 STDERR 而不是 STDOUT 以確保它們被看到。
預設為 False。這會在不應該由格式化程式顯示的事件上傳回 true。
如果事件在子測試中，這應具有子測試 ID。
如果事件是最後一個子測試事件，這應包含子測試 ID。
此物件使用 Test2::Util::ExternalMeta，這提供一致的方式讓您將 meta 資料附加到此類別的執行個體。這對工具、外掛程式和其他擴充套件很有用。
Test2 的原始碼存放庫可在 http://github.com/Test-More/test-more/ 找到。
版權所有 2020 Chad Granum <exodist@cpan.org>。
此程式是免費軟體；您可以在與 Perl 相同的條款下重新散佈或修改它。
請參閱 http://dev.perl.org/licenses/