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”一词，但它没有出现。该测试用例失败了，但是您可以知道示例代码有问题并且可以修复它。

它是如何运作的？

Livexample 执行以下步骤：

1. 通过解析示例代码中找到Output语句。
2. 在 PHPUnit 中运行代码并捕获输出。
3. 比较预期输出和实际输出。

好处

有时，示例代码会被破坏，例如添加新功能、忘记更新它们、拉取请求不处理示例代码等等。

损坏的示例代码对于图书馆用户来说是糟糕的体验。

通过使用 Livexample，您将获得以下好处：

• 您的示例代码受到保护，不会出现意外回归。
• 您可以轻松检查示例代码是否有效。
• 您的库用户可以通过复制和粘贴来使用有效的示例代码。
• 您不必对现有示例代码进行重大更改；只是添加一些评论。

特征

• Livexample 是 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

断言语法

断言有两种语法：

• 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 环境仍然保留在今天的运行服务中。 Livexample 也应该用于重构此类旧环境。

变更日志

请参阅变更日志了解更多详细信息。

贡献

请参阅贡献了解更多详细信息。请修正我的英语。