README

这是一个面向文档的测试框架，适用于从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. 比较预期输出和实际输出。

优势

有时示例代码会因添加新功能、忘记更新、提交的pull-requests未注意示例代码等原因而出现错误。

损坏的示例代码会给库用户带来不好的体验。

使用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

断言语法

有两种断言语法

• 长： // 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也支持用于重构这样的旧环境。

变更日志

请参阅变更日志获取更多详细信息。

贡献

请参阅贡献指南获取更多详细信息。请修复我的英语 😂。