名前¶

Test::More - テストを書くためのもう一つのフレームワーク

概要¶

  use Test::More tests => 23;
  # or
  use Test::More skip_all => $reason;
  # or
  use Test::More;   # see done_testing()

  require_ok( 'Some::Module' );

  # Various ways to say "ok"
  ok($got eq $expected, $test_name);

  # 「ok」と示すためのさまざまな方法
  ok($got eq $expected, $test_name);

  is  ($got, $expected, $test_name);
  isnt($got, $expected, $test_name);

  # Rather than print STDERR "# here's what went wrong\n"
  diag("here's what went wrong");

  # print STDERR "# here's what went wrong\n" とするよりも
  diag("here's what went wrong");

  like  ($got, qr/expected/, $test_name);
  unlike($got, qr/expected/, $test_name);

  cmp_ok($got, '==', $expected, $test_name);

  is_deeply($got_complex_structure, $expected_complex_structure, $test_name);

  SKIP: {
      skip $why, $how_many unless $have_some_feature;

      ok( foo(),       $test_name );
      is( foo(42), 23, $test_name );
  };

  TODO: {
      local $TODO = $why;

      ok( foo(),       $test_name );
      is( foo(42), 23, $test_name );
  };

  can_ok($module, @methods);
  isa_ok($object, $class);

  pass($test_name);
  fail($test_name);

  BAIL_OUT($why);

  # UNIMPLEMENTED!!!
  my @status = Test::More::status;

説明¶

待った! もし、今初めて、テストを書こうとしているのなら、Test::Simple をまず 見てください。 これは、一旦基本的なテストのコツを得れば、置き換え可能な Test::Simple の差込式の置換物です。

このモジュールの目的は、幅広いテストユーティリティを提供することです。 よりよい診断で「ok」と示す方法を用意したり、テストを簡単にスキップしたり、 将来的な実装をテストしたり、複雑なデータ構造を比較したりする様々な機能が あります。 単純な ok() 関数でほとんど全てのことが出来ますが、ok() 関数は、良い 診断出力を提供しません。

計画が一緒に来るなら、それを大事にする¶

他の何より前に、テストの計画が必要です。 スクリプトが行おうとしているテストがいくつであるかというこの基本的な宣言は、 時期尚早な失敗に対する保護になります。

この保護を行う好ましい方法は、use Test::More を書く時に、計画を 宣言することです。

  use Test::More tests => 23;

スクリプトが行おうとしているテストがいくつあるかを事前に知らないような、まれな ケースがあります。 こういうケースでは、最後にテストを宣言することができます。

  use Test::More;

  ... run your tests ...

  done_testing( $number_of_tests_run );

いくつのテストが実行されるか本当に分からない時や、計算するのが大変な時に 使えます。 そのようなケースでは、$number_of_tests_run を省くこともできます。

いくつかのケースでは、あるテストスクリプト全てを完全にスキップしたいでしょう。

  use Test::More skip_all => $skip_reason;

スクリプトが、なぜスキップするのかの理由を宣言すると、即座に0(成功)で 終了します。 詳細については Test::Harness を参照してください。

Test::More がエクスポートする関数をコントロールしたければ、 'import' オプションを使う必要があります。 たとえば、'fail' を除いて、全てをインポートしたいなら、次のようにします：

  use Test::More tests => 23, import => ['!fail'];

代わりに、plan() 関数を使えます。 テストの数を計算する必要があるときに有用です。

  use Test::More;
  plan tests => keys %Stuff * 3;

または、テストを走らせている間に決めるためには：

  use Test::More;
  if( $^O eq 'MacOS' ) {
      plan skip_all => 'Test irrelevant on MacOS';
  }
  else {
      plan tests => 42;
  }

done_testing

    done_testing();
    done_testing($number_of_tests);

If you don't know how many tests you're going to run, you can issue the plan when you're done running tests.

実行しようとしているテストがいくつかわからない場合、 テストの実行を終えたときに計画を発表することができます。

$number_of_tests is the same as plan(), it's the number of tests you expected to run. You can omit this, in which case the number of tests you ran doesn't matter, just the fact that your tests ran to conclusion.

$number_of_tests は、plan() と同じです; 実行しようとしているテストの数です。 これを省略することもできます; その場合、テストの数は問題にしません; 最後までテストが実行されたかだけを問題にします。

This is safer than and replaces the "no_plan" plan.

これは "no_plan" な計画より安全で、"no_plan" を置き換えるものです。

テストの名前¶

便宜のために、それぞれのテストは、順番に番号が割り振られています。 これは、主に自動的に行われます。 ですが、テストに名前を割り当てると、とても有益なことがよくあります。 どちらがよいでしょうか:

  ok 4
  not ok 5
  ok 6

あるいは:

  ok 4 - basic multi-variable
  not ok 5 - simple exponential
  ok 6 - force == mass * acceleration

後者は、何が失敗したかの手がかりを与えてくれます。 また、単に "simple exponential" を探すことで、 スクリプト中のテストを見つけやすくなります。

全てのテストの関数は、名前を引数にとります。 これはオプションではありますが、使うことが強く推奨されています。

わたしは、OK 、あなたは、だめ¶

このモジュールの基本的な目的は、与えたテストが、成功したか、失敗したかで、 「ok 番号」か、「not ok 番号」のどちらかを出力することです。 他の全ては、ただのおまけです。

この下に書いているものは全て、テストが成功したか失敗したかどうかによって、 「ok」か「not ok」を表示します。 それら全てはまた、それぞれ真か偽を返します。

ok

  ok($got eq $expected, $test_name);

This simply evaluates any expression ($got eq $expected is just a simple example) and uses that to determine if the test succeeded or failed. A true expression passes, a false one fails. Very simple.

