atoum

原子

PHP版本	原子版本
5.3 -> 5.6	1.x -> 3.x
7.2 -> 8.1	4.X -> 4.1
8.x	4.1 < 4.X（当前）

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

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

• 可以快速实施，

• 简化测试开发，

• 允许编写可靠、可读且清晰的单元测试。

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

为什么是原子？

• atoum确实很容易安装：从 github 克隆它，下载它的 PHAR 或简单地使用 Composer，

• atoum通过将每个测试方法隔离在其自己的 PHP 进程中，在测试执行期间提供高级别的安全性。当然，这个功能是开箱即用的，不需要安装任何额外的扩展，

• atoum在并行环境中运行测试，利用当今的多核 CPU，使套件尽可能快地运行，

• atoum提供了一组功能齐全的自然且富有表现力的断言，使测试尽可能具有可读性。这是一个例子：

 <?php$this->整数(150)
        ->大于(100)
        ->低于或等于(200)
;

• atoum支持带有大量结构关键字的类似 BDD 的语法：

 <?php$this->given($testedInstance = 新的testedClass())
    ->and($testedClass[] = $firstValue = uniqid())
    ->然后->sizeof($testedInstance)->isEqualTo(1)
        ->string($testedClass[0])->isEqualTo($firstValue)
;

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

 <?php$this->given($testedInstance = 新的testedClass())
    ->and($aMock = new mockfoobar()) // 这里动态创建了 foobar 类的模拟 ->and($this->calling($aMock)->doOtherThing = true) // 每次调用 doOtherThing( ) 实例将返回 true->and($testedInstance->setDependency($aMock))
    ->然后->boolean($testedInstance->doSomething())->isTrue()
        -> 模拟（$aMock）
            ->call('doOtherThing')->withArguments($testedInstance)->once() // 断言 $aMock 的 doOtherThing() 方法被调用一次；

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

 <?php$this->given($testedInstance = 新的testedClass())
    ->and($aMock = new mockfoobar()) // 这里动态创建了 foobar 类的模拟->and($this->calling($aMock)->doOtherThing->throw = $exception = new exception( )) // 调用 doOtherThing() 会抛出异常->and($testedInstance->setDependency($aMock))
    ->然后->异常(function() use ($testedInstance) { $testedInstance->doSomething(); })
            ->isIdenticalTo($异常)
;

• atoum还允许您模拟本机 PHP 函数。同样，这是开箱即用的：

 <?php$this->given($this->function->session_start = false)
    ->and($session = 新的testedClass())
    ->然后->异常(function () use ($session) { $session->start(); })
            ->isInstanceOf('projectnamespaceexception')
            ->hasMessage('无法启动会话')
        ->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 atoumatoumtestgenerator();$ testGenerator->setTestClassesDirectory(__DIR__ . '/tests/units/classes');
    ->setTestClassNamespace('atoumatoumtestsunits');
    ->setTestedClassesDirectory(__DIR__ . '/classes');
    ->setTestedClassNamespace('atoumatoum')
    ->setRunnerPath(__DIR__ . '/scripts/runner.php')
;$runner->setTestGenerator($testGenerator);

• atoum提供了一个自动测试模板生成器，

• atoum提供了循环模式来轻松重新触发失败的测试，

• atoum还充满了其他有趣的功能，随着时间的推移，您会发​​现这些功能。

使用atom的先决条件

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

 $ php -v | php 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 | php grep -oi 'xdebug'

如果显示Xdebug或同等内容，则模块已正确安装。

5分钟即可运行的单元测试框架！

第1步：安装atom

您只需下载其 PHAR 存档并将其存储在您想要的位置，例如/path/to/project/tests/atoum.phar下。该 PHAR 存档包含通过atoum全部单元测试的最新开发版本。 atoum的源代码也可以通过 GitHub 存储库获取。要检查atoum是否可以在您的配置下正常工作，您可以执行其所有单元测试。为此，您只需在终端中运行以下命令：

 $ php atoum.phar --测试它

第 2 步：编写测试

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

 <?phpnamespacevendorprojecttestsunits;require_once'path/to/atoum.phar';include_once'path/to/project/classes/helloWorld.php';use atoumatoum;usevendorproject;class helloWorld扩展atoumtest
{公共函数testSay()
    {$helloWorld = new projecthelloWorld();$this->string($helloWorld->say())->isEqualTo('Hello World!');
    }
}

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

启动终端并运行以下命令：

 $ php 路径/到/测试/文件[输入]

您应该得到以下结果或等效结果：

 > 原子版本 XXX，作者：Frédéric Hardy。
错误：无人参与的异常：测试类“vendorprojecttestsunitshelloWorld”不存在测试类“vendorprojecthelloWorld”

第四步：编写与您的测试相对应的类

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

 <?php命名空间vendorproject;class helloWorld
{公共函数说()
    {return '你好世界！';
    }
}

第 5 步：再次运行测试

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

 $ php 路径/到/测试/文件[输入]

您应该得到以下结果或等效结果：

 > Atoum 版本 288，作者：Frédéric Hardy。> 运行vendorprojecttestsunitshelloWorld...
[S_______________________________________________________________][1/1]
=> 测试持续时间：0.00 秒。
=> 内存使用量：0.25 Mb。> 总测试持续时间：0.00 秒。> 总测试内存使用量：0.25 Mb。> 代码覆盖率值：100.00%> 运行持续时间：0.08 秒。> 成功（1 个测试、1 个方法、2 个断言，0 个错误，0 个异常）！

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

<?phpnamespacevendorprojecttestsunits;require_once'path/to/atoum.phar';include_once'path/to/project/classes/helloWorld.php';use atoumatoum;usevendorproject;class helloWorld扩展atoumtest
{公共函数test__construct()
    {$helloWorld = new projecthelloWorld();$this->string($helloWorld->say())->isEqualTo('你好！')
            ->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目录的内容，因为它包含所有单元测试，

• 阅读有关它的（法语）会议幻灯片，可在线获取，

• 阅读（法语）维基，

• 加入讨论频道，

• 通过电子邮件提问，地址为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。要解决此问题，只需将其设置为 0编辑php.ini文件或使用以下命令运行atoum ：

 $ php -d detector_unicode=0 atoum.phar [选项]

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

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

此错误是由于使用include或require将atoum PHAR 存档包含在代码中的多个位置这一事实造成的。要解决此问题，您只需使用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正在工作。

---

路线图

正在寻找路线图？

• 这是正在进行的工作，

• 下一个版本中将会出现这些内容。

制作人员

原子是由弗雷德里克·哈代 (Frédéric Hardy) 创建的。它现在由强大的贡献者社区领导。您可以在提交者列表或贡献者团队中找到他们。

执照

atoum 是根据 BSD-3-Clause 许可证发布的。有关详细信息，请参阅捆绑的许可证文件。