Mink Debug Extension Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

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

   Ensure your project already has behat/behat and friends-of-behat/mink-extension installed.

2. Configure Behat Add the extension to your behat.yml under the default profile:

   default:
       extensions:
           FriendsOfBehat\MinkDebugExtension:
               directory: '%paths.base%/debug-logs'  # Replace with your desired path
   

   • Use %paths.base% to reference the directory where behat.yml is located.
   • Ensure the directory exists and is writable (create it manually if needed).

3. First Use Case Run Behat with --strict to trigger debug logs on failures:

   bin/behat --strict
   

   • After a test failure, check the configured directory for:
     • HTML snapshots of the page state.
     • Logs of Mink session data (e.g., form fields, links, CSS selectors).
     • Screenshots (if screenshot: true is configured and a supported driver is used).

Implementation Patterns

Workflows

1. Debugging Failed Scenarios

   • Pattern: Use MinkDebugExtension as a last-resort debugging tool when:
     • A step fails intermittently (e.g., flaky tests).
     • The Mink session state is unclear (e.g., "Element not found" errors).
   • Workflow:
     1. Run behat --strict and let a test fail.
     2. Inspect the generated logs in the configured directory.
     3. Use the HTML snapshots or screenshots to reverse-engineer the issue (e.g., verify if an element is actually missing or hidden).
     4. Update your step definitions or test data accordingly.

2. CI/CD Integration

   • Pattern: Automate debug log generation in CI pipelines for failed builds.
   • Workflow:
     1. Configure the extension in behat.yml with a CI-specific directory (e.g., debug-logs/ci).
     2. Add a post-failure step in your CI script to:
        • Archive the debug logs (e.g., upload to a service like S3 or Slack).
        • Example (GitHub Actions):

          - name: Upload debug logs on failure
            if: failure()
            uses: actions/upload-artifact@v3
            with:
              name: behat-debug-logs
              path: debug-logs/ci
          

     3. Use the logs to diagnose flaky tests or environment-specific issues.

3. Local Development Debugging

   • Pattern: Enable screenshots for quick visual debugging.
   • Workflow:
     1. Update behat.yml to include:

        FriendsOfBehat\MinkDebugExtension:
            directory: '%paths.base%/debug-logs'
            screenshot: true  # Enable screenshots
        

     2. Use a supported Mink driver (e.g., selenium2 or chrome).
     3. Run Behat locally, and inspect screenshots alongside HTML logs for context.

Integration Tips

• Combine with Other Extensions:
  • Pair with Behat\MinkExtension to ensure the Mink session is properly initialized before debugging.
  • Use Behat\Mink\Driver\Selenium2Driver or ChromeDriver for screenshots (other drivers like Goutte may not support screenshots).
• Customize Log Output:
  • Override the default log template by extending the extension’s Logger class (see extension source for hooks).
  • Example: Add custom CSS or JavaScript to highlight problematic elements in snapshots.
• Cleanup Strategy:
  • Set clean_start: false in behat.yml to preserve logs across runs (useful for debugging sequences of failures).
  • Use a script to manually clean logs after investigation:

    rm -rf debug-logs/*
    

Gotchas and Tips

Pitfalls

1. Directory Permissions

   • Issue: The extension fails silently if the directory is unwritable.
   • Fix: Ensure the directory exists and has 777 permissions (or adjust ownership/group).
   • Debug: Check Behat’s output for mkdir() warnings or empty debug logs.

2. Screenshot Limitations

   • Issue: Screenshots only work with drivers that support them (e.g., selenium2, chrome). Drivers like Goutte (HTML-based) will ignore screenshot: true.
   • Fix: Verify your Mink driver in behat.yml:

     default:
         extensions:
             Behat\MinkExtension:
                 base_url: http://example.com
                 goutte: ~  # No screenshots
                 selenium2: ~  # Screenshots supported
     

   • Workaround: Use Goutte for HTML debugging and switch to selenium2 for visual debugging.

3. Log Overwrite Behavior

   • Issue: clean_start: true (default) deletes logs before each run, which may hide cumulative debugging data.
   • Fix: Set clean_start: false temporarily to preserve logs for multi-step debugging:

     FriendsOfBehat\MinkDebugExtension:
         clean_start: false
     

4. Strict Mode Requirement

   • Issue: Debug logs only generate when Behat runs in --strict mode.
   • Fix: Always include --strict in your debug commands:

     bin/behat --strict --tags=@smoke
     

5. Large Log Files

   • Issue: Debug logs can grow large with complex pages (e.g., SPAs or heavily dynamic content).
   • Fix:
     • Filter logs by excluding irrelevant elements (e.g., ignore input[type="hidden"]).
     • Use screenshot: true sparingly for targeted debugging.

Debugging Tips

1. Inspect the HTML Snapshots

   • Open the generated *.html files in a browser to:
     • Verify element existence/visibility.
     • Check for JavaScript-rendered content (e.g., React/Vue apps).
     • Validate CSS selectors used in your step definitions.

2. Leverage Screenshots for Visual Regression

   • Compare screenshots across runs to spot UI changes or rendering issues.
   • Tools like diffimg can automate screenshot comparison:

     diffimg old-screenshot.png new-screenshot.png
     

3. Debug Mink Session State

   • Use the logs to inspect the Mink session’s getHtml(), getTitle(), or getCurrentUrl() at the time of failure.
   • Example: If a step expects a title of "Dashboard" but fails, check the log for the actual title.

4. Extend the Extension

   • Custom Logging: Override the Logger class to add metadata (e.g., test environment, timestamp). Example hook in a custom extension:

     use FriendsOfBehat\MinkDebugExtension\Logger;
     
     class CustomLogger extends Logger {
         public function log($message) {
             parent::log("[ENV: " . getenv('APP_ENV') . "] " . $message);
         }
     }
     

   • Post-Processing: Add a post-failure hook to process logs (e.g., extract failed selectors to a report).

5. CI-Specific Quirks

   • Headless Browsers: Ensure your CI environment supports headless drivers (e.g., selenium2 with --headless).
   • Resource Limits: Debug logs may hit disk space limits in CI. Configure clean_start: true and archive logs post-failure.

Configuration Quirks

• Path Variables:
  • %paths.base% resolves to the directory containing behat.yml. Use absolute paths if needed:

    directory: /var/www/project/debug-logs
    

• Nested Directories:
  • The extension creates subdirectories per test suite/run. Avoid flat paths like ./logs to prevent clutter.
• Case Sensitivity:
  • Directory paths are case-sensitive on Linux/macOS. Use consistent casing (e.g., DebugLogs vs. debug-logs).