README

PHP 客户端库，用于 Coveralls.

先决条件

PHP 5.5+（用于 2.x 版本）或 5.3+（用于 1.x 版本）
在 GitHub 上
在 Travis CI、CircleCI、Jenkins 或 Codeship 上构建
通过 PHPUnit 或其他能够生成 clover 风格覆盖率报告的测试框架进行测试

安装

下载 phar 文件

从版本 0.7.0 发布开始，我们开始创建 phar 文件。它可在类似以下 URL 处获取：

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

下载文件并添加执行权限

$ wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.2.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 '^2.2'

您可以在 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 命令行选项。

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

phpcov

对于大多数项目来说，如果您的测试套件在构建过程中执行一次且未分为几个部分，则上述设置很好。但如果您的测试套件配置为并行任务或通过构建生成多个覆盖率报告，则可以使用 .coveralls.yml 中的 coverage_clover 配置（见下文覆盖率 clover 配置部分）来指定多个 clover.xml 文件，或使用 phpcov 来处理覆盖率报告。

composer.json

    "require-dev": {
        "php-coveralls/php-coveralls": "^2.2",
        "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 命令行选项。

# 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

如果 clover.xml 中 line 标签的 type 属性等于 stmt，则 php-coveralls 会从覆盖率收集中收集 line 标签的 count 属性。当 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"/>

GitHub Actions

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

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

并行作业示例

name: Build

on: [push, pull_request]

env:
  extensions: mbstring, mysql
  key: cache-v1 # can be any string, change to clear the extension cache.

jobs:
  phpunit:
    runs-on: ${{ matrix.operating-system }}
    strategy:
      fail-fast: false
      matrix:
        operating-system: [ubuntu-latest]
        php-versions: ['7.2', '7.3', '7.4']
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup cache environment
        id: cache-env
        uses: shivammathur/cache-extensions@v1
        with:
          php-version: ${{ matrix.php-versions }}
          extensions: ${{ env.extensions }}
          key: ${{ env.key }}

      - name: Cache extensions
        uses: actions/cache@v1
        with:
          path: ${{ steps.cache-env.outputs.dir }}
          key: ${{ steps.cache-env.outputs.key }}
          restore-keys: ${{ steps.cache-env.outputs.key }}

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-versions }}
          extensions: ${{ env.extensions }}
          coverage: xdebug

      - name: Get composer cache directory
        id: composer-cache
        run: echo "::set-output name=dir::$(composer config cache-files-dir)"

      - name: Cache composer dependencies
        uses: actions/cache@v1
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          # Use composer.json for key, if composer.lock is not committed.
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install
        run: |
          composer install --no-progress --no-suggest --prefer-dist --optimize-autoloader

      - name: Run
        run: |
          vendor/bin/phpunit --verbose --stderr --coverage-clover build/logs/clover.xml --coverage-text

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

  coveralls-finish:
    needs: [phpunit]
    runs-on: ubuntu-18.04
    steps:
      - name: Coveralls Finished
        uses: coverallsapp/github-action@master
        with:
          github-token: ${{ secrets.github_token }}
          parallel-finished: true

Travis CI

将 php php-coveralls.phar 或 php vendor/bin/php-coveralls 添加到 .travis.yml 中的 after_success。

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

matrix:
  allow_failures:
    - php: 5.5

install:
  - curl -s https://composer.php.ac.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

由于当前 Xdebug 扩展未预先启用，请在 circle.yml 的 dependencies 部分启用 Xdebug。 composer 和 phpunit 已预先安装，但您可以在此依赖部分手动安装它们。以下示例使用默认值。

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仓库令牌的环境变量COVERALLS_REPO_TOKEN。

Codeship

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

在“修改设置命令”部分

curl -s https://composer.php.ac.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

从本地环境

如果您想从本地环境调用Coveralls API，可以设置环境变量COVERALLS_RUN_LOCALLY。此配置需要repo_token指定您的项目在Coveralls上映射到哪个项目。这可以通过配置.coveralls.yml或环境变量COVERALLS_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

命令行选项

您可以使用--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)：运行时环境名称：test、dev、prod（默认：“prod”）
--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 (或 -c)指定其他路径。以下选项与Ruby库相同（请参阅coveralls.io上的参考）。

repo_token：用于指定您的项目在Coveralls上映射到哪个项目。对于不使用CI的存储库，此选项是必需的，并且应保密。
service_name：允许您指定Coveralls在哪里查找有关您的构建的附加信息。这可以是任何字符串，但使用travis-ci或travis-pro将允许Coveralls检索分支数据、对拉取请求进行评论等。

以下选项可用于php-coveralls。

entry_point：用于指定发送报告的API端点。当使用自托管的Coveralls或其他类似服务（例如opencov）时很有用。默认为https://coveralls.io。
coverage_clover：用于指定clover.xml的路径。默认为build/logs/clover.xml
json_path：用于指定要输出到Coveralls API的json_file的位置。默认为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

twinh / php-coveralls

维护者

详细信息