livexample

ライブサンプル

これは、PHP 5.3 から 7.x までのドキュメント指向のテスト フレームワークです。その目的は、単体テストによってサンプル コードが動作することを確認することです。 Golang テストの「例」からインスピレーションを受けました。

簡単なテストケースの例

以下の例を参照してください。最初のセクションはテストされるサンプルコードです。 Outputで始まるコメントはテストコードです。

 <?php

function hello ( string $ name ): string {
	return ' hello ' . $ name ;
}
echo hello ( ' alice ' ) . "n" ;
echo hello ( ' bob ' ) . "n" ;

// Output:
// hello alice
// hello carol

このサンプルコードは壊れています。 「carol」という単語が出力として期待されていますが、表示されません。このテスト ケースは失敗しますが、サンプル コードに問題があることがわかり、それを修正できる可能性があります。

どのように機能するのでしょうか?

Liveexample は次の手順を実行します。

1. サンプル コード内のOutputステートメントを解析して見つけます。
2. PHPUnit でコードを実行し、出力をキャプチャします。
3. 予想される出力と実際の出力を比較します。

利点

新しい機能の追加、更新の忘れ、サンプル コードを考慮しないプルリクエストなどにより、サンプル コードが壊れることがあります。

サンプル コードが壊れていると、ライブラリ ユーザーにとっては不快な経験になります。

Liveexample を使用すると、次のようなメリットが得られます。

• サンプルコードは予期せぬリグレッションから保護されています。
• サンプルコードが有効であるかどうかを簡単に確認できます。
• ライブラリのユーザーは、コピーして貼り付けることで有効なサンプル コードを使用できます。
• 既存のサンプル コードに大きな変更を加える必要はありません。いくつかのコメントを追加するだけです。

特徴

• Liveexample は PHPUnit の一部として動作します。
• 学習コストが非常に低い。

はじめる

Composer 経由でsuin/livexampleをインストールします。

 composer require --dev suin/livexample

ExampleTest.phpテスト ディレクトリに追加します。

 use Livexample  PHPUnit  ExampleTestCase ;

class ExampleTest extends ExampleTestCase
{
    public function exampleFiles ()
    {
        // specify your example code directory.
        return self :: exampleDirectory ( ' example ' );
    }
}

phpunit を実行します。

 phpunit

アサーション構文

アサーションには 2 つの構文があります。

• Long: // Output: {expected output}
• 短い: //=> {expected output}

 echo 1 ; // Output: 1 

 echo " hello " ; //=> hello 

 var_dump ([ 1 , 2 , 3 ]);
// Output:
// array(3) {
// 	[0] =>
// 	int(1)
// 	[1] =>
// 	int(2)
// 	[2] =>
// 	int(3)
// } 

ヒント: var_dump($object)

var_dump()関数は、クラス名の横にある#some-numberであるオブジェクト識別子を出力します。識別子は実行環境に依存するため、 Output:ステートメントでハードコーディングすることはできません。識別子をハードコーディングする代わりに、数値にプレースホルダー%d使用できます。

 <?php
var_dump ( new stdClass );
// Output:
// object(stdClass)#%d (0) {
// } 

ヒント: phpコマンドを使用してサンプル スクリプトを実行する

 php -d auto_prepend_file=vendor/autoload.php 
    -d xdebug.overload_var_dump=0 
    example/simple-usage.php

2017 年に PHP 5.3 をサポートするのはなぜですか?

PHP 5.3 の正式サポートは終了しましたが、RHEL/CentOS は 2017 年現在でも PHP 5.3 をサポートし続けています。古い PHP 環境は現在もサービスとして残っています。 Liveexample は、そのような古い環境をリファクタリングするために使用することも想定されています。

変更履歴

詳細については、CHANGELOG を参照してください。

貢献する

詳細については、「貢献」を参照してください。私の英語を直してください。