Tested Routes Checker Bundle Laravel Package

Getting Started

Minimal Setup

1. Requirements:

   • PHP 8.4+ as of v1.1.0 (support for PHP 8.2 and 8.3 was dropped). Confirm your runtime before upgrading.

2. Installation:

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

   Add to config/bundles.php:

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

3. 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
  

• Regenerating the Baseline (v1.1.0+): When the codebase evolves, regenerate the baseline and the bundle will now keep useful entries and drop useless ones (e.g. routes that no longer exist), instead of appending blindly. This makes baselines safe to commit and regenerate as part of routine maintenance.

• 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.

• Parallel Tests (ParaTest): v1.1.0 includes official documentation for running under ParaTest. See the README's "Parallel tests" section for the recommended worker configuration / file merging approach instead of hand-rolling it.

Gotchas and Tips

Pitfalls

1. PHP Version Requirements:

   • v1.1.0 drops PHP 8.2 and 8.3. If you are pinned to those runtimes, stay on 1.0.x or upgrade PHP first. Bump composer.json's php constraint to >=8.4 to avoid silent failures on older runtimes.

2. Baseline Gluing Bug (pre-1.1.0):

   • Earlier versions could glue successive route entries together on repeated IgnoredRoutesStorage::saveRoutes() calls, producing malformed baseline files. This is fixed in v1.1.0 — if you have a baseline file generated by an older release, regenerate it once after upgrading.

3. Regenerating the Baseline:

   • With the new regeneration behavior, entries for routes that no longer exist (or are no longer relevant) are dropped automatically. If you manually curated a baseline, back it up before regenerating to be sure nothing you intentionally kept gets pruned.

4. 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'
     

5. Test Environment:

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

6. Route Matching:

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

7. Parallel Tests:

   • If using parallel test runners (e.g., PHPUnit --parallel or ParaTest), each worker writes to its own cache file. Follow the official ParaTest guidance added in v1.1.0 to merge the worker files before running the checker.

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
  

• Windows Compatibility: CI now runs on Windows as of v1.1.0. If you develop on Windows, prefer forward-slash paths in config and verify the cache file location under %kernel.cache_dir%.

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 }