目錄

• 名稱
• 說明
• 中斷事項
  • Test::Builder1.5/2 條件式
    • 問題
    • 修正
  • 取代 Test::Builder 單例
    • 問題
    • 修正
  • 直接存取雜湊元素
    • 問題
    • 修正
  • 子測試縮排
    • 問題
    • 修正
• 中斷或需要升級的發行版
  • 運作但測試會失敗
  • 建議升級
  • 需要升級
  • 仍然中斷
• 將斷言轉換為傳送事件
  • 舊版
  • TEST2
• 包裝現有工具
  • 舊版
  • TEST2
• 使用 UTF8
  • 舊版
  • TEST2
• 作者、貢獻者和審閱者
• 原始碼
• 維護者
• 版權

#名稱

Test2::Transition - 升級到 Test2 時的轉換注意事項

#說明

此處記載與 Test2 升級相關的陷阱和中斷事項。升級會導致 Test::Builder 在幕後轉用 Test2。此轉換大多是透明的，但有少數情況可能會造成問題。

#中斷事項

這是與新內部結構不符的場景清單。

#Test::Builder1.5/2 條件式

#問題

幾年前曾有兩次嘗試升級/取代 Test::Builder。令人困惑的是，它們分別稱為 Test::Builder2 和 Test::Builder1.5。許多人在其程式碼中加入條件式，以檢查 Test::Builder 版本號碼並相應調整其程式碼。

Test::Builder2/1.5 專案都已停擺。現在，人們加入的條件式程式碼已成為一個雷區。絕大多數被 Test2 中斷的模組都屬於此類別。

#修正

修正方法是移除所有與 Test::Builder1.5/2 相關的程式碼。請使用舊版的 Test::Builder API，或直接使用 Test2。

#取代 Test::Builder 單例

#問題

某些測試模組會用自己的執行個體或子類別取代 Test::Builder 單例執行個體。這通常是為了攔截或修改結果，因為它們會發生。

Test::Builder 單例現在是 Test2 周圍的簡單相容性包裝器。Test::Builder 單例不再是結果的集中存放處。許多結果完全繞過 Test::Builder 單例，這會中斷並在取代單例時預期的行為。

#修正

如果您只是想攔截所有結果，而不是讓它們傳送到 TAP，您應該查看 Test2::API 文件，並閱讀有關將新的集線器推送到集線器堆疊的資訊。暫時取代集線器現在是攔截結果的正確方法。

如果您的目標純粹是監控事件，請使用 Test::More 匯出的 Test2::Hub->listen() 方法來觀察事件觸發時的狀況。如果您希望在結果傳送到 TAP 之前修改結果，請查看 Test2::Hub->filter() 方法。

#直接存取雜湊元素

#問題

某些模組會直接查看 Test::Builder 單例上的雜湊金鑰。這裡的問題是 Test::Builder 單例不再包含任何重要資訊。

#修正

修正方法是使用 Test2::API 中指定的 API 來查看或修改所需的狀態。

#子測試縮排

#問題

早期變更（事實上，讓 Test2 成為一個想法的變更）是子測試註解的縮排變更。決定將子測試註解縮排，而不是與子測試同列，會更易於閱讀

# subtest foo
    ok 1 - blah
    1..1
ok 1 - subtest foo

舊式會縮排註解

    # subtest foo
    ok 1 - blah
    1..1
ok 1 - subtest foo

這會中斷測試，這些測試會比較 TAP 輸出的字串。

#修正

my $indent = $INC{'Test2/API.pm'} ? '' : '    ';

is(
    $subtest_output,
    "${indent}# subtest foo",
    "Got subtest note"
);

檢查 $INC{'Test2/API.pm'} 是否已設定，如果已設定，則不應預期縮排。如果未設定，則表示使用舊的 Test::Builder，應預期縮排。

#中斷或需要升級的套件

這是已知在升級時中斷的 CPAN 模組清單。

#運作正常，但測試會失敗

這些模組仍能正常運作，但其測試套件無法通過。如果您已安裝這些模組，則可以繼續使用。如果您在升級 Test::Builder 之後嘗試安裝這些模組，則需要強制安裝或略過中斷的測試。

#Test::DBIx::Class::Schema

這個模組有一個測試，似乎是為了解決 Test::Builder 的錯誤。Test2 似乎已修正此錯誤，這表示解決方法會導致失敗。這可以輕鬆更新，但目前尚未有人這麼做。

已知中斷的版本：1.0.9 及更舊版本

#Device::Chip

測試因子測試縮排而中斷。

