期待値

Pest の期待値 API を使用してテストの期待値を設定することで、コード内のバグやその他の問題を簡単に特定できます。これは、API を使用してテストの期待される結果を指定できるため、期待される動作からの逸脱を簡単に検出できるためです。

値を expect($value) 関数に渡すことで、期待値を開始できます。expect() 関数は、値をテストするたびに使用されます。expect() 単独で呼び出すことはほとんどありません。代わりに、値について何かをアサートするために、「期待値」メソッドとともに expect() を使用します。

1test('sum', function () {
2    $value = sum(1, 2);
3 
4    expect($value)->toBe(3); // Assert that the value is 3...
5});

デモンストレーションされているように、Pest の expect 関数を使用すると、特定の $value に対して複数の期待値をチェーン接続できます。つまり、追加の期待値をチェーン接続し続けるだけで、1 回のテストで必要な数のチェックを実行できます。

1expect($value)
2    ->toBeInt()
3    ->toBe(3);

いつでも、期待値の反対をテストするには、期待値に not 修飾子を付加します。

1expect($value)
2    ->toBeInt()
3    ->toBe(3)
4    ->not->toBeString() // Not to be string...
5    ->not->toBe(4); // Not to be 4...

Pest の期待値 API では、コードのさまざまな側面をテストするように設計された、個々の期待値の広範なコレクションにアクセスできます。以下は、利用可能な期待値の包括的なリストです。

Pest で利用可能な個々の期待値に加えて、期待値 API は、テストをさらにカスタマイズできるいくつかの修飾子も提供します。これらの修飾子を使用して、より複雑な期待値を作成したり、複数の値を一度にテストしたりできます。以下に、Pest で利用可能な修飾子の例を示します。

toBe()

この期待値は、$value と $expected の両方が同じ型と値を共有することを保証します。

オブジェクトで使用する場合は、両方の変数がまったく同じオブジェクトを参照していることを保証します。

1expect(1)->toBe(1);
2expect('1')->not->toBe(1);
3expect(new StdClass())->not->toBe(new StdClass());

toBeBetween()

この期待値は、$value が 2 つの値の間にあることを保証します。int、float、および DateTime で機能します。

1expect(2)->toBeBetween(1, 3);
2expect(1.5)->toBeBetween(1, 2);
3 
4$expectationDate = new DateTime('2023-09-22');
5$oldestDate = new DateTime('2023-09-21');
6$latestDate = new DateTime('2023-09-23');
7 
8expect($expectationDate)->toBeBetween($oldestDate, $latestDate);

toBeEmpty()

この期待値は、$value が空であることを保証します。

1expect('')->toBeEmpty();
2expect([])->toBeEmpty();
3expect(null)->toBeEmpty();

toBeTrue()

この期待値は、$value が true であることを保証します。

1expect($isPublished)->toBeTrue();

toBeTruthy()

この期待値は、$value が真値であることを保証します。

1expect(1)->toBeTruthy();
2expect('1')->toBeTruthy();

toBeFalse()

この期待値は、$value が false であることを保証します。

1expect($isPublished)->toBeFalse();

toBeFalsy()

この期待値は、$value が偽値であることを保証します。

1expect(0)->toBeFalsy();
2expect('')->toBeFalsy();

toBeGreaterThan($expected)

この期待値は、$value が $expected より大きいことを保証します。

1expect($count)->toBeGreaterThan(20);

toBeGreaterThanOrEqual($expected)

この期待値は、$value が $expected 以上であることを保証します。

1expect($count)->toBeGreaterThanOrEqual(21);

toBeLessThan($expected)

この期待値は、$value が $expected より小さいことを保証します。

1expect($count)->toBeLessThan(3);

toBeLessThanOrEqual($expected)

この期待値は、$value が $expected 以下であることを保証します。

1expect($count)->toBeLessThanOrEqual(2);

toContain($needles)

この期待値は、指定されたすべてのニードルが $value の要素であることを保証します。

1expect('Hello World')->toContain('Hello');
2expect('Pest: an elegant PHP Testing Framework')->toContain('Pest', 'PHP', 'Framework');
3expect([1, 2, 3, 4])->toContain(2, 4);

toContainEqual($needles)

この期待値は、指定されたすべてのニードルが $value の要素（同等性に関して）であることを保証します。

