README

实用的测试。在项目根目录下运行路径 ./themis-tests/ 中的所有PHP文件。如果任何断言失败，或者没有处理任何异常，或者将任何内容写入错误日志 - 则被视为错误。

Themis还可以将PHP脚本的输出与文件进行比较，并将任何差异记录为错误。

Themis可以运行以.phpt为扩展名的PHP语言测试套件文件。

错误条件

一般来说，如果脚本仅通过使用echo、print()、fwrite(STDERR, ...)或fwrite(STDOUT, ...)写入标准输出或标准错误而完成，则测试被视为成功。

以下事件被视为失败

• 如果使用PHP测试函数assert()并检测到错误。
• 如果没有抛出预期异常。
• 如果抛出任何异常且未被全局错误处理器捕获。
• 如果使用error_log()函数记录任何内容。
• 如果向STDERR流写入任何内容。
• 如果命令退出且退出代码大于0，使用exit(int $code)。

测试还可以通过将STDOUT和STDERR日志与验证文件进行比较来执行。如果您正在测试诸如事件发生的顺序之类的语义，这非常有用。

编写测试

测试编写在项目根目录下的./charm-tests/文件夹中。测试脚本只是像这样的普通PHP文件

正常运行时错误

<?php
// triggers a division by zero
echo 1/0;

断言

assert()函数是一个美丽的PHP函数，专为测试设计。美丽之处在于，此函数在生产中没有任何性能开销，因为PHP解释器将自动删除它。因此，您应该经常使用assert()命令；尤其是当您测试的函数的输入直接来自您的内部逻辑时。绝对不要用它来验证用户输入（因为函数在生产中将被忽略）。

<?php
// Triggers warning "Undefined variable $test"
assert($test === NULL, 'Variable $test is not NULL`);

运行测试

我们建议将themis脚本添加到您的composer.json文件中

    "scripts": {
        "test": "@php vendor/bin/charm-testing"
    },
    "script-descriptions": {
        "test": "Run testing"
    }

接下来，您只需从命令行运行命令composer test

> composer test

注意如果您想向Charm/Testing传递参数，您必须将针对composer的参数与针对charm-testing的参数分开

composer test -- --help将提供charm-testing的参数帮助composer test --help将提供composer的参数帮助

或者您可以直接运行命令./vendor/bin/charm-testing。

运行特定测试

如果您只想运行特定测试，您可以提供测试文件名的部分作为参数

composer test KEYWORD

这将递归地扫描./charm-tests/文件夹，并且只运行包含路径中字符串KEYWORD的测试。

自动化测试

如果任何测试失败，则该工具提供错误退出代码。

编写最小测试

测试以普通PHP文件的形式编写在./charm-tests/文件夹中。

<?php
assert(false, "Error");

此文件不使用任何依赖关系，并依赖于PHP内置函数assert()。assert()函数本质上只是检查第一个参数是否为真，或者将触发由第二个参数提供的错误字符串。

您可以在代码中使用assert()而不用担心性能影响，因为该命令是专为测试设计的PHP语言构造。使用PHP的默认配置，assert()函数被PHP完全忽略。

验证输出序列

有时，您想测试一些语义或事物的输出顺序。Charm/Testing可以通过创建与脚本同名的一个文件来配置，从而检查STDOUT或STDERR的输出。

some-test.php应该有一个some-test.php.STDOUT文件来验证STDOUT，以及一个some-test.php.STDERR文件来验证STDERR。

以下示例创建了一个“测试”，它将失败50%的时间。

<?php
if (mt_rand(0,1) === 0) {
    echo "SUCCESS\n";
} else {
    echo "FAILURE\n";
}

为确保只记录SUCCESS\n作为正测试结果，您可以在命令行使用以下命令捕获输出

> php my-test-file.php > my-test-file.php.STDOUT

这将创建一个包含成功运行测试的预期输出的文件。

编写测试

在项目根目录中创建一个charm-tests/文件夹。测试包含在简单的PHP文件中，这些文件返回类似下面的数组

<?php return [
    /**
     * First array item is a string that describes the test.
     */
    "Test description",

    /**
     * Second item is a function which performs the testing. The function
     * must return data which will be compared to the expected result.
     */
    function($data) {
        // perform your test and return a value
        return strtoupper($args);
    },

    /**
     * The next items are arrays of testing criteria and their expected result
     */
    [ "hello world",        "HELLO WORLD" ],        // succeeds
    [ "blåbærsyltetøy",     "BLåBæRSYLTETøY" ],     // succeeds
    [ "blåbærsyltetøy",     "BLÅBÆRSYLTEDØY" ],     // fails, but is the correct result

];


The test report
---------------

The test report contains the date and the result of all the tests with a nice
side-by-side diff highlighting the difference between the expected result and
the actual result.

Running the tests
-----------------

Run the function `vendor/bin/charm-testing` and you will see the tests being performed.
The output is a markdown file that you can save for future reference.


Simple Automation Example
-------------------------

The `charm-testing` command can easily be automated in various contexts, because it
provides an exit code which indicates the percentage of failed tests rounded up.

 * If no tests failed, the exit code is `0`.
 * If all tests failed, the exit code is `100`.
 * If 1 test failed, the exit code is `1` (or `100` if you only have
   one test. ;-)

Invoking the tests from PHP:

exec('exec /usr/bin/env vendor/bin/charm-testing', $output, $exitCode); if ($exitCode > 0) {

// some tests failed!

}

Handling failed tests from the command line:

./vendor/bin/charm-testing || echo "Some tests failed!"

or

if [[ ! $(./vendor/bin/charm-testing) ]]; then

echo "Some tests failed"

fi