README

使用说明

需要安装的包

composer require pretzlaw/phpunit-docgen

在你的phpunit.xml中写入以下内容

<listeners>
    <listener class="Pretzlaw\PHPUnit\DocGen\TestCaseListener">
        <arguments>
            <string>test-evidence.md</string>
        </arguments>
    </listener>
</listeners>

它将输出所有文档注释的精美markdown格式。在运行集成测试时，这将为单元测试或某种类型的文档提供良好的测试证据。

示例/最佳使用

假设你需要描述一个API或向客户交付一些由单元测试/集成测试保证的测试证据...

• tests/
  • FooController/
    • CreateTest.php
    • ShowTest.php
    • ...
  • FooControllerTest.php

只需要几个文档注释就可以生成这些文档。以下是由测试的文档注释生成的（Tests\FooControllerTest完成了这个操作）

# Foo Fighters

This is an API for managing Foo. It allows:

- Create
- Read

Tests\FooController\CreateTest添加了这个

## How to create a new one?

Creating is easy as long as you stick to the range.

### Request

Do `POST /foo` with some data.

Tests\FooController\ShowTest添加了这个

## Read out all foo

### Restrictions

You can't see more than five. This is because ...

At least one will be at the drums. Because ...

标题和文本

在FooControllerTest.php中，我们有

namespace Tests;

/**
 * Foo Fighters
 *
 * This is an API for managing Foo. It allows:
 *
 * - Create
 * - Read
 *
 * @since 1994
 */
class FooControllerTest {}

这就是变成第一个部分的内容（参见上面的示例文档）。它只是将没有@属性的文档注释放入输出中。

深度/结构

子部分将通过解析命名空间和（之后）测试包含的方法来创建

namespace Tests\FooController;

/**
 * How to create a new one?
 * 
 * Creating is easy as long as you stick to the range.
 *
 */
class CreateTest {
  /**
   * Request
   *
   * Do `POST /foo` with some data.
   *
   */
  function testBar() {
    $this->assertTrue( (new FooController)->create() );
  }
}

这就是第二个部分的创建方式（参见上面）。

将内容追加到另一个标题

当你在一个测试中时，意味着你在测试一个上下文，所以有时你希望向某些标题添加文档。只需再次使用那些测试的标题即可

/**
 * Read out all foo
 *
 */
class ShowTest {

  /**
   * Restrictions
   *
   * You can't see more than five. This is because ...
   */
  function testBar() {}
  
  
  /**
   * Restrictions
   *
   * At least one will be at the drums. Because ...
   */
  function testBaz() {}
}

忽略一个方法或类/不在文档中打印

• 用@internal标记。
• 没有标题或内容的注释也会被忽略。

感谢！