1expect([1, 2, 3])->toContainEqual('1');
2expect([1, 2, 3])->toContainEqual('1', '2');

toContainOnlyInstancesOf($class)

この期待値は、$value に $class のインスタンスのみが含まれていることを保証します。

1$dates = [new DateTime(), new DateTime()];
2 
3expect($dates)->toContainOnlyInstancesOf(DateTime::class);

toHaveCount(int $count)

この期待値は、指定された $count がイテラブルな $value の要素数と一致することを保証します。

1expect(['Nuno', 'Luke', 'Alex', 'Dan'])->toHaveCount(4);

toHaveProperty(string $name, $value = null)

この期待値は、$value に $name という名前のプロパティがあることを保証します。

さらに、2 番目の引数を指定して、プロパティの実際の値を検証できます。

1expect($user)->toHaveProperty('name');
2expect($user)->toHaveProperty('name', 'Nuno');
3expect($user)->toHaveProperty('is_active', 'true');

toHaveProperties(iterable $name)

この期待値は、$value に $names に含まれるすべての名前と一致するプロパティ名があることを保証します。

1expect($user)->toHaveProperties(['name', 'email']);

さらに、連想配列を使用して、複数のプロパティの名前と値を検証できます。

1expect($user)->toHaveProperties([
2    'name' => 'Nuno',
3    'email' => 'enunomaduro@gmail.com'
4]);

toMatchArray($array)

この期待値は、$value 配列が指定された $array サブセットと一致することを保証します。

 1$user = [
 2    'id'    => 1,
 3    'name'  => 'Nuno',
 4    'email' => 'enunomaduro@gmail.com',
 5    'is_active' => true,
 6];
 7 
 8expect($user)->toMatchArray([
 9    'email' => 'enunomaduro@gmail.com',
10    'name' => 'Nuno'
11]);

toMatchObject($object)

この期待値は、$value オブジェクトが指定された $object のプロパティのサブセットと一致することを保証します。

1$user = new stdClass();
2$user->id = 1;
3$user->email = 'enunomaduro@gmail.com';
4$user->name = 'Nuno';
5 
6expect($user)->toMatchObject([
7    'email' => 'enunomaduro@gmail.com',
8    'name' => 'Nuno'
9]);

toEqual($expected)

この期待値は、$value と $expected が同じ値を持つことを保証します。

1expect($title)->toEqual('Hello World');
2expect('1')->toEqual(1);
3expect(new StdClass())->toEqual(new StdClass());

toEqualCanonicalizing($expected)

この期待値は、要素がどのような順序で指定されているかに関係なく、$value と $expected が同じ値を持つことを保証します。

1$usersAsc = ['Dan', 'Fabio', 'Nuno'];
2$usersDesc = ['Nuno', 'Fabio', 'Dan'];
3 
4expect($usersAsc)->toEqualCanonicalizing($usersDesc);
5expect($usersAsc)->not->toEqual($usersDesc);

toEqualWithDelta($expected, float $delta)

この期待値は、$value と $expected の絶対差が $delta より小さいことを保証します。

1expect($durationInMinutes)->toEqualWithDelta(10, 5); //duration of 10 minutes with 5 minutes tolerance
2 
3expect(14)->toEqualWithDelta(10, 5);    // Pass
4expect(14)->toEqualWithDelta(10, 0.1); // Fail

toBeIn()

この期待値は、$value が指定された値の 1 つであることを保証します。

1expect($newUser->status)->toBeIn(['pending', 'new', 'active']);

toBeInfinite()

この期待値は、$value が無限であることを保証します。

1expect(log(0))->toBeInfinite();

toBeInstanceOf($class)

この期待値は、$value が $class のインスタンスであることを保証します。

1expect($user)->toBeInstanceOf(User::class);

toBeArray()

この期待値は、$value が配列であることを保証します。

1expect(['Pest','PHP','Laravel'])->toBeArray();

toBeBool()

この期待値は、$value が bool 型であることを保証します。

1expect($isActive)->toBeBool();

toBeCallable()

この期待値は、$value が callable 型であることを保証します。

1$myFunction = function () {};
2 
3expect($myFunction)->toBeCallable();

toBeFile()

この期待値は、文字列 $value が既存のファイルであることを保証します。

