C3 Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require --dev codeception/c3
   

   Ensure codeception/codeception is also installed (required dependency).

2. Configuration Update your codeception.yml to include the C3 module:

   modules:
     enabled:
       - C3
   

   Configure C3 in .codeception.dist.yml (or directly in codeception.yml):

   C3:
     url: 'https://coverage.example.com'  # Your remote coverage server
     token: 'your_api_token'              # API token for authentication
     project: 'your_project_name'         # Project identifier
   

3. First Use Case Run tests with coverage upload:

   ./vendor/bin/codecept run --coverage --coverage-xml --coverage-c3
   

   Verify coverage data appears on your remote server.

Implementation Patterns

Daily Workflow

1. Local Testing with Remote Upload

   • Use codecept run with --coverage-c3 to upload coverage after each test run.
   • Example CI/CD integration (GitHub Actions):

     - name: Run tests with coverage
       run: ./vendor/bin/codecept run --coverage --coverage-c3
     

2. Conditional Uploads

   • Skip C3 uploads in local dev (e.g., via environment checks):

     C3:
       enabled: ${ENV:CI}  # Only upload in CI
     

3. Parallel Testing

   • For parallel test suites (e.g., codecept run -p), ensure unique project or token per worker to avoid conflicts.

4. Integration with Laravel

   • Use Laravel’s phpunit.xml to trigger Codeception:

     <phpunit>
       <listeners>
         <listener class="Codeception\Codecept\PHPUnit\Listener" file="vendor/codeception/codeception/codecept.php"/>
       </listeners>
     </phpunit>
     

   • Run via Artisan:

     php artisan codecept run --coverage-c3
     

Advanced Patterns

• Custom Coverage Filters Exclude Laravel-specific paths (e.g., vendor/, bootstrap/) in codeception.yml:

  C3:
    exclude:
      - vendor/
      - bootstrap/*
  

• Branch/Tag-Based Projects Dynamically set project in codeception.yml:

  C3:
    project: 'laravel-${GIT_BRANCH}'  # Use CI env vars
  

• Post-Test Hooks Use Codeception’s after hooks to validate coverage before upload:

  // tests/_support/Helper/Acceptance.php
  public function _after(AcceptanceTester $I) {
      if ($I->grabService('C3')->getCoverage() < 80) {
          throw new \Exception("Coverage too low!");
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. Authentication Failures

   • Issue: 403 Forbidden errors if token is missing/invalid.
   • Fix: Verify the token in your C3 server’s dashboard and ensure it’s not hardcoded in version control.

2. Coverage Data Mismatches

   • Issue: Uploaded coverage doesn’t match local reports.
   • Fix: Ensure --coverage-xml is used alongside --coverage-c3 to generate consistent data.

3. CI Environment Conflicts

   • Issue: C3 fails in CI due to missing environment variables.
   • Fix: Use .env.testing or CI-specific config:

     C3:
       url: ${COVERAGE_SERVER_URL}
       token: ${COVERAGE_TOKEN}
     

4. Rate Limits

   • Issue: API rate limits block uploads in parallel jobs.
   • Fix: Add delays between uploads or use separate tokens/projects per job.

Debugging Tips

• Enable Verbose Logging Run with -vvv to debug C3 interactions:

  ./vendor/bin/codecept run --coverage-c3 -vvv
  

• Check Server Status Verify your C3 server is reachable:

  curl -v https://coverage.example.com/api/status
  

• Local Testing Without Upload Disable uploads for local runs:

  C3:
    enabled: false
  

Extension Points

1. Custom Upload Logic Extend the C3 module by overriding uploadCoverage() in a custom module:

   class CustomC3 extends \Codeception\Module\C3 {
       public function uploadCoverage() {
           // Custom logic (e.g., pre-process data)
           parent::uploadCoverage();
       }
   }
   

2. Webhook Triggers Use C3’s API to trigger builds on coverage updates (e.g., via GitHub Actions webhooks).

3. Dashboard Integration Embed C3’s coverage reports in Laravel’s admin panel using its API:

   $coverage = Http::get('https://coverage.example.com/api/coverage', [
       'token' => config('services.c3.token'),
   ]);
   

Config Quirks

• URL Paths: Ensure url ends with / (e.g., https://example.com/).
• Token Permissions: Restrict tokens to read-only if only uploading coverage.
• Project Naming: Use lowercase/kebab-case for consistency (e.g., laravel-auth).