Tested Routes Checker Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev bab/tested-routes-checker-bundle
   

   Add to config/bundles.php:

   Bab\TestedRoutesCheckerBundle\BabTestedRoutesCheckerBundle::class => ['dev' => true, 'test' => true],
   

2. First Run:

   • Execute your PHPUnit tests normally. The bundle will cache all accessed routes in var/cache/bab_tested_routes_checker_bundle_route_storage.
   • Run the checker:

     php bin/console bab:tested-routes-checker:check
     

   • Review the report for untouched routes.

First Use Case

Prevent Uncovered Routes in CI: Add this to your GitHub Actions workflow after tests:

- name: Check Tested Routes
  run: php bin/console bab:tested-routes-checker:check

Implementation Patterns

Workflow Integration

1. Test Execution:

   • Run tests with --coverage-text or --coverage-clover to generate coverage reports alongside route tracking.
   • Example PHPUnit command:

     ./vendor/bin/phpunit --coverage-text --colors=never
     

2. CI Pipeline:

   • Single Job: Directly run the checker after tests.
   • Multi-Job: Upload var/cache/bab_tested_routes_checker_bundle_route_storage as an artifact, then merge and check in a final job (see README for details).

3. Local Development:

   • Use php bin/console bab:tested-routes-checker:check --env=test to validate routes during local testing.

Advanced Patterns

• Exclude Routes: Create a .bab-trc-baseline file with one route per line (e.g., api/login) to ignore specific routes.

  echo "api/login" > .bab-trc-baseline
  

• Custom Cache Directory: Override the cache path in config/packages/bab_tested_routes_checker.yaml:

  bab_tested_routes_checker:
      cache_dir: '%kernel.cache_dir%/custom_route_cache'
  

• Symfony Localized Routes: The bundle automatically handles localized routes (e.g., _locale=de). No extra configuration is needed.

Gotchas and Tips

Pitfalls

1. Cache Clearing:

   • The cache file (bab_tested_routes_checker_bundle_route_storage) is not cleared by default during cache:clear. Manually delete it or add it to your cache:pool cleanup script.
   • Fix: Add to config/packages/framework.yaml:

     framework:
         cache:
             pools:
                 bab_route_checker:
                     path: '%kernel.cache_dir%/bab_tested_routes_checker_bundle_route_storage'
     

2. Test Environment:

   • The bundle only works in test or dev environments (configured in bundles.php). Running it in prod will show no results.

3. Route Matching:

   • The checker uses exact route name matches (e.g., app_homepage vs. app_home). Ensure your tests hit the correct route names.

4. Parallel Tests:

   • If using parallel test runners (e.g., PHPUnit --parallel), merge the cache files manually or use a shared storage solution.

Debugging Tips

• Verify Cache Contents: Inspect the cache file directly:

  cat var/cache/bab_tested_routes_checker_bundle_route_storage
  

  Expected format: One route name per line (e.g., app_homepage).

• Check Route Names: List all routes to confirm names:

  php bin/console debug:router
  

• CI Debugging: Add a step to dump the cache before checking:

  - name: Debug Cache
    run: cat var/cache/bab_tested_routes_checker_bundle_route_storage
  

Extension Points

1. Custom Report Format: Override the command class (Bab\TestedRoutesCheckerBundle\Command\CheckCommand) to extend the report (e.g., JSON output).

2. Route Filtering: Extend the Bab\TestedRoutesCheckerBundle\Checker\RouteChecker service to add custom logic (e.g., ignore routes with specific parameters).

3. Event Listeners: Listen to bab.tested_routes_checker.route_captured to log or process routes in real-time:

   // config/services.yaml
   services:
       App\EventListener\RouteLogger:
           tags:
               - { name: kernel.event_listener, event: bab.tested_routes_checker.route_captured, method: onRouteCaptured }