1expect('/tmp/some-file.tmp')->toBeFile();

toBeFloat()

この期待値は、$value が float 型であることを保証します。

1expect($height)->toBeFloat();

toBeInt()

この期待値は、$value が integer 型であることを保証します。

1expect($count)->toBeInt();

toBeIterable()

この期待値は、$value が iterable 型であることを保証します。

1expect($array)->toBeIterable();

toBeNumeric()

この期待値は、$value が numeric 型であることを保証します。

1expect($age)->toBeNumeric();
2expect(10)->toBeNumeric();
3expect('10')->toBeNumeric();

toBeDigits()

この期待値は、$value が数字のみで構成されていることを保証します。

1expect($year)->toBeDigits();
2expect(15)->toBeDigits();
3expect('15')->toBeDigits();

toBeObject()

この期待値は、$value が object 型であることを保証します。

1$object = new stdClass();
2 
3expect($object)->toBeObject();

toBeResource()

この期待値は、$value が resource 型であることを保証します。

1$handle = fopen('php://memory', 'r+');
2 
3expect($handle)->toBeResource();

toBeScalar()

この期待値は、$value が scalar 型であることを保証します。

1expect('1')->toBeScalar();
2expect(1)->toBeScalar();
3expect(1.0)->toBeScalar();
4expect(true)->toBeScalar();
5expect([1, '1'])->not->toBeScalar();

toBeString()

この期待値は、$value が string 型であることを保証します。

1expect($string)->toBeString();

toBeJson()

この期待値は、$value が JSON 文字列であることを保証します。

1expect('{"hello":"world"}')->toBeJson();

toBeNan()

この期待値は、$value が非数 (NaN) であることを保証します。

1expect(sqrt(-1))->toBeNan();

toBeNull()

この期待値は、$value が null であることを保証します。

1expect(null)->toBeNull();

toHaveKey(string $key)

この期待値は、$value が提供された $key を含むことを保証します。

1expect(['name' => 'Nuno', 'surname' => 'Maduro'])->toHaveKey('name');
2expect(['name' => 'Nuno', 'surname' => 'Maduro'])->toHaveKey('name', 'Nuno');
3expect(['user' => ['name' => 'Nuno', 'surname' => 'Maduro']])->toHaveKey('user.name');
4expect(['user' => ['name' => 'Nuno', 'surname' => 'Maduro']])->toHaveKey('user.name', 'Nuno');

toHaveKeys(array $keys)

この期待値は、$value が提供された $keys を含むことを保証します。

1expect(['id' => 1, 'name' => 'Nuno'])->toHaveKeys(['id', 'name']);
2expect(['message' => ['from' => 'Nuno', 'to' => 'Luke'] ])->toHaveKeys(['message.from', 'message.to']);

toHaveLength(int $number)

この期待値は、提供された $number が文字列 $value の長さ、または iterable $value の要素数と一致することを保証します。

1expect('Pest')->toHaveLength(4);
2expect(['Nuno', 'Maduro'])->toHaveLength(2);

toBeDirectory()

この期待値は、文字列 $value がディレクトリであることを保証します。

1expect('/tmp')->toBeDirectory();

toBeReadableDirectory()

この期待値は、文字列 $value がディレクトリであり、かつ読み取り可能であることを保証します。

1expect('/tmp')->toBeReadableDirectory();

toBeReadableFile()

この期待値は、文字列 $value がファイルであり、かつ読み取り可能であることを保証します。

1expect('/tmp/some-file.tmp')->toBeReadableFile();

toBeWritableDirectory()

この期待値は、文字列 $value がディレクトリであり、かつ書き込み可能であることを保証します。

1expect('/tmp')->toBeWritableDirectory();

toBeWritableFile()

この期待値は、文字列 $value がファイルであり、かつ書き込み可能であることを保証します。

1expect('/tmp/some-file.tmp')->toBeWritableFile();

toStartWith(string $expected)

この期待値は、$value が提供された文字列で始まることを保証します。

1expect('Hello World')->toStartWith('Hello');

toThrow()

この期待値は、クロージャが特定の例外クラス、例外メッセージ、またはその両方をスローすることを保証します。

