Behat Screenshot Laravel Package

Getting Started

1. Installation:

   composer require --dev bex/behat-screenshot
   

   Add the extension to your behat.yml:

   default:
     extensions:
       Bex\Behat\ScreenshotExtension: ~
   

2. First Use Case: Run your Behat tests. When a step fails, the extension automatically captures a screenshot and outputs the path (e.g., /tmp/behat-screenshot/failed_step.png). No additional code changes are required—just enable the extension.

3. Where to Look First:

   • Check behat.yml for configuration.
   • Review the README for driver options (e.g., local, uploadpie).
   • Verify PHP extensions (fileinfo) are installed (required for image handling).

Implementation Patterns

Basic Workflow

1. Enable for Debugging: Use the local driver to save screenshots to a directory (e.g., storage/screenshots):

   extensions:
     Bex\Behat\ScreenshotExtension:
       image_drivers:
         local:
           screenshot_directory: "%paths.base%/storage/screenshots"
           clear_screenshot_directory: true  # Clears dir before tests
   

2. Cloud Integration: Use a third-party driver (e.g., uploadpie) to upload screenshots to a service like Imgur:

   extensions:
     Bex\Behat\ScreenshotExtension:
       active_image_drivers: [uploadpie]
       image_drivers:
         uploadpie:
           api_key: "your_api_key"
   

   Output: Direct URL to the screenshot in the terminal (e.g., Screenshot uploaded: https://i.imgur.com/abc123.png).

3. Combined Screenshots: Capture all steps in a failed scenario (not just the failing step):

   extensions:
     Bex\Behat\ScreenshotExtension:
       screenshot_taking_mode: failed_scenarios
   

Integration Tips

• Laravel-Specific: Use Laravel’s storage_path() helper in behat.yml:

  screenshot_directory: "%paths.base%/storage/app/screenshots"
  

  Ensure the directory is writable (chmod -R 775 storage/screenshots).

• CI/CD: Disable screenshots in CI to avoid clutter:

  ci:
    extensions:
      Bex\Behat\ScreenshotExtension:
        enabled: false
  

• Scenario Outlines: The extension supports dynamic scenarios (e.g., @dataProvider). No extra config is needed.

Gotchas and Tips

Pitfalls

1. Session Not Started:

   • Issue: Screenshots fail with Session not started errors.
   • Fix: Ensure your Behat\Mink\Driver (e.g., Selenium2Driver) is properly initialized before steps run. Example:

     // In your FeatureContext constructor
     $this->getSession()->start();
     

2. Directory Permissions:

   • Issue: Screenshots save to /tmp but fail silently.
   • Fix: Explicitly set a writable directory (e.g., storage/screenshots) and verify permissions:

     mkdir -p storage/screenshots && chmod -R 775 storage/screenshots
     

3. Missing PHP Extensions:

   • Issue: fileinfo extension is required but missing.
   • Fix: Install it via:

     pecl install fileinfo
     

     Or enable in php.ini:

     extension=fileinfo
     

4. Driver Conflicts:

   • Issue: Multiple drivers configured but only one works.
   • Fix: Ensure active_image_drivers lists only enabled drivers (e.g., active_image_drivers: [local]).

Debugging Tips

• Check Logs: Enable Behat’s verbose mode to see driver initialization:

  bin/behat --verbose
  

• Custom Drivers: If creating a driver, implement Bex\Behat\ScreenshotExtension\Driver\ImageDriverInterface and register it in behat.yml:

  image_drivers:
    custom:
      class: App\CustomDriver
      config: { "api_url": "https://example.com/upload" }
  

• Clear Directory: Use clear_screenshot_directory: true to avoid stale screenshots, but ensure the directory exists first.

Extension Points

1. Post-Screenshot Hooks: Extend the Bex\Behat\ScreenshotExtension\Event\ScreenshotTakenEvent to process screenshots (e.g., rename, tag):

   // In a service provider
   $eventDispatcher->addListener(
       ScreenshotTakenEvent::class,
       function (ScreenshotTakenEvent $event) {
           // Custom logic (e.g., upload to S3)
       }
   );
   

2. Conditional Screenshots: Disable screenshots for specific scenarios using tags:

   @no-screenshot
   Scenario: Skip screenshot for this test
   

   Note: Requires custom context logic to filter events.

3. Screenshot Naming: Override the default filename format (e.g., include step text):

   extensions:
     Bex\Behat\ScreenshotExtension:
       screenshot_filename_pattern: "step_{step}.png"