README

atoum

一个简单、现代且直观的PHP单元测试框架！

就像SimpleTest或PHPUnit一样，atoum是针对PHP语言的一个单元测试框架。然而，它从一开始就考虑到了以下想法：

• 可以快速实现
• 简化测试开发
• 允许编写可靠、可读且清晰的单元测试

为了实现这一点，它大量使用由PHP提供的功能，为开发者提供一种全新的编写单元测试的方式。因此，它可以非常容易地安装并集成到现有项目中，因为它只是一个单个PHAR归档，这是开发者的唯一入口点。此外，由于其流畅的接口，它允许以接近自然语言的方式编写单元测试。它还通过智能使用匿名函数和闭包来简化测试中的存根实现。默认情况下，atoum会在一个单独的PHP进程中执行每个单元测试，以确保隔离。当然，它可以无缝用于持续集成，并且由于其设计，它可以非常容易地适应特定需求。由于它被开发成在具有较小的内存占用同时允许加速测试执行，因此atoum不会影响性能。它还可以生成XUnit格式的单元测试执行报告，这使得它可以与Jenkins等持续集成工具兼容。此外，atoum还生成代码覆盖率报告，以便监督单元测试。最后，尽管它主要在UNIX上开发，但它也可以在Windows上运行。

为什么选择atoum？

• atoum 真的是非常 易于安装：从 GitHub 克隆它，下载 其 PHAR 文件，或者简单地 使用 Composer。
• atoum 在测试执行过程中通过将每个测试方法隔离在其自己的 PHP 进程中来提供高级别的安全性。当然，这个特性是开箱即用的，无需安装任何额外的扩展。
• atoum 在并行环境中运行测试，通过利用当今的多核 CPU 来尽可能快地运行测试套件。
• atoum 提供了一组功能齐全的自然和表达性断言，使测试尽可能易于阅读。以下是一个示例

<?php

$this
    ->integer(150)
        ->isGreaterThan(100)
        ->isLowerThanOrEqualTo(200)
;

• atoum 支持类似 BDD 的语法，以及许多结构化关键字。

<?php

$this
    ->given($testedInstance = new testedClass())
    ->and($testedClass[] = $firstValue = uniqid())
    ->then
        ->sizeof($testedInstance)->isEqualTo(1)
        ->string($testedClass[0])->isEqualTo($firstValue)
;

• atoum 提供了一个简单但非常强大的 模拟引擎。

<?php

$this
    ->given($testedInstance = new testedClass())
    ->and($aMock = new \mock\foo\bar()) // here a mock of the class \foo\bar is created dynamically
    ->and($this->calling($aMock)->doOtherThing = true) // each call to doOtherThing() by the instance will return true
    ->and($testedInstance->setDependency($aMock))
    ->then
        ->boolean($testedInstance->doSomething())->isTrue()
        ->mock($aMock)
            ->call('doOtherThing')->withArguments($testedInstance)->once() // Asserts that the doOtherThing() method of $aMock was called once
;

• atoum 提供了一个清晰的 API 来断言异常。

<?php

$this
    ->given($testedInstance = new testedClass())
    ->and($aMock = new \mock\foo\bar()) // here a mock of the class \foo\bar is created dynamically
    ->and($this->calling($aMock)->doOtherThing->throw = $exception = new \exception()) // Call to doOtherThing() will throw an exception
    ->and($testedInstance->setDependency($aMock))
    ->then
        ->exception(function() use ($testedInstance) { $testedInstance->doSomething(); })
            ->isIdenticalTo($exception)
;

• atoum 还允许您模拟原生 PHP 函数。同样，这也是开箱即用的。

<?php

$this
    ->given($this->function->session_start = false)
    ->and($session = new testedClass())
    ->then
        ->exception(function () use ($session) { $session->start(); })
            ->isInstanceOf('project\namespace\exception')
            ->hasMessage('Unable to start session')
        ->function('session_start')->wasCalled()->once()
;

• atoum 能够生成多种报告，如 TAP、clover、xUnit，可以轻松集成到 Jenkins 或任何其他持续集成工具中。
• atoum 支持 数据提供者。
• atoum 测试支持自动运行：只需包含 atoum 运行器，然后使用 php path/to/test/file.php 启动您的测试。
• atoum 的 配置文件 专门用 PHP 编写（没有 XML、YAML 或任何其他格式），为您提供最佳灵活性。

<?php

$script->addDefaultArguments('--test-it', '-ncc');

$runner->addTestsFromDirectory(__DIR__ . '/tests/units/classes');