これは単純に、どんな式も評価します($got eq $expected は ただの簡単な例です); そして、それをテストが成功したかどうかを決めるのに使います。 真の式は合格し、偽の式は失敗です。 とても単純です。

For example:

例えば:

    ok( $exp{9} == 81,                   'simple exponential' );
    ok( Film->can('db_Main'),            'set_db()' );
    ok( $p->tests == 4,                  'saw tests' );
    ok( !grep(!defined $_, @items),      'all items defined' );

(Mnemonic: "This is ok.")

(覚えかた: "This is ok.")

$test_name is a very short description of the test that will be printed out. It makes it very easy to find a test in your script when it fails and gives others an idea of your intentions. $test_name is optional, but we very strongly encourage its use.

$test_name は、実行時に出力される、とても短いテストの説明です。 これは、テストが失敗した場合に、スクリプト中のテストをとても 見つけやすくします; そして、他の人に、あなたの意図する考えを伝えます。 $test_name はオプションですが、使うことが とても 強く勧められています。

Should an ok() fail, it will produce some diagnostics:

万一、ok() が失敗した場合、ちょっとした診断を提供します:

    not ok 18 - sufficient mucus
    #   Failed test 'sufficient mucus'
    #   in foo.t at line 42.

This is the same as Test::Simple's ok() routine.

これは、Test::Simple の ok() ルーチンと同じです。

is

isnt

  is  ( $got, $expected, $test_name );
  isnt( $got, $expected, $test_name );

Similar to ok(), is() and isnt() compare their two arguments with eq and ne respectively and use the result of that to determine if the test succeeded or failed. So these:

ok() と is() と isnt() の類似点は、二つの引数をそれぞれ eq と ne で 比較し、その結果を使って、テストが成功したか、失敗したかを決めることです。 それで、これらは：

    # Is the ultimate answer 42?
    is( ultimate_answer(), 42,          "Meaning of Life" );

    # $foo isn't empty
    isnt( $foo, '',     "Got some foo" );

are similar to these:

次と似ています:

    ok( ultimate_answer() eq 42,        "Meaning of Life" );
    ok( $foo ne '',     "Got some foo" );

undef will only ever match undef. So you can test a value against undef like this:

undef は undef にのみマッチングします。 undef に対して値をテストしたければ、次のようにします:

    is($not_defined, undef, "undefined as expected");

(Mnemonic: "This is that." "This isn't that.")

(覚えかた: "This is that." "This isn't that.")

So why use these? They produce better diagnostics on failure. ok() cannot know what you are testing for (beyond the name), but is() and isnt() know what the test was and why it failed. For example this test:

どうしてこれらを使うのでしょう？ is() と isnt() は、失敗に関して、よりよい診断をだします。 ok() は、(名前以上には)何のためにテストをしているのか知ることが出来ませんが、 is() と isnt() は、テストが何で、テストがなぜ失敗したかを知っています。 たとえばこのテストは:

    my $foo = 'waffle';  my $bar = 'yarblokos';
    is( $foo, $bar,   'Is foo the same as bar?' );

Will produce something like this:

このようなものを出力します:

    not ok 17 - Is foo the same as bar?
    #   Failed test 'Is foo the same as bar?'
    #   in foo.t at line 139.
    #          got: 'waffle'
    #     expected: 'yarblokos'

So you can figure out what went wrong without rerunning the test.

これで、テストを再度走らせることなしに何が間違ったのか、判断できます。

You are encouraged to use is() and isnt() over ok() where possible, however do not be tempted to use them to find out if something is true or false!

可能なら、is() と isnt() を ok() の代わりに使うことを勧めます。 ですが、何かが、真であるか偽であるかを見つけ出すために、 is() と isnt() を使おうとしてはいけません!

  # XXX BAD!
  is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );

This does not check if exists $brooklyn{tree} is true, it checks if it returns 1. Very different. Similar caveats exist for false and 0. In these cases, use ok().

このコードは、exists $brooklyn{tree} が真であるかどうかを チェックしません。 このコードは、1 を返すかどうかをチェックします。これらはまったく違います。 似たような警告は、偽 と 0 にもあります。こういうケースでは、ok() を 使います。

  ok( exists $brooklyn{tree},    'A tree grows in Brooklyn' );

A simple call to isnt() usually does not provide a strong test but there are cases when you cannot say much more about a value than that it is different from some other value:

単純に isnt() を呼び出すのは、普通、強いテストを提供しませんが、 ある値について、ある特定の値と異なっているということ以上を 言えないような時に適しています:

  new_ok $obj, "Foo";

  my $clone = $obj->clone;
  isa_ok $obj, "Foo", "Foo->clone";

  isnt $obj, $clone, "clone() produces a different object";

For those grammatical pedants out there, there's an isn't() function which is an alias of isnt().

文法学者ぶる人のために書いておくと、 isnt() 関数の別名として isn't() 関数があります。

like

  like( $got, qr/expected/, $test_name );

Similar to ok(), like() matches $got against the regex qr/expected/.

ok() と似ていますが、like() は、 引数の $got を正規表現の qr/expected/ にマッチングさせます。

So this:

従ってこれは:

    like($got, qr/expected/, 'this is like that');

is similar to:

次と似ています:

    ok( $got =~ m/expected/, 'this is like that');

(Mnemonic "This is like that".)

(覚えかた "This is like that".)

