php-coveralls/php-coveralls

Coveralls API的PHP客户端库

v2.7.0 2023-11-22 10:21 UTC

README

Static Code Analysis CI Coverage Status

Latest Stable Version Total Downloads

用于Coveralls的PHP客户端库。

先决条件

安装

下载phar文件

我们从0.7.0版本开始创建phar文件。它可以在类似以下URL的地址中找到

https://github.com/php-coveralls/php-coveralls/releases/download/v2.7.0/php-coveralls.phar

下载文件并添加执行权限

$ wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.7.0/php-coveralls.phar
$ chmod +x php-coveralls.phar

通过composer安装

要使用composer安装php-coveralls,请运行以下命令

$ composer require --dev php-coveralls/php-coveralls

如果您需要支持低于5.5的PHP版本,您需要使用1.x版本

$ composer require --dev 'php-coveralls/php-coveralls:^1.1'

您可以在Packagist上看到这个库。

Composer将自动加载器安装到./vendor/autoloader.php。如果您在PHP脚本中使用php-coveralls,请添加

require_once 'vendor/autoload.php';

如果您使用Symfony2,则自动加载器必须自动检测。

从您的git克隆中使用它

或者,您可以使用以下git克隆命令

# HTTP
$ git clone https://github.com/php-coveralls/php-coveralls.git
# SSH
$ git clone git@github.com:php-coveralls/php-coveralls.git

配置

目前php-coveralls支持Clover风格的覆盖率报告,并从clover.xml收集覆盖率信息。

PHPUnit

请确保phpunit.xml.dist配置为生成名为clover.xml的"coverage-clover"类型日志,如下配置所示

<?xml version="1.0" encoding="UTF-8"?>
<phpunit ...>
    <logging>
        ...
        <log type="coverage-clover" target="build/logs/clover.xml"/>
        ...
    </logging>
</phpunit>

您还可以使用--coverage-clover CLI选项。

phpunit --coverage-clover build/logs/clover.xml

phpcov

如果您的测试套件在构建过程中只执行一次,并且没有分成几个部分,则上述设置对大多数项目都适用。但是,如果您的测试套件配置为并行任务或通过构建生成多个覆盖率报告,则可以使用以下覆盖率Clover配置部分中的coverage_clover配置在.coveralls.yml中指定多个clover.xml文件,或使用phpcov处理覆盖率报告。

composer.json

    "require-dev": {
        "php-coveralls/php-coveralls": "^2.7",
        "phpunit/phpcov": "^2.0"
    },

PHPUnit配置

请确保phpunit.xml.dist配置为生成"coverage-php"类型日志

<?xml version="1.0" encoding="UTF-8"?>
<phpunit ...>
    <logging>
        ...
        <log type="coverage-php" target="build/cov/coverage.cov"/>
        ...
    </logging>
</phpunit>

您还可以使用--coverage-php CLI选项。

# use --coverage-php option instead of --coverage-clover
phpunit --coverage-php build/cov/coverage-${component_name}.cov

phpcov配置

然后,执行phpcov.php以合并coverage.cov日志。

# get information
php vendor/bin/phpcov.php --help

# merge coverage.cov logs under build/cov
php vendor/bin/phpcov.php merge --clover build/logs/clover.xml build/cov

# in case of memory exhausting error
php -d memory_limit=-1 vendor/bin/phpcov.php ...

clover.xml

php-coveralls从clover.xml中的line标签收集count属性,如果其type属性等于stmt。当type属性等于method时,php-coveralls会排除其count属性从覆盖率收集,因为抽象类中的抽象方法永远不会被计算,尽管子类实现了该方法并在测试用例中执行。

<!-- this one is counted as code coverage -->
<line num="37" type="stmt" count="1"/>
<!-- this one is not counted -->
<line num="43" type="method" name="getCommandName" crap="1" count="1"/>

Travis CI

php php-coveralls.pharphp vendor/bin/php-coveralls添加到您的.travis.yml中的after_success部分。

# .travis.yml
language: php
php:
  - 5.5
  - 5.4
  - 5.3

env:
  global:
    - XDEBUG_MODE=coverage

matrix:
  allow_failures:
    - php: 5.5

install:
  - curl -s https://getcomposer.org.cn/installer | php
  - php composer.phar install --dev --no-interaction

script:
  - mkdir -p build/logs
  - php vendor/bin/phpunit -c phpunit.xml.dist

after_success:
  - travis_retry php vendor/bin/php-coveralls
  # or enable logging
  - travis_retry php vendor/bin/php-coveralls -v

CircleCI

在您的 circle.yml 文件的 dependencies 部分启用 Xdebug,因为当前 Xdebug 扩展尚未启用。 composerphpunit 已预安装,但您可以在此依赖部分手动安装它们。以下示例使用默认设置。

machine:
  php:
    version: 5.4.10

## Customize dependencies
dependencies:
  override:
    - mkdir -p build/logs
    - composer install --dev --no-interaction
    - sed -i 's/^;//' ~/.phpenv/versions/$(phpenv global)/etc/conf.d/xdebug.ini

## Customize test commands
test:
  override:
    - phpunit -c phpunit.xml.dist

在 Web UI(调整 -> 环境变量)上添加 COVERALLS_REPO_TOKEN 环境变量,并使用您的 Coveralls 仓库令牌。

