內容

• 名稱
• 語法
• 說明
• 常見任務
  • 傳送事件
  • 變更或移除事件
  • 監聽事件
  • 測試後行為
  • 設定格式化器
• 方法
  • 狀態方法
• 第三方元資料
• 原始碼
• 維護人員
• 作者
• 版權

#名稱

Test2::Hub - 所有事件流經的管道。

#語法

use Test2::Hub;

my $hub = Test2::Hub->new();
$hub->send(...);

#說明

Hub 是處理所有事件並將其傳遞給格式化器的地方。Hub 也會追蹤測試狀態，並提供多個掛入事件管線的掛勾。

#常見任務

#傳送事件

$hub->send($event)

send() 方法用於向 Hub 發出事件。此方法會處理執行緒/分岔同步、篩選器、監聽器、TAP 輸出等。

#變更或移除事件

你可以使用 filter() 或 pre_filter()，視你的需求而定。兩者語法相同，因此這裡只顯示 filter()。

$hub->filter(sub {
    my ($hub, $event) = @_;

    my $action = get_action($event);

    # No action should be taken
    return $event if $action eq 'none';

    # You want your filter to remove the event
    return undef if $action eq 'delete';

    if ($action eq 'do_it') {
        my $new_event = copy_event($event);
        ... Change your copy of the event ...
        return $new_event;
    }

    die "Should not happen";
});

預設情況下，子 hub 繼承不到篩選器。這表示如果你啟動一個子測試，子測試不會繼承篩選器。你可以使用 inherit 參數變更此行為

$hub->filter(sub { ... }, inherit => 1);

#傾聽事件

$hub->listen(sub {
    my ($hub, $event, $number) = @_;

    ... do whatever you want with the event ...

    # return is ignored
});

預設情況下，子 hub 繼承不到監聽器。這表示如果你啟動一個子測試，子測試不會繼承監聽器。你可以使用 inherit 參數變更此行為

$hub->listen(sub { ... }, inherit => 1);

#測試後行為

$hub->follow_up(sub {
    my ($trace, $hub) = @_;

    ... do whatever you need to ...

    # Return is ignored
});

follow_up 子程序只會呼叫一次，在呼叫 done_testing 時，或在 END 區塊中。

#設定格式化器

預設情況下，會建立 Test2::Formatter::TAP 的執行個體並使用它。

my $old = $hub->format(My::Formatter->new);

設定格式化器會取代任何現有的格式化器。你可以將格式化器設定為 undef 以防止輸出。如果已設定一個格式化器，將會傳回舊的格式化器。一次只允許一個格式化器。

#方法

#$hub->send($event)

這是所有事件進入 hub 進行處理的地方。

#$hub->process($event)

這是由 send 在執行任何 IPC 處理後呼叫的。你可以使用它來繞過 IPC 程序，但一般來說你應該避免使用它。

#$old = $hub->format($formatter)

用一個新的執行個體取代現有的格式化器執行個體。格式化器必須是實作 $formatter->write($event) 方法的物件。

#$sub = $hub->listen(sub { ... }, %optional_params)

你可以在將所有事件傳送給格式化器之後使用它來記錄所有事件。在此處所做的任何變更都沒有意義，除了可能對其他監聽器有意義之外。

$hub->listen(sub {
    my ($hub, $event, $number) = @_;

    ... do whatever you want with the event ...

    # return is ignored
});

通常子 hub（例如子測試）不會繼承監聽器。你可以新增 inherit => 1 參數以允許繼承監聽器。

#$hub->unlisten($sub)

你可以使用它來移除監聽回呼。你必須傳入 listen() 方法傳回的代碼參考。

#$sub = $hub->filter(sub { ... }, %optional_params)

#$sub = $hub->pre_filter(sub { ... }, %optional_params)

這些可以用來新增篩選器。篩選器可以在任何其他東西看到事件之前修改、取代或移除事件。

$hub->filter(
    sub {
        my ($hub, $event) = @_;

        return $event;    # No Changes
        return;           # Remove the event

        # Or you can modify an event before returning it.
        $event->modify;
        return $event;
    }
);

如果您不使用執行緒、分岔或 IPC，則 filter 和 pre_filter 之間唯一的差異在於 pre_filter 子程式會先執行。當您使用執行緒、分岔或 IPC 時，預先篩選器會在事件傳送到其目的地程序/執行緒之前發生，一般篩選器只會在目的地中樞/執行緒中發生。

如果中樞是在其他程序或執行緒中建立的，則您無法將一般篩選器新增到中樞。您隨時都可以新增預先篩選器。

#$hub->unfilter($sub)

#$hub->pre_unfilter($sub)

這些可以用於移除篩選器和預先篩選器。$sub 參數是 filter() 或 pre_filter() 傳回的參考。

#$hub->follow_op(sub { ... })

使用這個新增在中樞完成之前呼叫的行為。您的程式區塊的唯一參數將是 Test2::EventFacet::Trace 執行個體。