The second argument is a regular expression. It may be given as a regex reference (i.e. qr//) or (for better compatibility with older perls) as a string that looks like a regex (alternative delimiters are currently not supported):

2 番目の引数は正規表現です。正規表現リファレンス (つまり qr//) や、(古い Perl とより互換性を持たせるなら) 正規表現に見える文字列(代替の区切りは現在対応していません)として 与えられます。

    like( $got, '/expected/', 'this is like that' );

Regex options may be placed on the end ('/expected/i').

正規表現のオプションは末尾に置かれます ('/expected/i')。

Its advantages over ok() are similar to that of is() and isnt(). Better diagnostics on failure.

ok() と比べたときの利点は、is() と isnt() の利点に似ています。 失敗に関して、よりよく診断します。

unlike

  unlike( $got, qr/expected/, $test_name );

Works exactly as like(), only it checks if $got does not match the given pattern.

like() のように働きますが、 $got が与えたパターンに ッチング しない ことだけをチェックします。

cmp_ok

  cmp_ok( $got, $op, $expected, $test_name );

Halfway between ok() and is() lies cmp_ok(). This allows you to compare two arguments using any binary perl operator. The test passes if the comparison is true and fails otherwise.

ok() と is() の中間に cmp_ok() があります。 これは、すべての二項の Perl の演算子を使って、二つの引数を 比較できるようにします。 比較が真ならテストは成功し、さもなければ失敗します。

    # ok( $got eq $expected );
    cmp_ok( $got, 'eq', $expected, 'this eq that' );

    # ok( $got == $expected );
    cmp_ok( $got, '==', $expected, 'this == that' );

    # ok( $got && $expected );
    cmp_ok( $got, '&&', $expected, 'this && that' );
    ...etc...

Its advantage over ok() is when the test fails you'll know what $got and $expected were:

ok() と比べたときの利点は、テストが失敗したときに、 $got と $expected が何かがわかることです。

    not ok 1
    #   Failed test in foo.t at line 12.
    #     '23'
    #         &&
    #     undef

It's also useful in those cases where you are comparing numbers and is()'s use of eq will interfere:

また、数を比較する際や、is() を eq として使うことが、干渉する際に、 有益でしょう:

    cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );

It's especially useful when comparing greater-than or smaller-than relation between values:

二つの値の大小の比較に使うと、非常に便利です:

    cmp_ok( $some_value, '<=', $upper_limit );

can_ok

  can_ok($module, @methods);
  can_ok($object, @methods);

Checks to make sure the $module or $object can do these @methods (works with functions, too).

$module または $object がメソッド(または関数) @methods を実行できるかを チェックします。

    can_ok('Foo', qw(this that whatever));

is almost exactly like saying:

この表現は、ほぼ正確に次のような意味です:

    ok( Foo->can('this') && 
        Foo->can('that') && 
        Foo->can('whatever') 
      );

only without all the typing and with a better interface. Handy for quickly testing an interface.

すべてをタイプしなくていい、よりよいインターフェースです。 素早いテストのための、手ごろなインターフェースです。

No matter how many @methods you check, a single can_ok() call counts as one test. If you desire otherwise, use:

いくつの @methods をチェックするかに関わらず、 一つの can_ok() は一つのテストとして、カウントされます。 別の方法でやりたいなら、次のように使います:

    foreach my $meth (@methods) {
        can_ok('Foo', $meth);
    }

isa_ok

  isa_ok($object,   $class, $object_name);
  isa_ok($subclass, $class, $object_name);
  isa_ok($ref,      $type,  $ref_name);

Checks to see if the given $object->isa($class). Also checks to make sure the object was defined in the first place. Handy for this sort of thing:

与えられた $object->isa($class) が見えるかどうかをチェックします。 オブジェクトが最初の場所で定義されているか確かめるための チェックでもあります。 次のようなことをするのに便利です:

    my $obj = Some::Module->new;
    isa_ok( $obj, 'Some::Module' );

where you'd otherwise have to write

さもなければ次のように書く必要があるものです:

    my $obj = Some::Module->new;
    ok( defined $obj && $obj->isa('Some::Module') );

to safeguard against your test script blowing up.

これは、テストスクリプトが吹っ飛ぶのを防ぐためのセーフガードです。

You can also test a class, to make sure that it has the right ancestor:

クラスもテストできます; 正しい先祖か確かめます:

    isa_ok( 'Vole', 'Rodent' );

It works on references, too:

リファレンスでも動きます:

    isa_ok( $array_ref, 'ARRAY' );

The diagnostics of this test normally just refer to 'the object'. If you'd like them to be more specific, you can supply an $object_name (for example 'Test customer').

このテストの診断は通常、単に「そのオブジェクト」のリファレンスです。 それらをもっと特定したいなら、$object_name (たとえば、'Test customer')を指定できます。

new_ok

  my $obj = new_ok( $class );
  my $obj = new_ok( $class => \@args );
  my $obj = new_ok( $class => \@args, $object_name );

A convenience function which combines creating an object and calling isa_ok() on that object.

オブジェクトの作成と、そのオブジェクトへの isa_ok() の呼び出しを結合した 便利関数です。

It is basically equivalent to:

これは、次のものと基本的に同じです:

    my $obj = $class->new(@args);
    isa_ok $obj, $class, $object_name;

If @args is not given, an empty list will be used.

@args が与えられなければ、空のリストが使われます。

This function only works on new() and it assumes new() will return just a single object which isa $class.

この関数は、 new() でのみ動き、new() が $class と isa である 一つのオブジェクトを返すことを想定しています。

subtest

    subtest $name => \&code;

subtest() runs the &code as its own little test with its own plan and its own result. The main test counts this as a single test using the result of the whole subtest to determine if its ok or not ok.

subtest() は &code をそれ自身の計画と結果をもつそれ自身小さなテストとして、 実行します。 メインのテストはこれを一つのテストとしてカウントします; サブテスト全体の結果を使って、ok か not ok か決定します。

For example...

例えば...

  use Test::More tests => 3;
 
  pass("First test");

  subtest 'An example subtest' => sub {
      plan tests => 2;

      pass("This is a subtest");
      pass("So is this");
  };

  pass("Third test");

This would produce.

以下のように出力されます。

  1..3
  ok 1 - First test
      # Subtest: An example subtest
      1..2
      ok 1 - This is a subtest
      ok 2 - So is this
  ok 2 - An example subtest
  ok 3 - Third test

A subtest may call "skip_all". No tests will be run, but the subtest is considered a skip.

サブテストは、"skip_all" を呼んでもかまいません。 テストは実行されませんが、subtest は飛ばされたと考えられます。

  subtest 'skippy' => sub {
      plan skip_all => 'cuz I said so';
      pass('this test will never be run');
  };

Returns true if the subtest passed, false otherwise.

サブテストが成功すれば真を返し、さもなければ偽を返します。

Due to how subtests work, you may omit a plan if you desire. This adds an implicit done_testing() to the end of your subtest. The following two subtests are equivalent:

サブテストがどのように動くかによって、望むなら計画を省くことができます。 これはサブテストの末尾に暗黙の done_testing() を追加します。 以下の二つのサブテストは同じです:

  subtest 'subtest with implicit done_testing()', sub {
      ok 1, 'subtests with an implicit done testing should work';
      ok 1, '... and support more than one test';
      ok 1, '... no matter how many tests are run';
  };

  subtest 'subtest with explicit done_testing()', sub {
      ok 1, 'subtests with an explicit done testing should work';
      ok 1, '... and support more than one test';
      ok 1, '... no matter how many tests are run';
      done_testing();
  };

pass

fail

  pass($test_name);
  fail($test_name);

Sometimes you just want to say that the tests have passed. Usually the case is you've got some complicated condition that is difficult to wedge into an ok(). In this case, you can simply use pass() (to declare the test ok) or fail (for not ok). They are synonyms for ok(1) and ok(0).

時には、ただ、テストが成功したと示したいでしょう。 普通、このケースは、ok() に、押し込むことが難しい複雑な条件になっています。 こういう場合、単純に pass() (テストが ok であると宣言するために)か、 fail (not ok のために)かを使えます。 これらは、ok(1) と、ok(0) の同意語です。

Use these very, very, very sparingly.

pass() と fail() を使うことはひじょーに慎重に判断してください。

モジュールのテスト¶

あるモジュール、あるいは複数のモジュールの読み込みに成功するかを テストしたい場合があります。 例えば、より複雑なテストの実行に進む前に、単純に配布の全ての モジュールが読み込めるかをまずテストしたい場合がしばしばあります。

そのような目的のために、use_ok と、require_ok があります。

require_ok

   require_ok($module);
   require_ok($file);

Tries to require the given $module or $file. If it loads successfully, the test will pass. Otherwise it fails and displays the load error.

指定された $module または $file を require しようとします。 読み込みに成功すれば、テストは成功します。 さもなければ失敗し、読み込みエラーが表示されます。

require_ok will guess whether the input is a module name or a filename.

require_ok は、入力がモジュール名かファイル名かを推測します。

No exception will be thrown if the load fails.

読み込みに失敗しても例外は投げられません。

    # require Some::Module
    require_ok "Some::Module";

    # require "Some/File.pl";
    require_ok "Some/File.pl";

    # stop testing if any of your modules will not load
    for my $module (@module) {
        require_ok $module or BAIL_OUT "Can't load $module";
    }

use_ok

   BEGIN { use_ok($module); }
   BEGIN { use_ok($module, @imports); }

Like require_ok, but it will use the $module in question and only loads modules, not files.

require_ok と同様ですが、指定された $module を use し、 ファイルではなくモジュールだけを読み込みます。

If you just want to test a module can be loaded, use require_ok.

単にモジュールが読み込めるかをテストしたいなら、 require_ok を使ってください。

If you just want to load a module in a test, we recommend simply using use directly. It will cause the test to stop.

単にテストでモジュールを読み込みたいだけなら、直接 use を 使うことを勧めます。 これはテストの停止を引き起こします。

It's recommended that you run use_ok() inside a BEGIN block so its functions are exported at compile-time and prototypes are properly honored.

BEGIN ブロック内で、use_ok() を走らせることを推奨します。 これにより、この関数は、コンパイル時にエクスポートされ、 プロトタイプを適切に受け取ります。

If @imports are given, they are passed through to the use. So this:

@import が与えられた場合、use の際に渡されます。 従ってこれは:

   BEGIN { use_ok('Some::Module', qw(foo bar)) }

is like doing this:

次のようにするのと同じです:

   use Some::Module qw(foo bar);

Version numbers can be checked like so:

バージョン番号は次のようにチェックできます:

   # Just like "use Some::Module 1.02"
   BEGIN { use_ok('Some::Module', 1.02) }

Don't try to do this:

次のようにしようとしてはいけません:

   BEGIN {
       use_ok('Some::Module');

       ...some code that depends on the use...
       ...happening at compile time...
   }

because the notion of "compile-time" is relative. Instead, you want:

「コンパイル時」の記述が関係するからです。 代わりに、次のようにしましょう。

  BEGIN { use_ok('Some::Module') }
  BEGIN { ...some code that depends on the use... }

If you want the equivalent of use Foo (), use a module but not import anything, use require_ok.

use Foo () の同等物がほしい場合は、モジュールを使うけれども 何もインポートしない require_ok を使ってください。

  BEGIN { require_ok "Foo" }

複雑なデータ構造¶

全てが、単純な eq チェックや、正規表現ではありません。 たとえば、二つデータ構造が等価であるかどうかを見る必要があるときもあります。 こういった場合のために、Test::More は、ちょっとした有益な関数を 提供しています。

注意 ファイルハンドルについて起きることについて、あまり確信がありません。

is_deeply

  is_deeply( $got, $expected, $test_name );

Similar to is(), except that if $got and $expected are references, it does a deep comparison walking each data structure to see if they are equivalent. If the two structures are different, it will display the place where they start differing.

is() と似ていますが、$got と $expected はリファレンスです; それぞれのデータの構造を見てまわり、それぞれが等価かどうか、深い比較を します。 二つの構造が違っていれば、二つが違い始めた場所を示します。

is_deeply() compares the dereferenced values of references, the references themselves (except for their type) are ignored. This means aspects such as blessing and ties are not considered "different".

is_deeply() は、リファレンスのでリファレンスされた値の違いを比較します、 リファレンスそれ自身(その型を除く)は無視されます。 つまり、bless や tie のような側面は、「異なる」と考えられません。

is_deeply() currently has very limited handling of function reference and globs. It merely checks if they have the same referent. This may improve in the future.

is_deeply() は、今のところ、関数リファレンスと glob の扱いは 非常に限定的です。 単に、同じリファレンス先を持っているかをチェックします。 これは将来改善されるかもしれません。

Test::Differences and Test::Deep provide more in-depth functionality along these lines.

Test::Differences と Test::Deep は、より掘り下げた機能を 提供しています。

診断¶

正しいテスト関数を選んだなら、ふつう、そのテスト関数が失敗した場合に、 何が間違っているかについてよい情報を得ることができるでしょう。 ですが、時に、そういう風には、うまく働かないこともあります。 そのために、print STDERR よりも安全に、自分で自分自身の 診断メッセージを書く方法があります。

diag

  diag(@diagnostic_message);

Prints a diagnostic message which is guaranteed not to interfere with test output. Like print @diagnostic_message is simply concatenated together.

テストの出力に干渉しないと保証されている診断メッセージを出力します。 print と同様、@diagnostic_message は単純に一緒に結合されます。

Returns false, so as to preserve failure.

失敗のままにするために、偽を返します。

Handy for this sort of thing:

次のような場合に、手ごろです：

    ok( grep(/foo/, @users), "There's a foo user" ) or
        diag("Since there's no foo, check that /etc/bar is set up right");

which would produce:

次のようになります：

    not ok 42 - There's a foo user
    #   Failed test 'There's a foo user'
    #   in foo.t at line 52.
    # Since there's no foo, check that /etc/bar is set up right.

You might remember ok() or diag() with the mnemonic open() or die().

ok() or diag()を、open() or die() のように覚えると 覚えやすいかもしれません。

NOTE The exact formatting of the diagnostic output is still changing, but it is guaranteed that whatever you throw at it won't interfere with the test.

注意 診断の出力のための正確フォーマットは、まだ流動的です; しかし、それに何を渡してもテストに干渉しないことは保証されています。

note

  note(@diagnostic_message);

Like diag(), except the message will not be seen when the test is run in a harness. It will only be visible in the verbose TAP stream.

diag()と似ていますが、ハーネスでテストが動いている場合には表示されません。 冗長な TAP ストリームでのみ見られます。

Handy for putting in notes which might be useful for debugging, but don't indicate a problem.

デバッグに有用なメモをおくのに手ごろですが，問題を指摘するのに 使ってはいけません。

    note("Tempfile is $tempfile");

explain

  my @dump = explain @diagnostic_message;

Will dump the contents of any references in a human readable format. Usually you want to pass this into note or diag.

人が読みやすい形式で、リファレンスの内容をダンプします。 通常 note や diag に与えたいと思うでしょう。

Handy for things like...

次のような場合に、手ごろです...

    is_deeply($have, $want) || diag explain $have;

or

または

    note explain \%args;
    Some::Class->method(%args);

条件テスト¶

ある条件下でテストを動かすことによって、テストスクリプトが die することがあります。 (MacOS での fork() のような)特定の関数やメソッドは実装されていなかったり、 (ネット接続のような)いくつかのリソースが利用できなかったり、 モジュールが利用できなかったりとか。 こういったケースでは、テストをスキップしなければならないか、 そうでなければ、失敗することが予想されるけれど、 将来的に動くであろう(todo テスト)ということを宣言しなければなりません。

skip と todo テストの機構の詳細は、Test::Harness を見て下さい。

Test::More がこれを扱う方法は、名前付きブロックによるものです。 基本的にテストのブロックは、スキップさせるか、todo にするかです。 ただコードを見せるのが最善でしょう...

SKIP: BLOCK

  SKIP: {
      skip $why, $how_many if $condition;

      ...normal testing code goes here...
  }

This declares a block of tests that might be skipped, $how_many tests there are, $why and under what $condition to skip them. An example is the easiest way to illustrate:

これは、スキップするテストのブロックを宣言します。 $how_many はテストの数、 $why は理由、$condition は、 どういう条件で、これらのテストをスキップするのかを意味します。 最も簡単な例を見せます:

    SKIP: {
        eval { require HTML::Lint };

        skip "HTML::Lint not installed", 2 if $@;

        my $lint = new HTML::Lint;
        isa_ok( $lint, "HTML::Lint" );

        $lint->parse( $html );
        is( $lint->errors, 0, "No errors found in HTML" );
    }

If the user does not have HTML::Lint installed, the whole block of code won't be run at all. Test::More will output special ok's which Test::Harness interprets as skipped, but passing, tests.

ユーザが、HTML::Lint をインストールしていなければ、全てのブロックコードは、 まったく実行されません。 Test::More は特別な ok() を出力し、 Test::Harnes は、テストをスキップしたが、合格したと解釈します。

It's important that $how_many accurately reflects the number of tests in the SKIP block so the # of tests run will match up with your plan. If your plan is no_plan $how_many is optional and will default to 1.

テストの数が計画にマッチするために、 $how_many が正しく SKIP ブロックの中のテストの数を反映することは重要です。 もし、計画が no_plan であれば、$how_many はオプションで、デフォルトは 1 になります。

It's perfectly safe to nest SKIP blocks. Each SKIP block must have the label SKIP, or Test::More can't work its magic.

ネストする SKIP ブロックは完全に安全です。 それぞれの SKIP ブロックには、SKIP ラベルがなければなりません; そうしないと、Test::More は、その魔法をうまく使えません。

You don't skip tests which are failing because there's a bug in your program, or for which you don't yet have code written. For that you use TODO. Read on.

失敗するテストをスキップしてはいけません。 失敗するのは、プログラムにバグがあるからですし、 そうでなければ、まだコードを書いていないからです。 そのような場合は TODO を使います。 読み続けてください。

TODO: BLOCK

    TODO: {
        local $TODO = $why if $condition;

        ...normal testing code goes here...
    }

        ...ふつうのテストコードをここに続けてください...
    }

