Mink Debug Extension Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project (if using Behat for testing):

   composer require --dev friends-of-behat/mink-debug-extension
   

2. Configure Behat Update your behat.yml to include the extension:

   default:
     extensions:
       FriendsOfBehat\MinkDebugExtension:
         enabled: true
   

3. First Use Case Run a failing Behat scenario. The extension will automatically:

   • Capture screenshots on failure.
   • Log detailed debugging info (e.g., DOM snapshots, HTTP responses).
   • Output a report in features/debug/ (default path).

Key Commands

• Run with Debugging:

  behat --debug
  

• Clear Debug Output:

  behat --debug-clear
  

Implementation Patterns

Workflows

1. Debugging Failed Scenarios

   • Use Then I should see "Expected Text" → On failure, check features/debug/ for:
     • Screenshots (screenshot_*.png).
     • DOM snapshots (dom_*.html).
     • HTTP request/response logs (http_*.log).
   • Example: After a Click step fails, inspect the rendered HTML to verify element presence.

2. Integration with Laravel

   • Session Debugging: For Laravel sessions, ensure Mink uses the same session driver (e.g., array for testing):

     FriendsOfBehat\MinkDebugExtension:
       session: 'laravel'  # If using a custom Mink session
       screenshot_dir: 'storage/logs/behat-screenshots'
     

   • Artisan Commands: Debug CLI-driven steps (e.g., When I run "php artisan migrate"):

     // In a custom Mink context
     $this->getSession()->executeScript('return require("fs").readFileSync("/tmp/artisan.log")');
     

3. Custom Contexts Extend the debug extension in a custom context to log additional data:

   use FriendsOfBehat\MinkDebugExtension\Context\MinkDebugContext;
   
   class CustomDebugContext extends MinkDebugContext {
       public function logCustomData($data) {
           $this->getMinkDebug()->log('custom', print_r($data, true));
       }
   }
   

   Register in behat.yml:

   contexts:
     - CustomDebugContext
   

Best Practices

• Selective Debugging: Disable for CI/CD by environment:

  # behat.ci.yml
  extensions:
    FriendsOfBehat\MinkDebugExtension:
      enabled: false
  

• Storage Paths: Use Laravel’s storage system for screenshots:

  FriendsOfBehat\MinkDebugExtension:
    screenshot_dir: 'storage/app/behat-screenshots'
  

• Parallel Testing: Append scenario ID to filenames to avoid conflicts:

  FriendsOfBehat\MinkDebugExtension:
    screenshot_filename: 'scenario_%id%_step_%step%'
  

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Debugging adds I/O operations (screenshots, logs). Avoid in performance-critical tests.
   • Fix: Use enabled: false in production-like environments.

2. Session Mismatches

   • Mink’s session may not match Laravel’s (e.g., cookies, CSRF tokens).
   • Fix: Reset the session before critical steps:

     $this->getSession()->reset();
     

3. File Permissions

   • Debug output dir (features/debug/) must be writable.
   • Fix: Set permissions or use Laravel’s storage:

     chmod -R 777 storage/logs/behat-screenshots
     

4. Headless Browsers

   • Screenshots may fail in headless mode (e.g., ChromeDriver).
   • Fix: Use window.print() as a fallback:

     // In a custom JS snippet
     window.printToDataURL();
     

Debugging Tips

• Inspect HTTP Traffic: Enable Mink’s proxy logs:

  FriendsOfBehat\MinkDebugExtension:
    proxy_log: true
  

• DOM Diffing: Compare snapshots between runs using git diff:

  git diff features/debug/dom_*.html
  

• Custom Loggers: Override the logger to integrate with Laravel’s logging:

  $debug = $this->getMinkDebug();
  $debug->setLogger(new \Monolog\Logger('behat', [
      new \Monolog\Handler\StreamHandler(storage_path('logs/behat.log'))
  ]));
  

Extension Points

1. Pre/Post Hooks Add logic before/after steps:

   FriendsOfBehat\MinkDebugExtension:
     hooks:
       before_step: ['App\Behat\DebugHooks::beforeStep']
       after_step: ['App\Behat\DebugHooks::afterStep']
   

2. Custom Filters Filter debug output by step type:

   // In a service provider
   $extension->setFilter(function ($event) {
       return $event->getStep()->getType() !== 'background';
   });
   

3. Laravel Events Trigger Laravel events on debug failures:

   event(new \App\Events\BehatStepFailed($step, $debugData));