LinuxCommandLibrary

php-coveralls

Submit PHP code coverage reports to Coveralls

TLDR

Send coverage information to Coveralls

$ php-coveralls
copy

Send coverage information to Coveralls for a specific directory
$ php-coveralls [[-r|--root_dir]] [path/to/directory]
copy

Send coverage information to Coveralls with a specific config
$ php-coveralls [[-c|--config]] [path/to/.coveralls.yml]
copy

Send coverage information to Coveralls with verbose output
$ php-coveralls [[-v|--verbose]]
copy

Send coverage information to Coveralls excluding source files with no executable statements
$ php-coveralls --exclude-no-stmt
copy

Send coverage information to Coveralls with a specific environment name
$ php-coveralls [[-e|--env]] [test|dev|prod]
copy

Specify multiple Coverage Clover XML files to upload
$ php-coveralls [[-x|--coverage_clover]] [path/to/first_clover.xml] --coverage_clover [path/to/second_clover.xml]
copy

Output the JSON that will be sent to Coveralls to a specific file
$ php-coveralls [[-o|--json_path]] [path/to/coveralls-upload.json]
copy

SYNOPSIS

php-coveralls [options]

PARAMETERS

--version
    Display the current version of php-coveralls.

--help
    Display help information about the command and its options.

--coverage_clover
    Specify the path to the Clover XML coverage file generated by PHPUnit or similar tool.

--json_path
    Specify the path to a JSON file containing additional information for the Coveralls job, often generated by CI/CD systems.

--exclude
    Exclude a directory from the coverage analysis.

--dry-run
    Perform a dry run; validate the input and configuration without actually sending data to Coveralls.

--verbose
    Enable verbose output for debugging.

DESCRIPTION

The `php-coveralls` command is a tool used to send PHP code coverage reports generated by tools like PHPUnit to the Coveralls.io service. Coveralls provides insights into code test coverage, helping developers identify untested areas and improve code quality. This tool automates the process of submitting coverage data, which would otherwise require manual configuration and handling of coverage files. It streamlines the continuous integration workflow, allowing for easy tracking of coverage trends and ensuring that every commit is properly tested.

It typically integrates with CI/CD pipelines (e.g., Travis CI, CircleCI, GitHub Actions) to automatically submit coverage data after running tests. The tool collects coverage data from PHPUnit or similar tools, formats it according to Coveralls' specifications, and then transmits it to the Coveralls.io API. This enables developers to quickly visualize code coverage metrics, identify coverage gaps, and ultimately improve the reliability and maintainability of their PHP projects.

CAVEATS

Requires a Coveralls.io account and proper configuration within the CI/CD environment. Ensure the coverage file path is accurate and that the necessary environment variables (e.g., repo token) are set.

INTEGRATION WITH CI/CD

The primary use case for `php-coveralls` is within Continuous Integration/Continuous Delivery (CI/CD) pipelines. After tests are executed, the coverage data is generated and then submitted to Coveralls using this command. Common CI/CD platforms include Travis CI, CircleCI, GitHub Actions, GitLab CI, and Jenkins.

ENVIRONMENT VARIABLES

The `php-coveralls` tool often relies on environment variables to configure the Coveralls job, such as the repository token (`COVERALLS_REPO_TOKEN`) and CI build information.
These variables are typically provided by the CI/CD environment.

CONFIGURATION FILES

While command-line options are the primary way to configure `php-coveralls`, some settings can also be specified through configuration files in the project, although this is less common. The `json_path` argument points to a json config file

HISTORY

The `php-coveralls` command and associated library were created to simplify the process of submitting PHP code coverage data to Coveralls.io. Prior to this, developers often had to manually format and upload coverage data, which was time-consuming and error-prone. The tool has evolved to support various CI/CD environments and coverage formats, becoming an integral part of many PHP development workflows focused on code quality and test coverage.

Copied to clipboard