Declares a block of tests you expect to fail and $why. Perhaps it's because you haven't fixed a bug or haven't finished a new feature:

失敗すると予測しているテストと、$why のブロックを宣言します。 たぶん、バグをまだ直していないか、新しい機能を作り終えていないのでしょう:

    TODO: {
        local $TODO = "URI::Geller not finished";

        my $card = "Eight of clubs";
        is( URI::Geller->your_card, $card, 'Is THIS your card?' );

        my $spoon;
        URI::Geller->bend_spoon;
        is( $spoon, 'bent',    "Spoon bending, that's original" );
    }

With a todo block, the tests inside are expected to fail. Test::More will run the tests normally, but print out special flags indicating they are "todo". Test::Harness will interpret failures as being ok. Should anything succeed, it will report it as an unexpected success. You then know the thing you had todo is done and can remove the TODO flag.

todo ブロックでは、その中のテストは、失敗すると予期されます。 Test::More は、普通にテストを行いますが、特別なフラグを出力し、 それのテストが「todo」であることを示します。 Test::Harness は、この失敗を ok であると解釈します。 何かが成功すると、予期しない成功と報告します。 そうすると、あなたは todo が解消されたと分かり、 TODO フラグを外すことが出来ます。

The nice part about todo tests, as opposed to simply commenting out a block of tests, is it's like having a programmatic todo list. You know how much work is left to be done, you're aware of what bugs there are, and you'll know immediately when they're fixed.

