README

在 Markdown 中使用注释来自动将测试示例编译到您的 README 中。

警告

此包仍在开发中。它尚未准备好投入生产使用，API 可能随时更改。

安装

您可以通过 composer 安装此包

composer require luttje/php-example-tester

用法

1. 准备您的 README

在 README 中添加开始和结束注释，您希望每个示例单独出现的位置

### `exampleMethod`

Document the example method here, as you normally would.

**Here's the example code:**

<!-- #EXAMPLE_COPY_START = \Luttje\ExampleTester\Tests\Fixtures\ExampleClassTest::exampleMethod -->

This will be replaced with the example code.

<!-- #EXAMPLE_COPY_END -->

*🤓 Yay calculations!*

有关完整示例，请参阅 👀 示例 README 中的占位符。

您必须提供要复制的方法的完全限定路径。您也可以提供要复制整个类的完全限定路径。

2. 为该示例代码编写测试

在您的测试类中单独的静态方法中编写您的测试。然后，此包可以提取该方法的主体并将其用作示例代码。

use Luttje\ExampleTester\Tests\TestCase;

final class ExampleClassTest extends TestCase
{
    public static function exampleMethod(): void
    {
        // This is an example method.
        $a = 1;
        $b = 25;

        $c = $a + $b;

        echo $c;
        // This is the end of the example method.
    }

    /**
     * @test
     */
    public function testExampleMethod(): void
    {
        ob_start();
        self::exampleMethod();
        $output = ob_get_clean();

        $this->assertSame('26', $output);
    }
}

3. 将示例编译到您的 README 中

运行 example-tester 命令，使用 vendor/bin/example-tester compile 命令将示例编译到您的 README 中。

vendor/bin/example-tester compile

运行该命令后，示例将编译到您的 README 中。运行该命令后，您的 README 中的一个部分可能看起来像这样

exampleMethod

在此处记录示例方法，就像您通常做的那样。

以下是示例代码

// This is an example method.
$a = 1;
$b = 25;

$c = $a + $b;

echo $c;
// This is the end of the example method.

🤓 Yay calculations!

有关完整示例，请参阅 🏗 编译后的示例 README。

注意

您可以通过将 example-tester compile 命令添加到 composer.json 脚本来使工作流程更加顺畅。这样，您可以使用 composer compile-readme 运行它。

{
    "scripts": {
        "compile-readme": [
            "vendor/bin/example-tester compile"
        ]
    }
}

高级用法

您已经看到了标记示例开始的简单语法，但您还可以通过以 JSON 对象的形式向 #EXAMPLE_COPY_START 注释提供一些额外选项

<!-- #EXAMPLE_COPY_START = { "symbol": "\\Luttje\\ExampleTester\\Tests\\Fixtures\\ExampleClassTest::exampleMethod" } -->

等同于以下更简单的语法

<!-- #EXAMPLE_COPY_START = \Luttje\ExampleTester\Tests\Fixtures\ExampleClassTest::exampleMethod -->

但是，提供 JSON 对象可以解锁配置其他属性的能力，例如 short 属性。

short 属性

short 属性默认为 true，并确保仅将方法或类的主体复制到 README.md 文件中。

为方法设置 short

将 short 属性设置为 false 将还会将整个方法签名复制到 README.md 文件中的此结果

public static function exampleMethod(): void
{
    // This is an example method.
    $a = 1;
    $b = 25;

    $c = $a + $b;

    echo $c;
    // This is the end of the example method.
}

为类设置 short

对于类，将 short 设置为 false 以将整个类复制到 README.md 文件中的此结果可能更有意义

use Luttje\ExampleTester\Tests\TestCase;

final class ExampleClassTest extends TestCase
{
    public static function exampleMethod(): void
    {
        // This is an example method.
        $a = 1;
        $b = 25;

        $c = $a + $b;

        echo $c;
        // This is the end of the example method.
    }

    /**
     * @test
     */
    public function testExampleMethod(): void
    {
        ob_start();
        self::exampleMethod();
        $output = ob_get_clean();

        $this->assertSame('26', $output);
    }
}

忽略示例

特别是对于此包根目录中的 README，我们希望选择性地忽略示例。这可以通过在您希望不复制示例的 README 部分的周围包裹 <!-- #EXAMPLE_COPY_IGNORE_START --> 和 <!-- #EXAMPLE_COPY_IGNORE_END --> 注释来实现。

<!-- #EXAMPLE_COPY_IGNORE_START -->

#### Ignored example

This example will be ignored.

<!-- #EXAMPLE_COPY_START = { "symbol": "\\Luttje\\ExampleTester\\Tests\\Fixtures\\ExampleClassTest", "short": false } -->

Should not be removed.

<!-- #EXAMPLE_COPY_END -->

<!-- #EXAMPLE_COPY_IGNORE_END -->

命令行界面

该命令具有以下签名

compile [--output OUTPUT] [--input INPUT]

您必须从项目的根目录运行该命令。 这样命令就可以找到包含composer自动加载文件的供应商目录。

--output

要写入编译示例的README文件路径。默认为项目根目录下的README.md。

vendor/bin/example-tester compile --output DOCS.md

--input

读取示例的README文件路径。默认为--output路径。

测试

使用以下命令运行测试

composer test

许可证

MIT许可证（MIT）。请参阅许可证文件获取更多信息。