Hidev Phpunit Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hiqdev/hidev-phpunit
   

   Ensure hiqdev/hidev is also installed (this plugin is a HiDev extension).

2. First Use Case: Run HiDev’s PHPUnit integration via CLI:

   hidev phpunit
   

   This executes PHPUnit with default configurations (generates phpunit.xml.dist and tests/_bootstrap.php if missing).

3. Key Files to Check:

   • hidev.json (HiDev config) – Look for phpunit section.
   • tests/_bootstrap.php – Auto-generated bootstrap file for test setup.
   • phpunit.xml.dist – Auto-generated PHPUnit config.

Implementation Patterns

Core Workflows

1. Test Execution:

   hidev phpunit          # Run all tests
   hidev phpunit --filter TestClass  # Filter tests
   hidev phpunit --coverage-html  # Generate HTML coverage
   

   • Supports all standard PHPUnit flags (e.g., --group, --exclude-group).

2. Test Generation:

   hidev gentest Model     # Generate skeleton test for `Model`
   hidev genfake Model     # Generate fake test data for `Model`
   

   • Uses phpunit-skeleton-generator under the hood. Outputs to tests/.

3. Configuration: Define PHPUnit settings in hidev.json:

   {
     "phpunit": {
       "colors": true,
       "bootstrap": "src/_bootstrap.php",
       "config": "phpunit.xml.dist"
     }
   }
   

   • colors: Enable colored output (auto-detected for PHPUnit ≥6).
   • bootstrap: Custom bootstrap file path (defaults to tests/_bootstrap.php).
   • config: Custom PHPUnit config file (defaults to phpunit.xml.dist).

4. Coverage Reports:

   hidev phpunit --coverage-clover=coverage.clover
   

   • Integrates with tools like Scrutinizer via clover/html formats.

5. Integration with HiDev:

   • Use hidev commands in CI/CD pipelines (e.g., Travis, GitHub Actions):

     # .github/workflows/test.yml
     - run: hidev phpunit --coverage-text
     

Advanced Patterns

• Custom Test Suites: Extend phpunit.xml.dist to include multiple suites:

  <phpunit>
    <testsuites>
      <testsuite name="Unit">
        <directory>./tests/unit</directory>
      </testsuite>
      <testsuite name="Feature">
        <directory>./tests/feature</directory>
      </testsuite>
    </testsuites>
  </phpunit>
  

  Trigger via:

  hidev phpunit --testsuite Unit
  

• Dynamic Bootstrap: Reference Laravel’s createTestingEnvironment() in tests/_bootstrap.php:

  <?php
  require __DIR__.'/../vendor/autoload.php';
  $dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/../');
  $dotenv->load();
  

• Parallel Testing: Use PHPUnit’s --parallel flag:

  hidev phpunit --parallel --threads=4
  

Gotchas and Tips

Pitfalls

1. Deprecated PHPUnit 6 Support:

   • The package was updated to drop PHPUnit 6 compatibility in v0.6.2. Ensure your project uses PHPUnit ≥7.
   • Fix: Update PHPUnit via Composer:

     composer require --dev phpunit/phpunit:^9
     

2. Missing phpunit-skelgen:

   • If hidev gentest fails, manually install the generator:

     composer require --dev sebastianbergmann/phpunit-skeleton-generator
     

3. Bootstrap File Paths:

   • The package assumes tests/_bootstrap.php or src/_bootstrap.php. Custom paths in hidev.json may break if files are missing.
   • Tip: Verify paths with:

     hidev phpunit --debug
     

4. HiDev Configuration Conflicts:

   • If hidev.json has duplicate phpunit keys (e.g., from multiple plugins), the last defined key wins.
   • Tip: Use hidev config:dump to inspect active configs.

5. Coverage Reporting:

   • HTML coverage reports may fail if xdebug is misconfigured. Ensure:

     ; php.ini
     xdebug.mode=coverage
     xdebug.output_dir=/tmp
     

Debugging Tips

• Verbose Output:

  hidev phpunit --verbose
  

  Reveals underlying PHPUnit commands and file paths.

• Dry Run: Simulate test generation without writing files:

  hidev gentest --dry-run Model
  

• HiDev Logs: Enable debug mode in hidev.json:

  {
    "debug": true
  }
  

Extension Points

1. Custom Templates: Override default templates (e.g., phpunit.xml.dist) by placing custom files in:

   config/hidev-phpunit/
   

   Example: config/hidev-phpunit/phpunit.xml.dist.

2. Pre/Post Hooks: Use HiDev’s onRun events to extend functionality. Add to hidev.json:

   {
     "scripts": {
       "pre-phpunit": "php artisan migrate --env=testing",
       "post-phpunit": "php artisan optimize"
     }
   }
   

3. CI-Specific Configs: Use environment variables to toggle settings:

   {
     "phpunit": {
       "colors": "${CI:-false}"
     }
   }
   

   • Disables colors in CI (e.g., GitHub Actions) where ANSI escape codes may cause issues.

Performance

• Cache Test Results: Add to phpunit.xml.dist:

  <phpunit>
    <cacheResultFile>~/.phpunit.result.cache</cacheResultFile>
  </phpunit>
  

  Reduces execution time on repeated runs.

• Exclude Slow Tests: Use groups in phpunit.xml.dist:

  <phpunit>
    <exclude>@slow</exclude>
  </phpunit>
  

  Tag slow tests in your test classes:

  /** @group slow */
  class LongRunningTest extends TestCase { ... }