todo テストの良いところは、テストのブロックを単純に コメントアウトすることではなく、 プログラム的な todo リストであるようになることです。 どれくらいするべき仕事が残っているのか分かるし、どのようなバグがあるのかも 気付きます; また、それらのテストが修正された場合、即座に識別することが出来ます。

Once a todo test starts succeeding, simply move it outside the block. When the block is empty, delete it.

一度、todo テストが成功し始めると、単純に、ブロックの外側にそれを移します。 ブロックが空なら、削除します。

todo_skip

    TODO: {
        todo_skip $why, $how_many if $condition;

        ...normal testing code...
    }

With todo tests, it's best to have the tests actually run. That way you'll know when they start passing. Sometimes this isn't possible. Often a failing test will cause the whole program to die or hang, even inside an eval BLOCK with and using alarm. In these extreme cases you have no choice but to skip over the broken tests entirely.

todo テストでは、実際にテストをなるべく走らせようとします。 このように、それらのテストがいつ通過し始めるかを知るでしょう。 時々、これが可能でない場合があります。 失敗するテストは全てのプログラムが die するか、 ハングする原因になることがよくあります; eval BLOCK の内側で、alarm を使ってもです。 このような極端なケースでは、壊れたテストを完全にスキップする以外には、 選択の余地はありません。

