TAP::Harness

(原始碼, CPAN)

版本 3.44

#名稱

TAP::Harness - 使用統計資料執行測試腳本

#版本

版本 3.44

#說明

這是一個簡單的測試套件，允許執行測試，並自動彙總結果並輸出到 STDOUT。

#語法

use TAP::Harness;
my $harness = TAP::Harness->new( \%args );
$harness->runtests(@tests);

#方法

#類別方法

#`new`

my %args = (
   verbosity => 1,
   lib     => [ 'lib', 'blib/lib', 'blib/arch' ],
)
my $harness = TAP::Harness->new( \%args );

建構函式會傳回一個新的 TAP::Harness 物件。它接受一個選用的雜湊，其允許的鍵為

詳細程度

設定詳細程度等級

 1   verbose        Print individual test results to STDOUT.
 0   normal
-1   quiet          Suppress some test output (mostly failures 
                    while tests are running).
-2   really quiet   Suppress everything but the tests summary.
-3   silent         Suppress everything.

計時器

將每個測試的執行時間附加到輸出。如果可用，會使用 Time::HiRes。
失敗

顯示測試失敗（如果選取 詳細，這是一個空操作）。
註解

顯示測試註解（如果選取 詳細，這是一個空操作）。
顯示計數

在測試期間更新執行中測試的計數。
正規化

設定為 true 值，以正規化在詳細模式中發出的 TAP。
函式庫

接受一個純量值或純量值的陣列參考，指出如果執行 Perl 測試，應包含哪些路徑到允許的函式庫。當然，這僅在 Perl 編寫的測試的背景下才有意義。
切換

接受一個純量值或純量值的陣列參考，指出如果執行 Perl 測試，應包含哪些切換。當然，這僅在 Perl 編寫的測試的背景下才有意義。
測試參數

傳遞給每個測試程式的一個 @INC 風格參數陣列的參考。
```
test_args => ['foo', 'bar'],
```
如果您想傳遞不同的參數給每個測試，則應傳遞一個陣列雜湊，其鍵為每個測試的別名
```
test_args => {
  my_test    => ['foo', 'bar'],
  other_test => ['baz'],
}
```
顏色

嘗試產生彩色輸出。
執行

通常，Perl 測試會透過此執行。不過，任何吐出 TAP 的內容都可以。您可以使用這個參數來指定執行測試的程式名稱（和選用的切換）
```
exec => ['/usr/bin/ruby', '-w']
```
您也可以傳遞一個子常式參考，以根據給定的測試指令碼來確定和傳回要執行的適當程式。子常式參考應將 TAP::Harness 物件本身作為第一個參數，並將檔案名稱作為第二個參數。它應傳回包含要執行的命令並包含測試檔案名稱的陣列參考。它也可以只傳回 undef，在這種情況下，TAP::Harness 會退回到在 Perl 中執行測試指令碼
```
exec => sub {
    my ( $harness, $test_file ) = @_;

    # Let Perl tests run.
    return undef if $test_file =~ /[.]t$/;
    return [ qw( /usr/bin/ruby -w ), $test_file ]
      if $test_file =~ /[.]rb$/;
  }
```
如果子常式傳回一個包含換行符或檔案控制代碼的純量，它將分別被解釋為原始 TAP 或 TAP 串流。
合併

如果 合併 為 true，則 Harness 會建立解析器，將 STDOUT 和 STDERR 合併到它們啟動的任何程序中。
來源

3.18 的新增功能.

如果設定，來源 必須是一個雜湊，包含要載入和/或設定的 TAP::Parser::SourceHandler 的名稱。這些值是一個設定雜湊，可透過 TAP::Parser::Source 中的 "config_for" 供來源處理程式存取。

例如
```
sources => {
  Perl => { exec => '/path/to/custom/perl' },
  File => { extensions => [ '.tap', '.txt' ] },
  MyCustom => { some => 'config' },
}
```
來源 參數會影響 來源、tap 和 執行 參數的處理方式。

有關更多詳細資料，請參閱 TAP::Parser 中的「new」、TAP::Parser::Source 和 TAP::Parser::IteratorFactory 中的 sources 參數。
aggregator_class

用於彙總測試結果的類別名稱。預設為 TAP::Parser::Aggregator。
version

3.22 新增.

假設這是 TAP::Parser 的 TAP 版本，而不是預設的 TAP 版本 12。
formatter_class

用於格式化輸出的類別名稱。預設為 TAP::Formatter::Console，如果輸出不是 TTY，則為 TAP::Formatter::File。
multiplexer_class

在平行測試期間用於多工測試的類別名稱。預設為 TAP::Parser::Multiplexer。
parser_class

用於解析 TAP 的類別名稱。預設為 TAP::Parser。
scheduler_class

用於排程測試執行的類別名稱。預設為 TAP::Parser::Scheduler。
formatter

如果設定，formatter 必須是能夠格式化 TAP 輸出的物件。請參閱 TAP::Formatter::Console 以取得範例。
errors

