README

该包旨在在执行测试的同时生成README文件。为了使其工作，您需要在测试方法内部调用它。因此，它不会自动将每个测试方法转换为README文件。

安装和配置

sail composer require bakgul/laravel-tests-to-readme --dev

sail artisan vendor:publish --tag=to-readme-config

现在，您可以在发布配置文件（'to-readme.php'）后更改设置。

最后，我们需要一个文件夹来存储README文件。您可以按自己的意愿命名，但它必须位于测试类路径下的某个文件夹中。例如，如果您的测试类在

base_path('tests/Feature/EndpointTests/UserEndpointTests')

那么您可以在

base_path() 或 base_path('tests') 或 base_path('tests/Feature') 等。

一些注意事项

我建议您将README文件夹放在根级别。话虽如此，每个文件将根据测试类命名。因此，如果您有多个具有相同名称的类，您不能为它们所有使用 base_path('readme')。在这种情况下，您可能需要创建多个README文件夹。
此包不会生成最终的 README.md 文件。您需要手动创建它。
当您调用此包添加新测试时，您的新方法将被添加到目标文件中。
您可以修改输出，因为一旦打印出来，它就不会被覆盖。
当您重命名测试方法时，它将被添加到目标文件中。但是您需要手动删除旧的一个。
您可以在代码块之间添加段落、列表、表格。它们将被保留。

它是如何工作的

您应该在测试方法中调用此包。

class MyClassTest extends TestCase
{
    /** @test */
    public function my_test_method_does_things(): void
    {
        (new ToReadme([
            'test' => $this->getName();
            'class' => MyClass::class,
            'method' => 'doSomething',
            'args' => [1, 2],
            'message' => 'Anything you want to print.',
            'result' => 3
        ]))->write();

        // Your test ...
    }
}

上面的代码将生成一个 readme/MyClass.md 文件，并将内容放在下面的水平线之间。

MyClass

doSomething

/**
 * If you have Phpdoc, it will be displated here
 */
public function doSomething(int $num1, int $num2): int

// My test method does things.

// Anything you want to print.

(new MyClass)->doSomething(1, 2);

// 3

如您所注意到的，我们传递了一个值作为结果，并且在代码块中打印了它。我建议您这样做，但您不必指定方法的输出。当“result”键不存在时，我们将尝试执行方法并生成输出以打印。

Phpdoc 与 Typehint

此包可以使用两者生成文件。如果您将 merge_phpdoc_and_method_declaration => true，我们将从Phpdoc移动类型到Typehint。否则，我们不会做任何改变。

下面的方法

/**
 * It does some stuff
 * 
 * @param array $arr
 * @param int   $int
 * @return array
 */
 public function do($arr, $int) { return [$arr, $int]; }

将被打印成这样

/**
 * It does some stuff
 */
 public function do(array $arr, int $int): array

当您同时使用它们，并且Phpdoc和Typehint之间存在不一致时，将打印一条警告消息。下面的方法

/**
 * It does some stuff
 * 
 * @param array $arr
 * @return array
 */
 public function do(array|string $arr) { return $arr; }

将被打印成这样

WARNINGS:
   - mismatched types.

/**
 * It does some stuff
 */
 public function do(array $arr, int $int): array

还有其他不一致性检查。您可以在 to-readme.php 中找到它们。

一些限制

如前所述，当您不传递 'result' 时，我们将尝试调用方法并获得输出。如果类有依赖项，它可能不会工作。在这种情况下，您最好手动指定结果。
方法返回的数组将被转换为Json字符串，然后通过某些字符替换修改，使其看起来像PHP数组。这可能在所有情况下都不会很好。
标识符标题级别不能在README中其他地方使用。
以'//'开头的第一行必须是测试方法的名称。
我找不到打印可调用参数的方法。因此，您需要手动添加它们。

许可证

这是一个开源软件，在MIT许可证下授权。

bakgul / laravel-tests-to-readme

维护者

详细信息