$testGenerator = new atoum\atoum\test\generator();
$testGenerator
    ->setTestClassesDirectory(__DIR__ . '/tests/units/classes');
    ->setTestClassNamespace('atoum\atoum\tests\units');
    ->setTestedClassesDirectory(__DIR__ . '/classes');
    ->setTestedClassNamespace('atoum\atoum')
    ->setRunnerPath(__DIR__ . '/scripts/runner.php')
;

$runner->setTestGenerator($testGenerator);

• atoum 提供了一个自动测试模板生成器。
• atoum 提供了一个 循环模式，可以轻松重新触发失败的测试。
• atoum 充满了其他有趣的特性，您将在使用过程中发现它们。

使用 atoum 的先决条件

atoum 绝对需要 PHP >= 5.6.0 或更高版本才能运行。在 UNIX 上，为了检查您是否安装了正确的 PHP 版本，您只需在终端运行以下命令

$ php -v | grep -oE 'php 5\.3\.(?:[3-9]|[1-9][0-9])|5\.[4-6]\.[0-9]+|[5-8]\.[0-9]+\.[0-9]+'

如果显示 PHP 5.6.x 或等效版本，则表示您已安装了正确的 PHP 版本。如果您想使用 atoum 的 PHAR 存档来使用它，您还需要 PHP 能够访问 phar 模块，这通常默认可用。在 UNIX 上，为了检查您是否安装了此模块，您只需在终端运行以下命令

$ php -m | grep -i phar

如果显示 Phar 或等效版本，则表示该模块已正确安装。生成 Xunit 格式的报告需要 xml 模块。在 UNIX 上，为了检查您是否安装了此模块，您只需在终端运行以下命令

$ php -m | grep -i xml

如果显示 Xml 或等效版本，则表示该模块已正确安装。如果您希望通过单元测试监控代码的覆盖率，则需要 Xdebug 2.3 模块。在 UNIX 上，为了检查您是否安装了此模块，您只需在终端运行以下命令

$ php -v | grep -oi 'xdebug'

如果显示 Xdebug 或等效版本，则表示该模块已正确安装。

一个可以在 5 分钟内启动的单元测试框架！

第 1 步：安装 atoum

您只需要下载 其PHAR存档，并将其存储在您希望的位置，例如在 /path/to/project/tests/atoum.phar 之下。这个PHAR存档包含通过所有 atoum 单元测试的最新开发版本。atoum 的源代码也通过 GitHub仓库 提供。为了检查 atoum 是否与您的配置正确工作，您可以执行所有单元测试。要做到这一点，您只需要在终端运行以下命令

$ php atoum.phar --test-it

步骤2：编写测试

使用您喜欢的文本编辑器，创建文件 path/to/project/tests/units/helloWorld.php 并添加以下代码

<?php

namespace vendor\project\tests\units;

require_once 'path/to/atoum.phar';

include_once 'path/to/project/classes/helloWorld.php';

use atoum\atoum;
use vendor\project;

class helloWorld extends atoum\test
{
    public function testSay()
    {
        $helloWorld = new project\helloWorld();

        $this->string($helloWorld->say())->isEqualTo('Hello World!');
    }
}

步骤3：使用命令行运行测试

启动您的终端并运行以下命令

$ php path/to/test/file[enter]

您应该得到以下结果或类似的结果

> atoum version XXX by Frédéric Hardy.
Error: Unattended exception: Tested class 'vendor\project\helloWorld' does not exist for test class 'vendor\project\tests\units\helloWorld'

步骤4：编写与测试对应的类

再次使用您喜欢的文本编辑器，创建文件 path/to/project/classes/helloWorld.php 并添加以下代码

<?php

namespace vendor\project;

class helloWorld
{
    public function say()
    {
        return 'Hello World!';
    }
}

步骤5：再次运行测试

在同一个终端中，再次运行以下命令

$ php path/to/test/file[enter]

您应该得到以下结果或类似的结果

> atoum version 288 by Frédéric Hardy.
> Run vendor\project\tests\units\helloWorld...
[S___________________________________________________________][1/1]
=> Test duration: 0.00 second.
=> Memory usage: 0.25 Mb.
> Total test duration: 0.00 second.
> Total test memory usage: 0.25 Mb.
> Code coverage value: 100.00%
> Running duration: 0.08 second.
> Success (1 test, 1 method, 2 assertions, 0 error, 0 exception)!

步骤6：完成测试并从步骤3重新开始循环

<?php

namespace vendor\project\tests\units;

require_once 'path/to/atoum.phar';

include_once 'path/to/project/classes/helloWorld.php';

use atoum\atoum;
use vendor\project;

