README

Archer 是一个库，使用约定优于配置的方法在多个项目中标准化PHP单元测试、持续集成和文档行为。它集合了几个高质量的库来帮助提高项目测试套件和报告工具的质量。

使用 Archer 需要主项目符合一系列约定。作为回报，它提供了以下好处

无需配置、最佳实践的单元测试和测试覆盖率报告，使用 PHPUnit 和 Xdebug。
无需配置，使用 Sami 生成 API文档。
自动配置仓库和 Travis CI。
构建工件发布到项目 GitHub Pages。
无需配置与 Codecov 集成，以实现出色的测试覆盖率指标。

要求

项目必须使用 Composer。
项目必须符合预期项目布局。
项目必须使用带有供应商和项目前缀的PHP命名空间，例如 Icecave\Archer。
PHPUnit 必须作为开发依赖项安装，或在用户的PATH中可用。
如果需要生成文档，Sami 必须作为开发依赖项安装，或在用户的PATH中可用。
需要 Xdebug PHP扩展才能生成测试覆盖率报告。
需要 openssl PHP扩展才能发布构建工件。

入门

预期项目布局

Archer 预期项目使用以下目录结构进行布局

.                 # Project / git root
├── src/          # PHP source files
└── test/
    └── suite/    # PHPUnit test suite

Composer配置

将 icecave/archer 添加到项目的 composer.json 文件中作为开发依赖项

composer require icecave/archer:^1 --dev

如果不存在，这将创建一个新的 composer.json 文件并更新所有依赖项。现在应该在 vendor/bin/archer 下可用 archer 可执行文件

vendor/bin/archer --version

初始化 Archer

使用更新命令设置 Git 仓库和 Travis CI 配置文件

vendor/bin/archer update --authorize

此命令将提示输入 GitHub 用户名和密码以授权 Archer 从 Travis CI 发布构建工件。有关安全性的更多信息，请参阅安全性部分的Woodhouse 文档。

Archer 做出的更改现在应该提交到仓库，并推送到 GitHub

git add -A
git commit -m 'Adding Archer integration.'
git push

好了！项目现在已设置好以使用 Archer。

单元测试

Archer 为单元测试提供对 PHPUnit 的包装。此命令的参数和选项传递给 PHPUnit。可以通过执行 archer 无参数来运行测试套件

vendor/bin/archer

没有参数运行 archer 等同于运行 archer test。

测试命令用法

vendor/bin/archer test                   # canonical form
vendor/bin/archer                        # shortcut to 'test' (no arguments or options allowed)
vendor/bin/archer t                      # shortcut to 'test'
vendor/bin/archer t --stop-on-failure    # arguments are forwarded to PHPUnit

示例测试命令输出

$ vendor/bin/archer
Using PHP: /path/to/php
Using PHPUnit: /path/to/phpunit
PHPUnit 4.7.7 by Sebastian Bergmann and contributors.

Runtime:        PHP 5.6.11 with Xdebug 2.3.3
Configuration:  /path/to/project/vendor/icecave/archer/res/phpunit/phpunit.xml

...............................................................  63 / 414 ( 15%)
............................................................... 126 / 414 ( 30%)
............................................................... 189 / 414 ( 45%)
............................................................... 252 / 414 ( 60%)
............................................................... 315 / 414 ( 76%)
............................................................... 378 / 414 ( 91%)
....................................

Time: 1 second, Memory: 14.00Mb

OK (414 tests, 915 assertions)

测试用例类自动加载

对于某些测试，测试替身不适合，需要使用测试用例类。因此，Archer 在测试时仅自动加载来自 test/src 目录的遵循 PSR-0 标准的任何类，以及通常由 Composer 加载的类。

测试覆盖率报告

测试覆盖率报告为确定项目测试程度提供了有用的指标。可以通过执行 archer coverage 来生成测试覆盖率报告。HTML 测试覆盖率报告将生成在 artifacts/tests/coverage 目录中，可以在任何网页浏览器中打开。

覆盖率命令用法

vendor/bin/archer coverage               # canonical form
vendor/bin/archer c                      # shortcut to 'coverage'
vendor/bin/archer c --stop-on-failure    # passing arguments to PHPUnit

示例覆盖率命令输出