The syntax and behavior is similar to a SKIP: BLOCK except the tests will be marked as failing but todo. Test::Harness will interpret them as passing.

todo ではなくテストが失敗としてマークされる以外は、 構文や振る舞いが SKIP: BLOCK に似ています。 Test::Harness は、テストに合格していると解釈します。

When do I use SKIP vs. TODO?

(SKIP 対 TODO をどのように使い分けるのでしょう？)

If it's something the user might not be able to do, use SKIP. This includes optional modules that aren't installed, running under an OS that doesn't have some feature (like fork() or symlinks), or maybe you need an Internet connection and one isn't available.

もし、ユーザが出来ないかもしれないときには、SKIP を使ってください。 これには、インストールされていないオプションのモジュールや、 (fork() や symlinks などの)機能を持っていない OS で実行することや、 インターネット接続を必要としているのに、それをユーザが 利用できないことも含みます。

If it's something the programmer hasn't done yet, use TODO. This is for any code you haven't written yet, or bugs you have yet to fix, but want to put tests in your testing script (always a good idea).

もし、プログラマがまだ、やっていないときには、TODO を使ってください。 これは、テストスクリプトにテストを置きたい(常によい考えです)けれども、 まだ書いていないコードや、まだ直していないバグなどです。

テストの制御¶

BAIL_OUT

    BAIL_OUT($reason);

Indicates to the harness that things are going so badly all testing should terminate. This includes the running of any additional test scripts.

悲惨ななことになったため、すべてのテストを終了させるように、harness に 伝えます。 これは、どんな追加のテストスクリプトの実行も含みます。

This is typically used when testing cannot continue such as a critical module failing to compile or a necessary external utility not being available such as a database connection failing.

データベース接続のような、重要なモジュールのコンパイルエラーや 必須の外部ユーティリティが利用できないようなために、 テストが続けられない場合に、典型的に使われます。

The test will exit with 255.