已知中斷的版本為 0.07。不過，在 0.06 中似乎運作正常。已提交修補程式來修正此問題。

#建議升級

這些模組並未中斷，但其測試套件中斷，且已修正。

#Test::Exception

舊版本運作正常，但有輕微的測試名稱行為，會與 Test2 中斷。舊版本將不再安裝，因為這個原因。CPAN 上的最新版本將會正常安裝。不需要升級，但建議升級。

已在版本 0.43 中修正

#Data::Peek

有些測試依賴於 $! 和 $? 以微妙的方式修改。已套用修補程式來修正已變更的事項。

模組本身運作良好，無需升級。

已在版本中修復：0.45

#circular::require

某些測試很脆弱，需要在後期載入 base.pm。Test2 過早載入 base.pm。已更新測試以修復此問題。

模組本身從未中斷，您不需要升級。

已在版本中修復：0.12

#Test::Module::Used

測試解決了現已修復的規劃錯誤。如果您已安裝舊版本，則無需升級。如果您需要，新版本可以正常安裝。

已在版本中修復：0.2.5

#Test::Moose::More

某些測試很脆弱，但已修復。實際中斷來自子測試註解縮排變更。

無需升級，舊版本運作良好。只有新版本會安裝。

已在版本中修復：0.025

#Test::FITesque

這是由如何執行規劃的錯誤修復中斷的。錯誤修復後已更新測試。

已在版本中修復：0.04

#Test::Kit

舊版本運作良好，但不會安裝，因為Test::Aggregate在相依性鏈中。不應需要升級。

已在版本中修復：2.15

#autouse

測試中斷，因為它依賴於未載入 Scalar::Util。Test2 載入 Scalar::Util。已更新測試，以便在檢查 Scalar::Util 的載入狀態後載入 Test2。

如果您已安裝，則無需升級。

已在版本中修復：1.11

#需要升級

#Test::SharedFork

舊版本需要直接存取 Test::Builder 單例雜湊元素。CPAN 上的最新版本仍會在舊 Test::Builder 上執行此操作，但會在 Test2 上推遲到Test2::IPC。

已在版本中修復：0.35

#Test::Builder::Clutch

這透過覆寫單例上的方法，以及直接存取單例上的雜湊值來運作。已發布新版本，它使用 Test2 API 以更明智的方式達成相同的結果。

已在版本中修復：0.07

#Test::Dist::VersionSync

這具有 Test::Builder2 條件。已透過移除條件來修復此問題。

已在版本中修正：1.1.4

#Test::Modern

此依賴於 Test::Builder->_try()，這是一個私人方法，文件記載為不應使用。已透過使用不同的工具修正此問題。

已在版本中修正：0.012

#Test::UseAllModules

版本 0.14 依賴於 Test::Builder->history，這在 Test::Builder 1.5 中可用。版本 0.12 和 0.13 依賴於其他 Test::Builder 內部元件。

已在版本中修正：0.15

#Test::More::Prefix

透過套用包裝 Test::Builder->_print_comment 的角色來運作。已透過新增事件篩選器修正，在 Test2 下執行時，此篩選器會修改訊息。

已在版本中修正：0.007

#仍有問題

#Test::Aggregate

此配發會直接存取 Test::Builder 單例中的雜湊鍵。它也從錯誤的角度切入問題，請考慮使用 Test2::Aggregate 以獲得類似功能，以及 Test2::Harness，它允許在測試架構層級預先載入模組。

截至版本仍有問題：0.373

#Test::Wrapper

此模組直接使用 Test::Builder 單例中的雜湊鍵。此模組也已過時，因為 Test2 有其好處。請使用 Test2::API 中的 intercept() 來達成類似的結果。

截至版本仍有問題：0.3.0

#Test::ParallelSubtest

此模組會覆寫 Test::Builder::subtest() 和 Test::Builder::done_testing()。它也會直接存取單例的雜湊元素。它尚未修正。

替代方案：Test2::AsyncSubtest 和 Test2::Workflow（不穩定）。

截至版本仍有問題：0.05

#Test::Pretty

請參閱 https://github.com/tokuhirom/Test-Pretty/issues/25

作者承認這個模組很瘋狂，他正在等待一個新的穩定版本 (Test2) 來以一種健全的方式完全重寫它。

截至版本：0.32 仍然損壞

#Net::BitTorrent

這個模組的測試直接存取 Test::Builder 的雜湊金鑰。大多數（如果不是全部）這些雜湊金鑰都有公開的 API 方法，可以用來避免這個問題。

截至版本：0.052 仍然損壞