如果在 TAP 輸出中找到解析錯誤，摘要報告中會註明這一點。若要查看所有解析錯誤，請將此參數設定為 true
```
errors => 1
```
directives

如果設定為 true 值，則只會顯示具有指令的測試結果。這會覆寫其他設定，例如 verbose 或 failures。
ignore_exit

如果設定為 true 值，指示 TAP::Parser 忽略測試指令碼的結束和等待狀態。
jobs

任何時候執行的平行測試的最大數量。哪些測試可以平行執行是由 rules 控制的。預設一次只執行一個測試。

rules

控制哪些測試可以在平行中執行的規則雜湊的參考。如果未宣告任何規則且 CPAN::Meta::YAML 可用，TAP::Harness 會嘗試從 rulesfile 參數指定的 YAML 檔案載入規則。如果沒有規則檔案，預設所有測試都有資格平行執行。

以下是幾個簡單的範例。有關資料結構和相關的 glob 式樣模式比對的完整詳細資料，請參閱 TAP::Parser::Scheduler 中的「規則資料結構」。

# Run all tests in sequence, except those starting with "p"
$harness->rules({
    par => 't/p*.t'
});

# Equivalent YAML file
---
par: t/p*.t

# Run all tests in parallel, except those starting with "p"
$harness->rules({
    seq => [
              { seq => 't/p*.t' },
              { par => '**'     },
           ],
});

# Equivalent YAML file
---
seq:
    - seq: t/p*.t
    - par: **

# Run some  startup tests in sequence, then some parallel tests than some
# teardown tests in sequence.
$harness->rules({
    seq => [
        { seq => 't/startup/*.t' },
        { par => ['t/a/*.t','t/b/*.t','t/c/*.t'], }
        { seq => 't/shutdown/*.t' },
    ],

});