1expect(fn() => throw new Exception('Something happened.'))->toThrow(Exception::class);
2expect(fn() => throw new Exception('Something happened.'))->toThrow('Something happened.');
3expect(fn() => throw new Exception('Something happened.'))->toThrow(Exception::class, 'Something happened.');
4expect(fn() => throw new Exception('Something happened.'))->toThrow(new Exception('Something happened.'));

toMatch(string $expression)

この期待値は、$value が正規表現に一致することを保証します。

1expect('Hello World')->toMatch('/^hello wo.*$/i');

toEndWith(string $expected)

この期待値は、$value が提供された文字列で終わることを保証します。

1expect('Hello World')->toEndWith('World');

toMatchConstraint(Constraint $constraint)

この期待値は、$value が指定された PHPUnit 制約に一致することを保証します。

1use PHPUnit\Framework\Constraint\IsTrue;
2 
3expect(true)->toMatchConstraint(new IsTrue());

toBeUppercase(string $expected)

この期待値は、$value が大文字であることを保証します。

1expect('PESTPHP')->toBeUppercase();

toBeLowercase(string $expected)

この期待値は、$value が小文字であることを保証します。

1expect('pestphp')->toBeLowercase();

toBeAlpha(string $expected)

この期待値は、$value がアルファベット文字のみを含むことを保証します。

1expect('pestphp')->toBeAlpha();

toBeAlphaNumeric(string $expected)

この期待値は、$value が英数字のみを含むことを保証します。

1expect('pestPHP123')->toBeAlphaNumeric();

toBeSnakeCase()

この期待値は、$value が snake_case 形式の文字列のみを含むことを保証します。

1expect('snake_case')->toBeSnakeCase();

toBeKebabCase()

この期待値は、$value が kebab-case 形式の文字列のみを含むことを保証します。

1expect('kebab-case')->toBeKebabCase();

toBeCamelCase()

この期待値は、$value が camelCase 形式の文字列のみを含むことを保証します。

1expect('camelCase')->toBeCamelCase();

toBeStudlyCase()

この期待値は、$value が StudlyCase 形式の文字列のみを含むことを保証します。

1expect('StudlyCase')->toBeStudlyCase();

toHaveSnakeCaseKeys()

この期待値は、$value が snake_case 形式のキーを持つ配列のみを含むことを保証します。

1expect(['snake_case' => 'abc123'])->toHaveSnakeCaseKeys();

toHaveKebabCaseKeys()

この期待値は、$value が kebab-case 形式のキーを持つ配列のみを含むことを保証します。

1expect(['kebab-case' => 'abc123'])->toHaveKebabCaseKeys();

toHaveCamelCaseKeys()

この期待値は、$value が camelCase 形式のキーを持つ配列のみを含むことを保証します。

1expect(['camelCase' => 'abc123'])->toHaveCamelCaseKeys();

toHaveStudlyCaseKeys()

この期待値は、$value が StudlyCase 形式のキーを持つ配列のみを含むことを保証します。

1expect(['StudlyCase' => 'abc123'])->toHaveStudlyCaseKeys();

toHaveSameSize()

この期待値は、$value のサイズと、提供された iterable のサイズが同じであることを保証します。

1expect(['foo', 'bar'])->toHaveSameSize(['baz', 'bazz']);

toBeUrl()

この期待値は、$value が URL であることを保証します。

1expect('https://pest.dokyumento.jp/')->toBeUrl();

toBeUuid()

この期待値は、$value が UUID であることを保証します。

1expect('ca0a8228-cdf6-41db-b34b-c2f31485796c')->toBeUuid();

and($value)

and() 修飾子は、新しい $value を渡すことを可能にし、単一のテストで複数の期待値を連鎖させることができます。

1expect($id)->toBe(14)
2    ->and($name)->toBe('Nuno');

dd()

dd() 修飾子

dd() 修飾子を使用すると、現在の期待値 $value をダンプしてコードの実行を停止できます。これにより、テストの特定時点における $value の状態を検査できるため、デバッグに役立ちます。

1expect(14)->dd(); // 14
2expect([1, 2])->sequence(
3    fn ($number) => $number->toBe(1),
4    fn ($number) => $number->dd(), // 2
5);

ddWhen($condition)

ddWhen() 修飾子を使用すると、指定された $condition が truthy の場合に、現在の期待値 $value をダンプしてコードの実行を停止できます。