$hub->follow_up(sub {
    my ($trace, $hub) = @_;

    ... do whatever you need to ...

    # Return is ignored
});

follow_up 子程式只會呼叫一次，在呼叫 done_testing 時，或在 END 區塊中。

#$sub = $hub->add_context_acquire(sub { ... });

新增一個回呼，每次有人嘗試取得內容時都會呼叫它。它會取得一個單一參數，一個用於建構內容的參數雜湊的參考。這是您透過直接變更雜湊來變更參數的機會。

test2_add_callback_context_acquire(sub {
    my $params = shift;
    $params->{level}++;
});

這是一個非常可怕的 API 函數。請不要在必要時使用它。這是為了 Test::Builder 和向後相容性而存在的。出於效能考量，這會讓您直接操作雜湊，而不是傳回新的雜湊。

注意 使用這個掛鉤可能會對效能造成極大的影響。

您提供的程式碼參考會被傳回，並可以在稍後用於移除掛鉤。

#$hub->remove_context_acquire($sub);

這可以用於移除內容取得掛鉤。

#$sub = $hub->add_context_init(sub { ... });

這讓您可以新增回呼，每次為中樞建立新的內容時都會觸發這些回呼。子程式唯一的參數將是建立的 Test2::API::Context 執行個體。

注意 使用這個掛鉤可能會對效能造成極大的影響。

您提供的程式碼參考會被傳回，並可以在稍後用於移除掛鉤。

#$hub->remove_context_init($sub);

這可以用來移除一個 context init hook。

#$sub = $hub->add_context_release(sub { ... });

這允許你加入 callback，當這個 hub 的 context 被釋放時就會觸發。sub 的唯一參數會是已釋放的 Test2::API::Context 執行個體。這些會以相反的順序執行。

注意 使用這個掛鉤可能會對效能造成極大的影響。

您提供的程式碼參考會被傳回，並可以在稍後用於移除掛鉤。

#$hub->remove_context_release($sub);

這可以用來移除一個 context release hook。

#$hub->cull()

清除任何 IPC 事件（並處理它們）。

#$pid = $hub->pid()

取得建立 hub 的 process id。

#$tid = $hub->tid()

取得建立 hub 的 thread id。

#$hud = $hub->hid()

取得 hub 的識別字串。

#$uuid = $hub->uuid()

如果啟用 UUID 標記（請參閱 Test2::API），則 hub 將有 UUID。

#$ipc = $hub->ipc()

取得 hub 使用的 IPC 物件。

#$hub->set_no_ending($bool)

#$bool = $hub->no_ending

這可以用來停用 hub 的自動結束行為。自動結束行為是由 end 區塊觸發的，用於清除 IPC 事件，並在 plan 為「NO PLAN」時輸出最終 plan。

#$bool = $hub->active

#$hub->set_active($bool)

這些用於取得/設定「active」屬性。當為 true 時，此屬性會強制 hub->finalize() 採取動作，即使沒有 plan，也沒有執行任何測試。此旗標對於加入後續行為的 plugin 很有用，即使沒有看到任何事件，這些後續行為也需要執行。

#狀態方法

#$hub->reset_state()

將所有狀態重設為開始狀態。這會將測試計數設為 0，清除 plan，移除失敗，等等。

#$num = $hub->count

取得已執行的測試數目。

#$num = $hub->failed

取得失敗次數（並非所有失敗都來自測試失敗，因此此數字可能大於計數）。

#$bool = $hub->ended

如果測試已結束，則為 True。這可能會傳回結束測試的工具堆疊框架，但並非保證。

#$bool = $hub->is_passing

#$hub->is_passing($bool)

檢查整體測試執行是否失敗。也可以用於設定通過/失敗狀態。

#$hub->plan($plan)

#$plan = $hub->plan

取得或設定計畫。計畫必須是大於 0 的整數、字串「NO PLAN」或字串「SKIP」。

#$bool = $hub->check_plan

檢查計畫和計數是否相符，但前提是測試已結束。如果測試尚未結束，這將傳回 undef，否則會傳回 true/false。

#第三方元資料

此物件使用 Test2::Util::ExternalMeta，它提供一致的方式讓您將元資料附加到此類別的執行個體。這對工具、外掛程式和其他擴充功能很有用。

#原始碼

Test2 的原始碼存放庫位於 http://github.com/Test-More/test-more/。

#維護人員

#Chad Granum <exodist@cpan.org>

#作者

#Chad Granum <exodist@cpan.org>

#版權

版權所有 2020 Chad Granum <exodist@cpan.org>。

此程式為自由軟體；您可以在與 Perl 相同的條款下重新散布或修改它。

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

Perldoc 瀏覽器由 Dan Book (DBOOK) 維護。如有任何關於網站本身、搜尋或文件呈現的問題，請透過 GitHub 問題追蹤器 或 電子郵件 聯絡他。

Perl 文件由 Perl 5 Porters 在 Perl 開發中維護。如有任何關於文件內容或格式的問題，請透過 Perl 問題追蹤器、郵件列表 或 IRC 聯絡他們。