Php Coveralls Mirror Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install the package via Composer:

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

2. Configure PHPUnit in phpunit.xml to generate a clover.xml report:

   <logging>
       <log type="coverage-clover" target="build/logs/clover.xml"/>
   </logging>
   

3. Add to CI workflow (e.g., .travis.yml):

   after_success:
     - php vendor/bin/php-coveralls -v
   

4. Set up .coveralls.yml (if not using CI):

   repo_token: your_coveralls_token
   service_name: travis-pro
   coverage_clover: build/logs/clover.xml
   

First Use Case

Run tests locally with coverage:

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

Then upload to Coveralls:

php vendor/bin/php-coveralls

Implementation Patterns

Laravel-Specific Workflows

1. CI Integration

   • Use after_success in GitHub Actions, GitLab CI, or CircleCI to trigger Coveralls upload.
   • Example GitHub Actions workflow:

     - name: Upload to Coveralls
       run: php vendor/bin/php-coveralls -v
       env:
         COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_TOKEN }}
     

2. Local Development

   • Set COVERALLS_RUN_LOCALLY=1 and COVERALLS_REPO_TOKEN to test locally:

     export COVERALLS_RUN_LOCALLY=1
     export COVERALLS_REPO_TOKEN=your_token
     php vendor/bin/php-coveralls
     

3. Parallel Testing

   • Merge multiple clover.xml files using phpcov (as shown in README) before uploading:

     php vendor/bin/phpcov merge --clover build/logs/clover.xml build/cov
     php vendor/bin/php-coveralls --coverage_clover=build/logs/clover.xml
     

4. Custom Configuration

   • Override defaults via .coveralls.yml or CLI flags:

     php vendor/bin/php-coveralls --json_path=custom/path.json --env=dev
     

Laravel Testing Patterns

• Laravel TestCase: Ensure phpunit.xml is configured for coverage-clover in Laravel’s test suite.
• PestPHP: If using Pest, configure it to generate clover.xml via pest.php:

  tests()->coverage()->outputTo('build/logs/clover.xml');
  

Gotchas and Tips

Pitfalls

1. Token Security

   • Never hardcode repo_token in .coveralls.yml; use environment variables or CI secrets.
   • Example: .env.coveralls (add to .gitignore):

     COVERALLS_REPO_TOKEN=your_token
     

2. Path Issues

   • Ensure clover.xml paths in .coveralls.yml are relative to the project root.
   • Use --root_dir to override the assumed root directory:

     php vendor/bin/php-coveralls --root_dir=/path/to/project
     

3. CI-Specific Quirks

   • Travis CI: Use travis_retry to avoid flaky uploads.
   • GitHub Actions: Cache vendor/ to speed up builds:

     - uses: actions/cache@v2
       with:
         path: vendor
         key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
     

4. Windows Compatibility

   • Paths in .coveralls.yml must use forward slashes (/), even on Windows.

Debugging Tips

• Verbose Mode: Use -v to debug upload issues:

  php vendor/bin/php-coveralls -v
  

• Dry Run: Test JSON generation without uploading:

  php vendor/bin/php-coveralls --dry-run
  

• Exclude Files: Skip files with no executable statements:

  php vendor/bin/php-coveralls --exclude-no-stmt
  

Extension Points

1. Custom API Endpoint

   • Override Coveralls’ default endpoint (e.g., for self-hosted instances):

     # .coveralls.yml
     entry_point: https://your-coveralls-instance.com
     

2. Post-Processing

   • Parse the generated coveralls-upload.json to customize data before upload (e.g., filter tests).

3. Symfony Integration

   • Use symfony/console integration for Laravel Artisan commands:

     use Symfony\Component\Console\Application;
     $app = new Application();
     $app->add(new \Coveralls\Command\CoverallsCommand());
     $app->run();