class helloWorld extends atoum\test
{
    public function test__construct()
    {
        $helloWorld = new project\helloWorld();

        $this
            ->string($helloWorld->say())->isEqualTo('Hello!')
            ->string($helloWorld->say($name = 'Frédéric Hardy'))->isEqualTo('Hello ' . $name . '!')
        ;
    }
}

要了解更多

atoum 的文档 正在编写中。任何有助于改进它的帮助都将受到赞赏。然而，如果您想立即进一步探索 atoum 的可能性，我们建议

• 在终端中运行命令 php atoum.phar -h 或命令 php scripts/runner.php -h,
• 探索 atoum 源代码中 configurations 目录的内容，因为它包含配置文件样本,
• 探索 atoum 源代码中 tests/unit/classes 目录的内容，因为它包含所有的单元测试,
• 阅读关于它的（法语）会议幻灯片，可在网上找到,
• 阅读（法语）wiki,
• 加入 讨论频道,
• 通过电子邮件在 support[AT]atoum(DOT)org 地址提问。

故障排除

atoum 的PHAR存档似乎无法工作

在这种情况下，您首先想要做的是确认您是否有存档的最新版本。您只需要再次 下载 它。如果仍然不起作用，请在终端窗口中运行以下命令

$ php -n atoum.phar -v

如果您得到 atoum 的版本号，那么问题来自您的PHP配置。在大多数情况下，原因可能是扩展不兼容PHAR格式，或者出于安全措施防止执行PHAR存档。例如，ioncube 扩展似乎与PHAR存档不兼容，如果您正在使用它，则必须通过在 php.ini 中注释掉以下行来禁用它，通过在前面加上 ; 字符

zend_extension = /path/to/ioncube_loader*.*

suhosin 扩展防止执行PHAR存档，因此必须修改其默认配置才能使用 atoum，在您的 php.ini 文件中添加以下行

suhosin.executor.include.whitelist="phar"

最后，如果运行 atoum 导致屏幕显示类似 ???% 的字符，这将是由于您的 php.ini 文件中的 detect_unicode 指令设置为1。要解决这个问题，您只需通过编辑 php.ini 文件或在运行 atoum 时使用以下命令将其设置为0

$ php -d detect_unicode=0 atoum.phar [options]

如果这三个操作不允许 atoum 运行，我们建议您将电子邮件发送到地址 support[AT]atoum(DOT)org，详细描述您的配置和问题。您还可以在 atoum 仓库的 讨论频道 中寻求开发人员的帮助。

错误：常量 __COMPILER_HALT_OFFSET__ 已在 /path/to/atoum.phar 中定义

这个错误是由于 atoum PHAR 归档在您的代码中使用 include 或 require 在多个地方被包含。要修复这个问题，您只需要使用 include_once 或 require_once 包含归档，以确保它不会重复包含。

APC 似乎与 atoum 不兼容

APC 是一个免费、开源且健壮的缓存和优化 PHP 中间代码的框架，以 PHP 扩展的形式分发。在测试使用 APC 的类时，您可能会得到一些错误信息，表明 apc_fetch 函数无法检索值。和所有 PHP 扩展一样，APC 有一些配置选项可以启用它。

• apc.enabled 是否启用或禁用 APC，
• apc.enable_cli，是否启用或禁用 PHP CLI 的 APC。

为了使用 APC 与 atoum 一起，您必须将 apc.enabled 和 apc.enable_cli 设置为 1，否则它将不会为用于 atoum 的 PHP CLI 版本启用。

模拟对象时出现段错误

当使用 atoum 和模拟对象时，您有时会得到来自 PHP 的段错误。这些段错误是由小于 2.1.0 版本的 XDebug 引起的，它在某些情况下处理反射时存在问题。要检查当前版本的 XDebug，您可以运行 php -v。要修复此问题，您必须将 XDebug 更新到最新 稳定版本。如果您无法在您的系统上更新 XDebug，您还可以禁用扩展以避免出现段错误。要确保 XDebug 已成功更新或禁用，您可以运行 php -v。在您完成更新或禁用 XDebug 后，运行 php atoum.phar --test-it 以确保所有段错误都已解决且 atoum 正在运行。

路线图

寻找路线图？

• 这里 是正在进行的工作，
• 这里有 将在下一个版本中推出。

鸣谢

atoum 由 Frédéric Hardy 创建。它现在由一个强大的贡献者社区领导。您可以在 提交者列表 或在 贡献者团队 中找到他们。

许可

atoum 在 BSD-3-Clause 许可下发布。有关详细信息，请参阅捆绑的 LICENSE 文件。