#Test::Group

它在 Test::Builder 上進行猴子修補，並在程式碼中稱之為「黑魔法」。

截至版本：0.20 仍然損壞

#Test::Flatten

這以許多方式修改 Test::Builder 的內部結構。達成這個模組目標的更好方法是撰寫你自己的子測試函式。

截至版本：0.11 仍然損壞

#Log::Dispatch::Config::TestLog

修改 Test::Builder 的內部結構。

截至版本：0.02 仍然損壞

#Test::Able

修改 Test::Builder 的內部結構。

截至版本：0.11 仍然損壞

#MAKE ASSERTIONS -> SEND EVENTS

#LEGACY

use Test::Builder;

# A majority of tools out there do this:
# my $TB = Test::Builder->new;
# This works, but has always been wrong, forcing Test::Builder to implement
# subtests as a horrific hack. It also causes problems for tools that try
# to replace the singleton (also discouraged).

sub my_ok($;$) {
    my ($bool, $name) = @_;
    my $TB = Test::Builder->new;
    $TB->ok($bool, $name);
}

sub my_diag($) {
    my ($msg) = @_;
    my $TB = Test::Builder->new;
    $TB->diag($msg);
}

#TEST2

use Test2::API qw/context/;

sub my_ok($;$) {
    my ($bool, $name) = @_;
    my $ctx = context();
    $ctx->ok($bool, $name);
    $ctx->release;
}

sub my_diag($) {
    my ($msg) = @_;
    my $ctx = context();
    $ctx->diag($msg);
    $ctx->release;
}

context 物件有下列方法的 API 相容實作

#ok($bool, $name)

#diag(@messages)

#note(@messages)

#subtest($name, $code)

如果你正在尋找具有 is、like 等助手的程式，請參閱 Test2::Suite。

#WRAP EXISTING TOOLS

#LEGACY

use Test::More;

sub exclusive_ok {
    my ($bool1, $bool2, $name) = @_;

    # Ensure errors are reported 1 level higher
    local $Test::Builder::Level = $Test::Builder::Level + 1;

    $ok = $bool1 || $bool2;
    $ok &&= !($bool1 && $bool2);
    ok($ok, $name);

    return $bool;
}

從這個工具到 ok，到任何 ok 呼叫的鏈中每個單一工具都需要遞增 $Level 變數。當發生錯誤時，Test::Builder 將會追蹤到由 $Level 確定的堆疊框架，並報告該檔案和行號為發生錯誤的地方。如果你或你使用的任何其他工具忘記設定 $Level，則錯誤將會報告到錯誤的地方。

#TEST2

use Test::More;

sub exclusive_ok {
    my ($bool1, $bool2, $name) = @_;

    # Grab and store the context, even if you do not need to use it
    # directly.
    my $ctx = context();

    $ok = $bool1 || $bool2;
    $ok &&= !($bool1 && $bool2);
    ok($ok, $name);

    $ctx->release;
    return $bool;
}

Test2 使用一個 context 物件，而不是使用 $Level 來執行回溯。在此範例中，您建立一個 context 物件並儲存它。這會鎖定 context（錯誤報告比此處高 1 個層級），供所有包裝的工具尋找。您不需要使用 context 物件，但您需要將它儲存在一個變數中。一旦子程式結束，$ctx 變數就會被銷毀，這讓未來的工具可以找到它們自己的變數。

#使用 UTF8

#舊版

# Set the mode BEFORE anything loads Test::Builder
use open ':std', ':encoding(utf8)';
use Test::More;

或

# Modify the filehandles
my $builder = Test::More->builder;
binmode $builder->output,         ":encoding(utf8)";
binmode $builder->failure_output, ":encoding(utf8)";
binmode $builder->todo_output,    ":encoding(utf8)";

#TEST2

use Test2::API qw/test2_stack/;

test2_stack->top->format->encoding('utf8');

儘管更好的方法是使用 Test2::Plugin::UTF8 外掛程式，它是 Test2::Suite 的一部分。

#作者、貢獻者和審閱者

以下人員都以某種方式為此文件做出貢獻，即使只是審閱。

#Chad Granum (EXODIST) <exodist@cpan.org>

#原始碼

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

#維護者

#Chad Granum <exodist@cpan.org>

#版權

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

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

請參閱 http://www.perl.com/perl/misc/Artistic.html

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

Perl 文件由 Perl 5 Porters 在 Perl 開發中維護。請透過 Perl 問題追蹤器、郵件清單 或 IRC 聯絡他們，以回報與文件內容或格式相關的任何問題。