Behat Screenshot Image Driver Cloudinary Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require --dev ezsystems/behat-screenshot-image-driver-cloudinary
   

2. Configure behat.yml:

   default:
     extensions:
       Bex\Behat\ScreenshotExtension:
         active_image_drivers: cloudinary
   

3. First Use Case:

   • Run a failing Behat scenario. The screenshot will automatically upload to Cloudinary, and the URL will appear in the Behat output:

     Screenshot has been taken. Open image at https://res.cloudinary.com/your_cloud_name/...
     

Implementation Patterns

Workflows

1. Signed Uploads (Recommended for Production):

   • Export Cloudinary credentials as environment variables:

     export CLOUDINARY_CLOUD_NAME=your_cloud_name
     export CLOUDINARY_API_KEY=your_api_key
     export CLOUDINARY_API_SECRET=your_api_secret
     

   • No additional config needed in behat.yml.

2. Unsigned Uploads (For Testing):

   • Configure behat.yml with cloud_name and preset:

     image_drivers:
       cloudinary:
         cloud_name: your_cloud_name
         preset: your_preset_name
     

3. Screenshot Directory Management:

   • Set a temporary directory for local screenshot storage:

     screenshot_directory: /tmp/behat-screenshots/
     

   • Ensure the directory is empty before test runs and cleaned afterward.

4. Limit Screenshots:

   • Restrict the number of screenshots per run (default: unlimited):

     limit: 10  # Max 10 screenshots per run
     

   • Disable limits via environment variable:

     export DISABLE_BEHAT_SCREENSHOT_LIMIT=true
     

Integration Tips

• Laravel-Specific:

  • Store Cloudinary credentials in .env:

    CLOUDINARY_CLOUD_NAME=your_cloud_name
    CLOUDINARY_API_KEY=your_api_key
    CLOUDINARY_API_SECRET=your_api_secret
    

  • Load credentials in BehatServiceProvider or test setup:

    putenv('CLOUDINARY_CLOUD_NAME=' . config('services.cloudinary.cloud_name'));
    

• Custom Context Hooks:

  • Override screenshot behavior in a custom context:

    use Behat\Behat\Context\Context;
    use Bex\Behat\ScreenshotExtension\Context\ScreenshotContext;
    
    class CustomScreenshotContext implements Context {
        public function __construct(private ScreenshotContext $screenshotContext) {}
    
        public function beforeScenario(\Behat\Behat\Event\BeforeScenarioScope $event) {
            $this->screenshotContext->setScreenshotDirectory(sys_get_temp_dir() . '/custom_screenshots');
        }
    }
    

Gotchas and Tips

Pitfalls

1. Environment Variables Override Config:

   • If cloud_name, api_key, or api_secret are set as environment variables, they override behat.yml settings. Test locally with unsigned uploads first.

2. Screenshot Directory Permissions:

   • Ensure the screenshot_directory is writable by the web server/user running Behat:

     chmod -R 777 /tmp/behat-screenshots/
     

   • Avoid using /tmp in production; use a dedicated directory.

3. Limit Quirk:

   • The limit feature counts files in screenshot_directory. If tests run in parallel, limits may be hit unexpectedly. Clean the directory after all tests complete.

4. Cloudinary Preset Requirements:

   • For unsigned uploads, the preset must allow uploads from your Behat server’s IP. Test with a temporary preset first.

Debugging

• Failed Uploads:

  • Check Cloudinary logs for errors (e.g., invalid credentials or missing permissions).
  • Enable verbose output in Behat:

    behat --verbose
    

• Missing Screenshots:

  • Verify active_image_drivers includes cloudinary in behat.yml.
  • Ensure the Bex\Behat\ScreenshotExtension is properly loaded (check behat --version).

Extension Points

1. Custom Cloudinary Options:

   • Pass additional Cloudinary parameters via behat.yml (if supported by the driver):

     image_drivers:
       cloudinary:
         transformation: "c_scale,w_800"
     

2. Post-Processing:

   • Use Cloudinary’s API to auto-tag or categorize screenshots by test name/ID. Example:

     // In a custom context or hook
     $this->screenshotContext->addScreenshotMetadata([
         'context' => 'test_id_' . $event->getScenario()->getId(),
     ]);
     

3. Fallback Drivers:

   • Combine with other drivers (e.g., local filesystem) for redundancy:

     active_image_drivers: [cloudinary, local]