Phpunit Double Colon Syntax Laravel Package

Getting Started

Install the package via Composer in your Laravel project's root directory:

composer require --dev sanmai/phpunit-double-colon-syntax

First use case: Run a single test method using pytest-style syntax:

vendor/bin/phpunit tests/Feature/UserTest.php::testLogin

This replaces the native PHPUnit --filter syntax while maintaining identical functionality.

Where to look first:

• The README for basic usage examples.
• The docs for troubleshooting and compatibility details.
• Laravel's built-in test helpers (e.g., php artisan test) remain unaffected—this only modifies vendor/bin/phpunit commands.

Implementation Patterns

Core Workflow

1. Replace --filter with :: syntax:

   # Before (native PHPUnit)
   vendor/bin/phpunit --filter testLogin tests/Feature/UserTest.php
   
   # After (with package)
   vendor/bin/phpunit tests/Feature/UserTest.php::testLogin
   

2. Run multiple tests:

   vendor/bin/phpunit tests/Feature/UserTest.php::testLogin tests/Feature/UserTest.php::testLogout
   

3. Combine with other flags (except --filter):

   vendor/bin/phpunit --coverage tests/Feature/UserTest.php::testLogin
   

Laravel-Specific Patterns

• Test Suite Organization: Leverage Laravel’s test structure (e.g., tests/Feature/, tests/Unit/) directly in commands:

  vendor/bin/phpunit tests/Feature/Auth/LoginTest.php::testGuestLogin
  

• CI/CD Integration: Use the syntax in GitHub Actions, GitLab CI, or Laravel Forge pipelines:

  # .github/workflows/tests.yml
  - run: vendor/bin/phpunit tests/Unit/UserTest.php::testCreate
  

• Package Development: Standardize test commands across published packages:

  vendor/bin/phpunit tests/Integration/PaymentTest.php::testWebhook
  

Integration Tips

• IDE Support: Configure your IDE (PHPStorm, VSCode) to recognize file::method syntax as valid PHPUnit commands.
• Alias Creation: Add shell aliases for convenience:

  alias run-test='vendor/bin/phpunit'
  run-test tests/Feature/UserTest.php::testProfileUpdate
  

• Team Onboarding: Document the syntax in your project’s CONTRIBUTING.md to reduce ramp-up time for new contributors.

Gotchas and Tips

Pitfalls

1. Exclusive Syntax: The package does not support mixing file::method and --filter in the same command. Choose one syntax per invocation.

   • ❌ Fails: vendor/bin/phpunit --filter testLogin tests/UserTest.php::testCreate
   • ✅ Works: vendor/bin/phpunit tests/UserTest.php::testCreate

2. Global Scope: Only affects vendor/bin/phpunit commands. Other PHPUnit executables (e.g., global phpunit) remain unchanged.

3. Static Analysis Tools: Tools like PHPStan or Psalm may flag file::method as invalid syntax. Configure them to ignore these patterns or use runtime checks.

4. Legacy PHPUnit: While the package supports PHPUnit 6+, Laravel’s minimum PHP 8.0+ ensures compatibility with modern versions.

Debugging

• Command Not Working?:

  • Verify the package is installed in dev dependencies (composer.json).
  • Ensure you’re using vendor/bin/phpunit, not a globally installed version.
  • Check for typos in test filenames or method names (case-sensitive).

• Error: "Test file not found":

  • Confirm the test file exists at the specified path.
  • Use absolute paths if relative paths fail:

    vendor/bin/phpunit /full/path/to/tests/UserTest.php::testLogin
    

Configuration Quirks

• No Config Needed: The package auto-detects vendor/bin/phpunit and transforms arguments at runtime. No phpunit.xml or environment variables are required.
• Custom PHPUnit Binaries: If you use a custom phpunit binary (e.g., ./vendor/bin/phpunit-custom), the package won’t intercept it. Stick to vendor/bin/phpunit.

Extension Points

• Custom Syntax: The package’s transformation logic is open-source. Fork and modify it to support additional syntax (e.g., namespace::class::method) if needed.
• Pre-Commit Hooks: Add a hook to validate file::method syntax in test commands before commits:

  grep -E 'phpunit.*::' your-script.sh && echo "Use file::method syntax" && exit 1
  

Laravel-Specific Tips

• Test Case Naming: Follow Laravel’s conventions (e.g., *Test.php) to avoid path-related issues.
• Artisan Test Command: The package does not affect php artisan test. Use vendor/bin/phpunit for file::method syntax.
• PestPHP: If adopting PestPHP later, migrate to its native syntax (test('description'))—this package won’t interfere but won’t be needed.