Convention Laravel Package

Technical Evaluation

Architecture Fit

• Testo’s Plugin System: The package leverages Testo’s modular plugin architecture, which is highly composable and aligns with Laravel’s service provider pattern. This allows for seamless integration into existing Laravel test workflows without monolithic changes.
• Convention-Based Discovery: Fits Laravel’s filesystem-centric testing (e.g., *Test.php in tests/) but operates at a lower abstraction level than Laravel’s TestCase. Requires a bridge layer to align with Laravel’s TestWorker and TestCase lifecycle.
• Legacy Migration: Ideal for incremental adoption of Testo in Laravel projects where rewriting test annotations is prohibitive. Reduces technical debt by preserving existing naming conventions.
• Hybrid Testing: Enables parallel execution of Testo and PHPUnit/Pest, useful for gradual migration or feature-specific testing.

Integration Feasibility

• Testo Dependency: Mandates Testo as a prerequisite, which may conflict with Laravel’s native testing stack. Requires:
  • A custom TestResolver to delegate discovery to Testo.
  • Overrides to Laravel’s TestCase bootstrapping (e.g., createApplication()).
• Configuration Conflicts: May clash with phpunit.xml or Pest’s pest.php if both define discovery rules. Needs explicit isolation (e.g., separate config files).
• Laravel-Specific Gaps: Lacks native integration with:
  • Laravel’s TestCase assertions (e.g., assertDatabaseHas).
  • Artisan commands (e.g., php artisan test).
  • IDE tooling (e.g., PHPStorm test runners).

Technical Risk

• Discovery Edge Cases:
  • Namespace collisions (e.g., App\Tests\* vs. Tests\*).
  • Custom test paths (e.g., tests/Feature/, tests/Unit/).
  • Performance overhead in large codebases (e.g., scanning vendor/).
• Testo Maturity Risks:
  • Breaking changes in Testo’s discovery API.
  • Limited Laravel tooling (e.g., no TestoServiceProvider).
  • Debugging complexity (e.g., "Test not discovered" errors lack IDE support).
• Hybrid Execution Risks:
  • Result aggregation (e.g., combining Testo and PHPUnit outputs in CI).
  • State management (e.g., Laravel’s TestCase state vs. Testo’s context).

Key Questions

1. Adoption Strategy:

   • Will Testo replace PHPUnit/Pest, or run in parallel? If parallel, how will results be merged in CI?
   • Are there Laravel-specific plugins for Testo (e.g., database assertions, HTTP testing)?

2. Integration Depth:

   • Should Testo fully replace Laravel’s TestCase, or act as a secondary runner?
   • How will createApplication() and other Laravel test hooks interact with Testo?

3. Convention Design:

   • Are naming conventions documented and enforced? If not, how will inconsistencies be handled?
   • Will custom conventions (e.g., FeatureTest, UnitTest) require runtime configuration?

4. Tooling Support:

   • Are there plans to integrate Testo with:
     • Laravel’s php artisan test?
     • IDE test runners (e.g., PHPStorm)?
     • CI/CD pipelines (e.g., GitHub Actions, parallel test execution)?

5. Performance:

   • What is the expected scale of test discovery? Will filesystem scanning be a bottleneck?
   • Are there exclusion patterns (e.g., skip vendor/, node_modules/)?

6. Rollback Plan:

   • How will the team revert if Testo adoption fails?
   • Is there a fallback to annotation-based discovery?

Integration Approach

Stack Fit

• Primary Use Case:
  • Laravel projects migrating from PHPUnit/Pest to Testo without rewriting test annotations.
  • Projects using convention-based discovery (e.g., *Test.php) and needing Testo-specific features (e.g., assertSoft).
• Secondary Use Case:
  • Hybrid testing where Testo runs specific test suites (e.g., performance tests) while PHPUnit/Pest handles others.
• Non-Fit:
  • Projects heavily reliant on Laravel’s TestCase assertions (e.g., assertDatabaseHas).
  • Teams preferring explicit annotations over conventions.

Migration Path

1. Phase 1: Testo Core Integration

   • Install Testo and configure as a secondary runner:

     composer require --dev php-testo/testo
     

   • Create a custom TestResolver to delegate discovery:

     // app/Providers/TestoServiceProvider.php
     public function boot()
     {
         TestCase::macro('runTestoTests', function () {
             return Testo::run($this->getName());
         });
     }
     

   • Update composer.json to support parallel execution:

     "scripts": {
         "test": "php artisan test --runner=phpunit && testo run"
     }
     

2. Phase 2: Convention Plugin Setup

   • Install the convention plugin:

     composer require --dev testo/convention
     

   • Configure conventions in testo.php:

     return [
         'conventions' => [
             'files' => ['tests/Unit/*Test.php', 'tests/Feature/*Test.php'],
             'classes' => ['*Test', 'TestCase'],
             'methods' => ['test*'],
         ],
         'excludes' => ['tests/Integration/*'], // Skip integration tests
     ];
     

3. Phase 3: Bridge Laravel Test Lifecycle

   • Extend TestCase to support Testo:

     // app/Tests/TestCase.php
     public function runTestoSuite()
     {
         return Testo::discoverAndRun($this->getTestPath());
     }
     

   • Override php artisan test to invoke Testo:

     php artisan test --runner=testo
     

4. Phase 4: CI/CD Integration

   • Update pipelines to support Testo:

     # .github/workflows/test.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - run: composer test
           - run: testo run --coverage
     

   • Configure parallel execution (if using both Testo and PHPUnit).

5. Phase 5: Gradual Rollout

   • Start with non-critical test suites (e.g., unit tests).
   • Use feature flags to toggle Testo discovery per suite.
   • Monitor performance and coverage gaps.

Compatibility

• Laravel TestCase:
  • Requires wrapper methods to adapt Testo’s assertions to Laravel’s TestCase contract.
  • Example: assertDatabaseHas() may need a Testo-compatible alias.
• PHPUnit/Pest:
  • Can run in parallel, but requires custom result aggregation (e.g., phpunit --testdox-html + Testo’s output).
  • Pest integration is non-trivial and may require a custom plugin.
• IDE Support:
  • Limited out-of-the-box. May need:
    • Custom metadata files (e.g., .idea/testRunConfigurations).
    • Testo-specific IDE plugins (e.g., for PHPStorm).

Sequencing

Operational Impact

Maintenance

• Configuration Management:
  • Conventions may drift if the team adopts new naming patterns (e.g., Test → Spec).
  • Requires documentation of allowed patterns (e.g., tests/Unit/*Test.php).
• Dependency Updates:
  • Testo’s early-stage maturity risks breaking changes