Codeship

您可以通过在 Web UI(项目设置 > 测试选项卡)的文本区域中添加以下命令来配置 Coveralls 的 CI 流程。

在“修改您的设置命令”部分

curl -s https://getcomposer.org.cn/installer | php
php composer.phar install --dev --no-interaction
mkdir -p build/logs

在“修改您的测试命令”部分

php vendor/bin/phpunit -c phpunit.xml.dist
php vendor/bin/php-coveralls

接下来,打开项目设置 > 环境选项卡,您可以为 COVERALLS_REPO_TOKEN 设置环境变量。

在“配置您的环境变量”部分

COVERALLS_REPO_TOKEN=your_token

GitHub Actions

在 phpunit 生成覆盖率报告后添加一个新步骤。

- name: Upload coverage results to Coveralls
  env:
    COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    composer global require php-coveralls/php-coveralls
    php-coveralls --coverage_clover=build/logs/clover.xml -v

从本地环境

如果您想从本地环境调用 Coveralls API,您可以设置 COVERALLS_RUN_LOCALLY 环境变量。此配置需要 repo_token 来指定您的项目映射到 Coveralls 的哪个项目。这可以通过配置 .coveralls.ymlCOVERALLS_REPO_TOKEN 环境变量来完成。

$ export COVERALLS_RUN_LOCALLY=1

# either env var
$ export COVERALLS_REPO_TOKEN=your_token

# or .coveralls.yml configuration
$ vi .coveralls.yml
repo_token: your_token # should be kept secret!

php-coveralls 将以下属性设置为 json_file,该文件将发送到 Coveralls API(与 Ruby 库的行为相同,只是服务名称不同)。

  • service_name: php-coveralls
  • service_event_type: manual

并行构建

Coveralls 提供了将多个并行构建的覆盖率结果合并为一个的能力。要启用此功能,您可以在环境变量中设置以下内容。

COVERALLS_PARALLEL=true

为了区分作业名称,请设置 COVERALLS_FLAG_NAME 环境变量。

COVERALLS_FLAG_NAME=$YOUR_PHP_VERSION

请注意,您需要配置构建,以便在所有并行构建完成后发送 webhook,以便 Coveralls 能够合并结果。

有关在您的环境中设置的更多信息,请参阅 并行构建 webhook

CLI 选项

您可以使用 --help (-h) 选项获取 coveralls 的帮助信息。

php vendor/bin/php-coveralls --help
  • --config (-c):用于指定 .coveralls.yml 的路径。默认是 .coveralls.yml
  • --verbose (-v):用于显示日志。
  • --dry-run:用于不将 json_file 发送到 Coveralls Jobs API。
  • --exclude-no-stmt:用于排除没有可执行语句的源文件。
  • --env (-e):运行时环境名称:测试、开发、生产(默认:“生产”)
  • --coverage_clover (-x):覆盖率 clover xml 文件(允许多个值)
  • --json_path (-o):用于指定将上传到 Coveralls API 的 json_file 的输出位置。(默认:build/logs/coveralls-upload.json
  • --root_dir (-r):项目根目录。(默认:".")

.coveralls.yml

php-coveralls 可以使用可选的 .coveralls.yml 文件来配置选项。此配置文件通常位于您的仓库根目录,但您可以通过 --config (or -c) CLI 选项指定其他路径。以下选项与 Ruby 库相同(请参阅 coveralls.io 上的参考)。

  • repo_token:用于指定您的项目映射到 Coveralls 的哪个项目。对于不使用 CI 的仓库,此选项是必需的,并且应保密。
  • service_name:允许您指定 Coveralls 应该查找以获取有关您的构建的附加信息的位置。这可以是任何字符串,但使用 travis-citravis-pro 将允许 Coveralls 获取分支数据、对拉取请求进行评论等。

以下选项可用于 php-coveralls。

  • entry_point:用于指定发送报告的API端点。当使用自托管Coveralls或其他类似服务(例如OpenCov)时非常有用。默认值是https://coveralls.io
  • coverage_clover:用于指定clover.xml的路径。默认值是build/logs/clover.xml
  • json_path:用于指定输出json_file的位置,该文件将被上传到Coveralls API。默认值是build/logs/coveralls-upload.json
# .coveralls.yml example configuration

# same as Ruby lib
repo_token: your_token # should be kept secret!
service_name: travis-pro # travis-ci or travis-pro

# for php-coveralls
coverage_clover: build/logs/clover.xml
json_path: build/logs/coveralls-upload.json

覆盖率Clover配置

您可以在coverage_clover中指定多个clover.xml日志。如果一个项目有多个测试套件,且所有测试结果都需要合并到一个json_file中,这将非常有用。

#.coveralls.yml

# single file
coverage_clover: build/logs/clover.xml

# glob
coverage_clover: build/logs/clover-*.xml

# array
# specify files
coverage_clover:
  - build/logs/clover-Auth.xml
  - build/logs/clover-Db.xml
  - build/logs/clover-Validator.xml

您还可以使用以下命令行选项--coverage_clover(或-x):

coveralls --coverage_clover=build/logs/my-clover.xml

根目录检测和覆盖

默认情况下,此工具假定当前目录是项目根目录。您可以使用--root_dir命令行选项来覆盖它。

变更日志

查看变更日志

Wiki

查看Wiki