テストは 255 で終了します。

For even better control look at Test::Most.

Test::Most に、よりよい制御があります。

推奨されない比較関数¶

下記の関数の使用は推奨されません; これらは、実際にはテスト関数ではなく、 何が間違っているかを突き止める助けとなる診断は提供しません。 is_deeply() ができるより前に書かれた関数で、二つの任意のデータ構造の 違いを表示する有効な方法を考え付くことが出来なかったためです。

これらは、ok() の中で使われるのが普通です。

    ok( eq_array(\@got, \@expected) );

is_deeply() は、より良いですし、診断もあります。

    is_deeply( \@got, \@expected );

将来のバージョンでなくなるかもしれません。

eq_array

  my $is_eq = eq_array(\@got, \@expected);

Checks if two arrays are equivalent. This is a deep check, so multi-level structures are handled correctly.

二つの配列が等価かどうかをチェックします。 これは、深いチェックであり、マルチレベルの構造が正確に扱われます。

eq_hash

  my $is_eq = eq_hash(\%got, \%expected);

Determines if the two hashes contain the same keys and values. This is a deep check.

二つのハッシュが同じキーと値を含んでいるかどうかを調べます。 これは深いチェックです。

eq_set

  my $is_eq = eq_set(\@got, \@expected);

Similar to eq_array(), except the order of the elements is not important. This is a deep check, but the irrelevancy of order only applies to the top level.

eq_array() と似ていますが、要素の順番は重要では ありません。 これは、深いチェックですが、順番の無視はトップレベルにしか 適用されません。

    ok( eq_set(\@got, \@expected) );

Is better written:

より良い書き方:

    is_deeply( [sort @got], [sort @expected] );

NOTE By historical accident, this is not a true set comparison. While the order of elements does not matter, duplicate elements do.

注意 歴史的な都合により、これは、本当の集合の比較ではありません。 要素の順番が問題ではない上に、重複した要素も問題にしません。

NOTE eq_set() does not know how to deal with references at the top level. The following is an example of a comparison which might not work:

注意 eq_set() は、トップレベルでリファレンスをどう扱うかを知りません。 以下のものは、動かない比較の例です:

    eq_set([\1, \2], [\2, \1]);

Test::Deep contains much better set comparison functions.

Test::Deep には、よりよい集合比較関数があります。

Test::More の拡張と埋め込み¶

Test::More のインターフェースが、まったく十分でない時もあります。 幸運なことに、Test::More は Test::Builder の上に作られています。 Test::Builder はあらゆるテストライブラリーのための、一つの統合された バックエンドを提供しています。 このことは、両方とも Test::Builder を使っている、二つの テストライブラリーならば、同じプログラムで同時に使える ことを 意味します。

もし単純に、テストの挙動の仕方を微調整したければ、次のように、 ベースとされた Test::Builder オブジェクトにアクセスできます:

builder

    my $test_builder = Test::More->builder;

Returns the Test::Builder object underlying Test::More for you to play with.

Test::More で遊ぶための、Test::More の基礎をなす Test::Builder オブジェクトを 返します。

終了コード¶

すべてのテストが合格したら、Test::Builder は 0 で終了します(通常です)。 何か間違っていたら，間違った数で終了します。計画しているよりも、 少ない(か、多い)か、見失ったか、余計なテストを走らせると、失敗したと みなされます。 テストが実行されなければ、警告を投げ、255 で終了します。 テストが die したら、たとえすべてのテストが成功しても、 失敗とみなし、255 で終了します。

終了コードは...

    0                   all tests successful
    255                 test died or all passed but wrong # of tests run
    any other number    how many failed (including missing or extras)

    0              すべてのテストが成功
    255            テストは die したか、すべて成功したがテスト数が間違っている
    その他の数値   失敗した数(不足や過剰を含む)

254 以上のテストに失敗したら、254 を報告します。

注意 この振る舞いは、将来のバージョンでなくなるかもしれません。

COMPATIBILITY¶

Test::More は 5.8.1 以降の Perl で動作します。

スレッド対応は 5.10.1 より前ではあまり安定していませんが、 これはスレッドが 5.10.1 より前ではあまり安定していないからです。

Test::More は 5.6.2 以降の Perl でコアモジュールになっていますが、 Test::More はそれから進化していて、 あなたが使っている全ての機能が同梱されているバージョンの Test::More に ないかもしれません。 あなたがモジュールを書いているなら、 あなたが必要な Test::More の最小バージョンをパッケージのメタデータに 指定することを忘れないでください。 例えば、もしあなたが done_testing() を使っているけれども、 あなたのテストスクリプトが Perl 5.10.0 で動作してほしいなら、, 明示的に Test::More > 0.88 を要求する必要があります。

主な機能のマイルストーンは:

subtests

Subtests were released in Test::More 0.94, which came with Perl 5.12.0. Subtests did not implicitly call done_testing() until 0.96; the first Perl with that fix was Perl 5.14.0 with 0.98.

Subtests were released in Test::More 0.94, which came with Perl 5.12.0. Subtests did not implicitly call done_testing() until 0.96; the first Perl with that fix was Perl 5.14.0 with 0.98. (TBT)

done_testing()

This was released in Test::More 0.88 and first shipped with Perl in 5.10.1 as part of Test::More 0.92.

これは Test::More 0.88 でリリースされ、最初に同梱されたのは Perl 5.10.1 に Test::More 0.92 の一部としてです。

cmp_ok()

Although cmp_ok() was introduced in 0.40, 0.86 fixed an important bug to make it safe for overloaded objects; the fixed first shipped with Perl in 5.10.1 as part of Test::More 0.92.