# Equivalent YAML file
---
seq:
    - seq: t/startup/*.t
    - par:
        - t/a/*.t
        - t/b/*.t
        - t/c/*.t
    - seq: t/shutdown/*.t

這是一個實驗性功能，介面可能會變更。

rulesfiles

這指定要在哪裡尋找測試排程規則的 YAML 檔案。如果未提供，它會尋找預設檔案來使用。它會先檢查在 HARNESS_RULESFILE 環境變數中提供的檔案，然後檢查 testrules.yml，再檢查 t/testrules.yml。
stdout

用於擷取標準輸出的檔案處理器。
trap

如果執行因 SIGINT (Ctrl-C) 中斷，嘗試列印摘要資訊。

值為 undef 的任何金鑰都將被忽略。

#實例方法

#`runtests`

$harness->runtests(@tests);

接受要執行的 @tests 陣列。這通常應該是測試檔案的名稱，但並非必要。@tests 中的每個元素都會作為 source 傳遞給 TAP::Parser::new()。請參閱 TAP::Parser 以取得更多資訊。

可以提供別名，這些別名將顯示在測試名稱的位置，方法是將測試提供為包含 [ $test, $alias ] 的陣列的參考。

$harness->runtests( [ 't/foo.t', 'Foo Once' ],
                    [ 't/foo.t', 'Foo Twice' ] );

通常，嘗試執行相同的測試兩次會產生錯誤。別名允許您透過為每次執行的測試提供唯一名稱來克服此限制。

測試將按找到的順序執行。

如果已定義環境變數 PERL_TEST_HARNESS_DUMP_TAP，它應該命名一個目錄，每個測試的原始 TAP 副本都將寫入其中。TAP 會寫入以每個測試命名的檔案。會視需要建立子目錄。

傳回包含測試結果的 TAP::Parser::Aggregator。

#`summary`

$harness->summary( $aggregator );

輸出 TAP::Parser::Aggregator 的摘要。

#`aggregate_tests`

$harness->aggregate_tests( $aggregate, @tests );

執行已命名的測試並顯示結果摘要。測試將按找到的順序執行。

測試結果會新增到提供的 TAP::Parser::Aggregator。可以多次呼叫 aggregate_tests 來執行多組測試。可以使用多個 Test::Harness 實例將結果傳遞給單一匯總器，以便可以使用不同的 TAP::Harness 設定執行複雜測試套件的不同部分。例如，在某些測試應該並行執行，而其他測試不適合並行執行的案例中，這會很有用。

my $formatter   = TAP::Formatter::Console->new;
my $ser_harness = TAP::Harness->new( { formatter => $formatter } );
my $par_harness = TAP::Harness->new(
    {   formatter => $formatter,
        jobs      => 9
    }
);
my $aggregator = TAP::Parser::Aggregator->new;

$aggregator->start();
$ser_harness->aggregate_tests( $aggregator, @ser_tests );
$par_harness->aggregate_tests( $aggregator, @par_tests );
$aggregator->stop();
$formatter->summary($aggregator);

請注意，對於較簡單的測試需求，通常可以將上述程式碼替換為單一呼叫 runtests。

@tests 陣列的每個元素為

要執行的測試的來源名稱
[ 來源名稱、顯示名稱 ] 陣列的參考

對於 perl 測試套件，通常「來源名稱」只是要執行的測試腳本的檔案名稱。

當您提供一個獨立的顯示名稱時，就可以執行一個測試超過一次；顯示名稱實際上是測試在測試架構中所知的別名。如果每次呼叫使用不同的名稱，測試架構不會在意是否執行相同的測試超過一次。

#`make_scheduler`

當測試架構需要建立 TAP::Parser::Scheduler 時呼叫。在子類別中覆寫以提供替代的排程器。make_scheduler 傳遞傳遞給 aggregate_tests 的測試清單。

#`jobs`

取得或設定測試架構處理的並行測試執行次數。預設值為 1 -- 對於平行測試，應設定為較高的值。

#`make_parser`

建立新的剖析器和顯示格式化器工作階段。通常在子類別中使用和/或覆寫。

my ( $parser, $session ) = $harness->make_parser;

#`finish_parser`

終止使用剖析器。通常在子類別中使用和/或覆寫。剖析器不會因為這樣而被銷毀。

#設定

TAP::Harness 設計成容易設定。

#外掛程式

TAP::Parser 外掛程式讓您可以變更 TAP 輸入和輸出到剖析器的方式。

TAP::Parser::SourceHandler 處理 TAP 輸入。您可以設定它們並使用 sources 參數載入自訂處理常式至 "new"。

TAP::Formatter 處理 TAP 輸出。您可以使用 formatter_class 參數載入自訂格式化器至 "new"。若要設定格式化器，您目前需要在 TAP::Harness 外部建立它，並使用 formatter 參數傳遞給 "new"。未來可能會透過新增 formatters 參數至 "new" 來解決這個問題。

#`Module::Build`

Module::Build 版本 0.30 支援 TAP::Harness。

若要載入 TAP::Harness 外掛程式，您需要使用 new 的 tap_harness_args 參數，通常從您的 Build.PL。例如

Module::Build->new(
    module_name        => 'MyApp',
    test_file_exts     => [qw(.t .tap .txt)],
    use_tap_harness    => 1,
    tap_harness_args   => {
        sources => {
            MyCustom => {},
            File => {
                extensions => ['.tap', '.txt'],
            },
        },
        formatter_class => 'TAP::Formatter::HTML',
    },
    build_requires     => {
        'Module::Build' => '0.30',
        'TAP::Harness'  => '3.18',
    },
)->create_build_script;

請參閱 "new"

#`ExtUtils::MakeMaker`

ExtUtils::MakeMaker 不支援 TAP::Harness 開箱即用。

#`prove`

prove 支援 TAP::Harness 外掛程式，並有自己的外掛程式系統。請參閱 prove 中的「FORMATTERS」、prove 中的「SOURCE HANDLERS」和 App::Prove 以取得更多詳細資訊。

#撰寫外掛程式

如果您無法設定 TAP::Harness 來執行您想要的操作，而且您找不到現有的外掛程式，請考慮撰寫一個。

TAP::Harness 支援的外掛程式有兩個主要使用案例：輸入和輸出

#自訂 TAP 如何進入剖析器

為此，您可以延伸現有的 TAP::Parser::SourceHandler，或撰寫您自己的。這是一個相當簡單的 API，而且它們可以使用 "new" 的 sources 參數來載入和設定。

#自訂 TAP 結果如何從剖析器輸出

為此，您可以延伸現有的 TAP::Formatter，或撰寫您自己的。撰寫格式化器比撰寫 SourceHandler 稍微複雜一些，因為您需要了解 TAP::Parser API。了解 "aggregate_tests" 如何運作是一個很好的起點。

自訂格式化器可以使用 "new" 的 formatter_class 參數來載入和設定。

#子類化

如果您無法設定 TAP::Harness 來執行您想要的操作，而且撰寫外掛程式不是一個選項，請考慮延伸它。它被設計為（大多數）易於子類化，儘管需要子類化的情況應該很少見。

#方法

如果您想要子類化 TAP::Harness，以下方法是您可能想要覆寫的方法。

#"new"
#「runtests」
#「summary」

#取代

如果您喜歡 prove 實用程式和 TAP::Parser，但您想要自己的套件，您只需要撰寫一個並提供 new 和 runtests 方法。然後您可以這樣使用 prove 實用程式

prove --harness My::Test::Harness

請注意，雖然 prove 接受測試清單（或要測試的事項），但 new 有一組相當豐富的引數。您可能想要仔細閱讀此程式碼，以了解如何使用所有這些引數。

#另請參閱

Test::Harness

目錄

#名稱

#版本

#說明

#語法

#方法

#類別方法

#new

#實例方法

#runtests

#summary

#aggregate_tests

#make_scheduler

#jobs

#make_parser

#finish_parser

#設定