Getting Started

Minimal Steps

Installation:

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

Add it to your composer.json under require-dev.

First Use Case: Run a single test method using the familiar pytest-style syntax:
```
vendor/bin/phpunit tests/Feature/UserTest.php::testLogin
```
This replaces the need for --filter and reduces ambiguity.

Where to Look First

README.md: For quick installation and basic usage.
docs/index.md: For detailed examples and troubleshooting.
GitHub Issues: Check for edge cases or compatibility notes (though minimal).

Implementation Patterns

Usage Patterns

Single Test Execution:

vendor/bin/phpunit tests/Unit/ExampleTest.php::testExampleMethod

Equivalent to:

vendor/bin/phpunit --filter testExampleMethod tests/Unit/ExampleTest.php

Multiple Tests in One Command:

vendor/bin/phpunit tests/Unit/UserTest.php::testCreate tests/Unit/UserTest.php::testUpdate

Integration with Laravel’s Test Structure:

vendor/bin/phpunit tests/Feature/Auth/LoginTest.php::testGuestCannotLogin
vendor/bin/phpunit tests/Unit/Http/Controllers/UserControllerTest.php::testIndex

CI/CD Pipelines: Use the syntax in GitHub Actions, Laravel Forge, or Envoyer for explicit test targeting:
```
# GitHub Actions example
- run: vendor/bin/phpunit tests/Unit/UserTest.php::testCreate
```

Workflows

Debugging Workflow: Replace ambiguous --filter calls with explicit file::method syntax to avoid typos or partial matches.

# Before (risk of typos or partial matches)
vendor/bin/phpunit --filter testCreate

# After (explicit and unambiguous)
vendor/bin/phpunit tests/Unit/UserTest.php::testCreate

Team Onboarding: Standardize test commands across teams familiar with pytest/Jest, reducing cognitive load for hybrid teams.
Test Isolation: Use the syntax to run tests in isolation during development, especially in large Laravel applications with modular test suites.

Integration Tips

Laravel Artisan Aliases: Add a custom alias in ~/.bashrc or ~/.zshrc for convenience:
```
alias phpunit="vendor/bin/phpunit"
```
Now you can use:
```
phpunit tests/Feature/UserTest.php::testLogin
```
IDE Support: Configure your IDE (PHPStorm, VSCode) to recognize the file::method syntax in run configurations for PHPUnit.
Custom Scripts: Wrap the command in a script (e.g., run-test) to add pre/post-processing logic while maintaining the double-colon syntax.

Laravel Packages: Document the syntax in your package’s README.md to help users run tests easily:

## Running Tests
```bash
composer test
vendor/bin/phpunit tests/Feature/PackageTest.php::testFeatureX

Gotchas and Tips

Pitfalls

Incompatibility with --filter: The package does not work when combined with --filter in the same command. Choose one syntax or the other:

# Works (double-colon)
vendor/bin/phpunit tests/UserTest.php::testLogin

# Works (native PHPUnit)
vendor/bin/phpunit --filter testLogin tests/UserTest.php

# Fails (mixed syntax)
vendor/bin/phpunit --filter testLogin tests/UserTest.php::testLogin

Static Analysis Tools: Tools like Psalm or PHPStan may flag the file::method syntax as invalid since it’s not native to PHPUnit. Add an ignore rule or configure the tool to skip the transformed arguments.
Non-vendor/bin/phpunit Binaries: The package only intercepts vendor/bin/phpunit. If you use a global phpunit binary or a custom alias, the syntax won’t work. Ensure you’re using the local vendor binary:
```
./vendor/bin/phpunit tests/UserTest.php::testLogin
```

Windows Paths: On Windows, ensure paths use forward slashes or escape backslashes:

vendor/bin/phpunit tests\Unit\UserTest.php::testLogin

Or:

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

Test Method Naming: The package relies on exact method names. If your test method uses spaces or special characters (e.g., test user login), ensure the syntax matches exactly:

# Fails (spaces in method name)
vendor/bin/phpunit tests/UserTest.php::test user login

# Works (use underscores or camelCase)
vendor/bin/phpunit tests/UserTest.php::testUserLogin

Debugging

Verify Installation: Check if the package is loaded by running:
```
composer show sanmai/phpunit-double-colon-syntax
```
Ensure it appears in require-dev.
Check Autoloader: The package hooks into Composer’s autoloader. If it’s not working, clear Composer’s cache:
```
composer clear-cache
```
Test with a Simple Command: Run a basic test to confirm the syntax works:
```
vendor/bin/phpunit tests/Unit/ExampleTest.php::testTrue
```
If this fails, check for typos or path issues.
Enable PHPUnit Debugging: Use --debug to inspect how arguments are processed:
```
vendor/bin/phpunit --debug tests/UserTest.php::testLogin
```

Tips

Leverage for CI/CD: Use the syntax in CI pipelines to run specific tests for faster feedback:

# GitHub Actions example
- name: Run specific test
  run: vendor/bin/phpunit tests/Unit/UserTest.php::testCreate

Combine with Laravel’s Test Helpers: Use the syntax alongside Laravel’s test helpers (e.g., actingAs, refreshDatabase) in your test methods:
```
public function testUserCanLogin()
{
    // Test logic here
}
```
Run it with:
```
vendor/bin/phpunit tests/Feature/Auth/LoginTest.php::testUserCanLogin
```

Document the Syntax: Add a section to your project’s CONTRIBUTING.md or README.md to educate contributors:

## Running Tests
Use the `file::method` syntax for clarity:
```bash
vendor/bin/phpunit tests/Feature/UserTest.php::testCreate

Alias for PestPHP Users: If your team uses PestPHP, consider migrating to Pest for native double-colon support and a more expressive testing syntax. This package is a good stopgap for PHPUnit users.
Performance Note: The package adds minimal overhead since it only transforms arguments before PHPUnit starts. No runtime performance impact is expected.
Future-Proofing: The package supports PHPUnit 6–13 and PHP 7.1–8.5+. If you’re using Laravel (PHP 8.0+), you’re covered for the foreseeable future. Monitor the GitHub repo for updates.

Phpunit Double Colon Syntax Laravel Package