1expect([1, 2])->each(
2    fn ($number) => $number->ddWhen(fn (int $number) => $number === 2) // 2
3);

ddUnless($condition)

ddUnless() 修飾子を使用すると、指定された $condition が falsy の場合に、現在の期待値 $value をダンプしてコードの実行を停止できます。

1expect([1, 2])->each(
2    fn ($number) => $number->ddUnless(fn (int $number) => $number === 1) // 2
3);

each()

each() 修飾子を使用すると、指定された iterable の各項目に対して期待値を作成できます。iterable を反復処理し、各項目に期待値を適用することで機能します。

1expect([1, 2, 3])->each->toBeInt();
2expect([1, 2, 3])->each->not->toBeString();
3expect([1, 2, 3])->each(fn ($number) => $number->toBeLessThan(4));

json()

json() 修飾子は、現在の期待値 $value を JSON から配列にデコードします。

1expect('{"name":"Nuno","credit":1000.00}')
2    ->json()
3    ->toHaveCount(2)
4    ->name->toBe('Nuno')
5    ->credit->toBeFloat();
6 
7expect('not-a-json')->json(); //Fails

match()

match() 修飾子は、メソッドに渡された最初の引数の値に一致する最初の配列キーに関連付けられたクロージャを実行します。

1expect($user->miles)
2    ->match($user->status, [
3        'new'  => fn ($userMiles) => $userMiles->ToBe(0),
4        'gold'  => fn ($userMiles) => $userMiles->toBeGreaterThan(500),
5        'platinum' => fn ($userMiles) => $userMiles->toBeGreaterThan(1000),
6    ]);

期待値が一致するキーに関連付けられた値と等しいかどうかを確認するには、クロージャを使用する代わりに、期待値を配列の値として直接渡すことができます。

1expect($user->default_language)
2    ->match($user->country, [
3        'PT' => 'Português',
4        'US' => 'English',
5        'TR' => 'Türkçe',
6    ]);

not

not 修飾子は、後続の期待値を反転させることを可能にします。

1expect(10)->not->toBeGreaterThan(100);
2expect(true)->not->toBeFalse();

ray()

ray() 修飾子を使用すると、myray.app を使用して現在の $value をデバッグできます。

1expect(14)->ray(); // 14
2expect([1, 2])->sequence(
3    fn ($number) => $number->toBe(1),
4    fn ($number) => $number->ray(), // 2
5);

sequence()

sequence() 修飾子を使用すると、単一の iterable に対して連続した期待値のセットを指定できます。

1expect([1, 2, 3])->sequence(
2    fn ($number) => $number->toBe(1),
3    fn ($number) => $number->toBe(2),
4    fn ($number) => $number->toBe(3),
5);

sequence() モディファイアは、連想イテラブルにも使用できます。シーケンス内の各クロージャは2つの引数を受け取ります。最初の引数は値の期待値、2番目の引数はキーの期待値です。

1expect(['hello' => 'world', 'foo' => 'bar', 'john' => 'doe'])->sequence(
2    fn ($value, $key) => $value->toEqual('world'),
3    fn ($value, $key) => $key->toEqual('foo'),
4    fn ($value, $key) => $value->toBeString(),
5);

sequence() モディファイアは、イテラブル内の各値が期待値のセットに一致するかどうかを確認するためにも使用できます。この場合、クロージャを使用する代わりに、期待値を直接 sequence() メソッドに渡すことができます。

1expect(['foo', 'bar', 'baz'])->sequence('foo', 'bar', 'baz');

when()

when() モディファイアは、メソッドに渡された最初の引数が true と評価された場合に、提供されたコールバックを実行します。

1expect($user)
2    ->when($user->is_verified === true, fn ($user) => $user->daily_limit->toBeGreaterThan(10))
3    ->email->not->toBeEmpty();

unless()

unless() モディファイアは、メソッドに渡された最初の引数が false と評価された場合に、提供されたコールバックを実行します。

1expect($user)
2    ->unless($user->is_verified === true, fn ($user) => $user->daily_limit->toBe(10))
3    ->email->not->toBeEmpty();

期待値の書き方を学んだら、ドキュメントの次のセクション「Hooks」では、テストの前提条件を設定したりクリーンアップアクションを実行するために使用できる "beforeEach" や "afterEach" のような便利な関数について説明しています: Hooks →