cmp_ok() は 0.40 で導入されましたが、 0.86 でオーバーロードされたオブジェクトに対しても安全にするための 重要なバグが修正されています; 修正されたものが最初に同梱されたのは Perl 5.10.1 に Test::More 0.92 の一部としてです。

new_ok() note() and explain()

These were was released in Test::More 0.82, and first shipped with Perl in 5.10.1 as part of Test::More 0.92.

これらは Test::More 0.82 でリリースされ、 最初に同梱されたのは Perl 5.10.1 に Test::More 0.92 の一部としてです。

完全なバージョン履歴は Changes ファイルにあり、 コアに含まれている Test::More のバージョンは Module::CoreList を 使うことでわかります:

    $ corelist -a Test::More

警告と注意¶

utf8 / "Wide character in print"

If you use utf8 or other non-ASCII characters with Test::More you might get a "Wide character in print" warning. Using binmode STDOUT, ":utf8" will not fix it. Test::Builder (which powers Test::More) duplicates STDOUT and STDERR. So any changes to them, including changing their output disciplines, will not be seem by Test::More.

utf8 やその他の non-ASCII な文字を Test::More と一緒に使う場合、 "Wide character in print" の警告が出るかもしれません。 binmode STDOUT, ":utf8" を使っても直りません。 (Test::More を駆動している) Test::Builder は STDOUT と STDERR を 複製しています。 そのため、それらの出力の方法の変更も含む、それらへのどんな変更も、、 Test::More にはわかりません。

One work around is to apply encodings to STDOUT and STDERR as early as possible and before Test::More (or any other Test module) loads.

一つの回避法は、できるだけ早く、Test::More (およびその他の Test モジュール) を読み込むより前に、STDOUT と STDERR にエンコーディングを 適用することです。

    use open ':std', ':encoding(utf8)';
    use Test::More;

A more direct work around is to change the filehandles used by Test::Builder.

より直接的な回避法は、Test::Builder で使われているファイルハンドルを 変更することです。

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

Overloaded objects

(オーバーロードされたオブジェクト)

String overloaded objects are compared as strings (or in cmp_ok()'s case, strings or numbers as appropriate to the comparison op). This prevents Test::More from piercing an object's interface allowing better blackbox testing. So if a function starts returning overloaded objects instead of bare strings your tests won't notice the difference. This is good.

オーバーロードされたオブジェクトは 文字列として (または cmp_ok() では、 比較する演算子に従って、文字列か数字として)比較されます。 これは、Test::More が、より良いブラックボックステストを許している オブジェクトのインターフェースを突き刺すのを妨げます。 そのため、関数が裸の文字列の代わりに、オーバーロードされた オブジェクトを返すようになれば、あなたのテストは違いに気付かないでしょう。 これは良いことです。

However, it does mean that functions like is_deeply() cannot be used to test the internals of string overloaded objects. In this case I would suggest Test::Deep which contains more flexible testing functions for complex data structures.

ですが、is_deeply() のような関数が、オブジェクトがオーバーロードされた文字列の 内部のテストに使うことが出来ないというわけではありません。 このケースでは、Test::Deep を提案します。 複雑なデータ構造のために、より柔軟なテスト関数があります。

Threads

Test::More will only be aware of threads if "use threads" has been done before Test::More is loaded. This is ok:

Test::More は、Test::More がロードされる前に、"use threads" がされている場合、 スレッドを意識します。 次は ok です:

    use threads;
    use Test::More;

This may cause problems:

次のものは問題になります:

    use Test::More
    use threads;

5.8.1 and above are supported. Anything below that has too many bugs.

5.8.1 以上に対応しています。 それ未満のバージョンには、あまりにも多くのバグがあります。

経緯¶

これは、Joshua Pritikin の Test モジュールをまとめて進化させたものです。 自分が ok() ルーチンを最初に書いたとき、この存在に まったく気づいていませんでした。 このモジュールが在るのは、簡単にテストの名前を Test のインターフェースに、 押し込む方法を見つけ出せなかったからです(他のいくつかの問題とともに)。

ここでのゴールは、既存の Test.pm より、柔軟性を提供しつつ 学びやすく、すぐに使えて、つまずきにくいテストのユーティリティです。 こんなわけで、ほとんどの共通のルーチンの名前は小さいままにして、 特別なケースと魔法の側面の効果は最小限にとどめました。 WYSIWYG(やり方は一つじゃない)。

SEE ALSO¶

Test::Simple もし、Test::More がまったく混乱させるだけのものであり、 ただ、テストを書きたいだけなら。 後で、Test::More にアップグレードできます (Test::More は、上位互換性が あります)。

Test::Harness は、テスト実行器であり、Perl の出力インタプリタです。 make test を駆動しているものであり、prove ユーティリティが 由来するところです。

Test::Legacy は、オリジナルのテストモジュールである、 他のテストライブラリと一緒にはうまく動かない、 Test.pm と共に書かれたテストを行います。 Test::Legacy は、Test.pm のインターフェースをエミュレートし、他のものと うまく動きます。

Test::Differences 複雑なデータ構造をテストするためのより多くの 方法のために。 Test::More と共にうまく動きます。

Test::Class は、xUnit に似ていますが、より perl っぽいです。

Test::Deep は、より強力で複雑なデータ構造のテストができます。

Test::Inline は埋め込みテストというアイデアを示します。

Bundle::Test は、便利なテストモジュールを全てインストールします。

作者¶

Michael G Schwern <[email protected]> with much inspiration from Joshua Pritikin's Test module and lots of help from Barrie Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.

バグ¶

See http://rt.cpan.org to report and view bugs.

SOURCE¶

The source code repository for Test::More can be found at http://github.com/schwern/test-more/.

コピーライト¶

Copyright 2001-2008 by Michael G Schwern <[email protected]>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html