$ vendor/bin/archer c
Using PHP: /path/to/php
Using PHPUnit: /path/to/phpunit
PHPUnit 4.7.7 by Sebastian Bergmann and contributors.

Runtime:        PHP 5.6.11 with Xdebug 2.3.3
Configuration:  /path/to/project/vendor/icecave/archer/res/phpunit/phpunit.coverage.xml

...............................................................  63 / 414 ( 15%)
............................................................... 126 / 414 ( 30%)
............................................................... 189 / 414 ( 45%)
............................................................... 252 / 414 ( 60%)
............................................................... 315 / 414 ( 76%)
............................................................... 378 / 414 ( 91%)
....................................

Time: 1 second, Memory: 17.00Mb

OK (414 tests, 915 assertions)

Generating code coverage report in HTML format ... done

示例测试覆盖率报告

有关实际示例，请参阅 Archer 自己测试套件的测试覆盖率报告。

Codecov 集成

Archer 提供对 Codecov 的支持。无需配置；当在 Travis CI 上构建时，Archer 将将测试覆盖率信息发布到 Codecov。

有关示例，请参阅 Archer 在 Codecov 上的内容。

API 文档

API 文档为任何项目的整体文档策略提供了一个有用的补充。可以通过执行 archer documentation 来生成静态、可搜索的 API 文档。API 文档将在 artifacts/documentation/api 目录下生成，可以在任何网页浏览器中打开。

请注意，API 文档的搜索面板使用 AJAX，而浏览器通常禁用本地文件对此。一种解决方案是使用 PHP 的内置服务器

php -S localhost:8000 -t artifacts/documentation/api

文档现在可在 http://localhost:8000/ 查看。

文档命令使用

vendor/bin/archer documentation    # canonical form
vendor/bin/archer d                # shortcut to 'documentation'

示例 API 文档

要查看实时示例，请参阅 API 文档，它为 Pathogen 提供。

自动化配置

Archer 提供了一个名为 update 的命令，用于帮助在多个项目中保持 Git 仓库和 Travis CI 配置的一致性。

生成的配置确保

Travis CI 知道如何运行测试、生成覆盖报告以及发布构建工件。
Travis CI 对所有相关的 PHP 版本进行构建。
由于 GitHub API 限制，Travis CI 的构建失败的可能性大大降低。
测试和构建工件被 Git 忽略。
项目的存档版本不包括测试套件等开发工件。

更新命令使用（不包含工件发布支持）

vendor/bin/archer update    # canonical form
vendor/bin/archer u         # shortcut to 'update'

构建工件发布

如果每个人都能看到 100% 的测试覆盖报告，那就太好了。这样就可以明显看出生产高质量产品投入了多少精力和努力。使用 Archer，这只需要授权一个项目即可。

要授权项目，只需使用带 --authorize 选项的 update 命令。该命令将提示输入 GitHub 用户名和密码，并使用这些信息创建一个加密配置文件，用于从 Travis CI 发布工件。

更新命令使用（包含工件发布支持）

vendor/bin/archer update --authorize    # canonical form
vendor/bin/archer u -a                  # shortcut to 'update --authorize'

发布的工件

一旦设置好授权，工件将在 Travis 构建仓库的默认分支下，在名为 artifacts 的目录中发布。

目录结构如下

artifacts/
├── images/         # Status shields/badges, organized by theme
└── tests/
    └── coverage/   # Test coverage reports

发布的测试覆盖报告

一旦发布，项目的测试覆盖报告就可通过 GitHub Pages 获取。例如，Archer 的覆盖报告发布在 http://icecavestudios.github.io/archer/artifacts/tests/coverage/。

上述 URL 会重定向到自定义域名，但仍通过 GitHub Pages 提供服务。

请注意，Archer 还会自动将覆盖率信息发布到 Codecov。建议尽可能链接到这些报告，而不是 Archer 发布的报告。

发布的测试覆盖率徽章

Archer 会发布状态盾牌/徽章，但这是一个遗留功能，现在推荐使用 Shields.io。

联系我们

关注 @IcecaveStudios 在 Twitter 上
访问 Icecave Studios 网站
加入 #icecave 在 irc.freenode.net

icecave / archer

维护者

详细信息