O Dusk Updater Laravel Package

Getting Started

Run the updater for the first time with:

composer require --dev wpstarter/dusk-updater
./vendor/bin/dusk-updater detect

This checks your current Chrome/ChromeDriver versions and suggests updates if needed. For immediate updates:

./vendor/bin/dusk-updater update

First Use Case: Add to your CI pipeline (e.g., GitHub Actions) as a pre-test step to ensure ChromeDriver compatibility:

- name: Update ChromeDriver
  run: vendor/bin/dusk-updater update 114

Key Files to Review:

• vendor/bin/dusk-updater (CLI entry point)
• composer.json (dev-dependencies section)

Implementation Patterns

1. CI/CD Integration

Workflow:

1. Pre-test Update (Recommended):

   # GitHub Actions example
   - name: Sync ChromeDriver
     run: vendor/bin/dusk-updater update ${{ env.CHROMEDRIVER_VERSION }}
   - name: Run Dusk Tests
     run: php artisan dusk
   

2. Post-build Update (For Docker images):

   RUN composer require --dev wpstarter/dusk-updater && \
       vendor/bin/dusk-updater update 114
   

Best Practices:

• Pin versions (e.g., update 114) to avoid surprises.
• Cache ChromeDriver binaries in CI to reduce download times:

  - name: Cache ChromeDriver
    uses: actions/cache@v3
    with:
      path: vendor/bin/chromedriver*
      key: chromedriver-${{ hashFiles('composer.lock') }}
  

2. Environment-Specific Configurations

Multi-Environment Handling: Use environment variables to specify versions:

# .env
CHROMEDRIVER_VERSION=114

Then invoke:

./vendor/bin/dusk-updater update $CHROMEDRIVER_VERSION

Custom Chrome Paths (Linux/macOS):

./vendor/bin/dusk-updater detect --chrome-dir=/usr/bin/google-chrome-stable

3. Docker Workflows

Dockerfile Example:

FROM laravel/dusk:latest

# Install updater and update ChromeDriver
RUN composer require --dev wpstarter/dusk-updater && \
    vendor/bin/dusk-updater update 114

# Ensure permissions
RUN chmod +x vendor/bin/chromedriver*

Docker Compose:

services:
  dusk:
    build: .
    volumes:
      - ./vendor/bin:/usr/local/bin/vendor
    environment:
      - CHROMEDRIVER_VERSION=114

4. Local Development

Composer Scripts (for convenience):

{
  "scripts": {
    "dusk:update": "dusk-updater update",
    "dusk:detect": "dusk-updater detect --auto-update"
  }
}

Run with:

composer dusk:update

Pre-commit Hook (to validate versions):

#!/bin/sh
./vendor/bin/dusk-updater detect --auto-update || exit 1

5. Standalone PHP Projects

Since this package uses Symfony Console, it works outside Laravel:

# Install globally (optional)
composer global require wpstarter/dusk-updater

# Use in any PHP project
./vendor/bin/dusk-updater update 114

Gotchas and Tips

Pitfalls

1. Permission Denied:

   • Symptom: Permission denied when running dusk-updater.
   • Fix: Ensure vendor/bin/ is writable:

     chmod -R 755 vendor/bin/
     

   • Docker Fix: Add USER root before running the updater in Dockerfile.

2. Version Mismatch:

   • Symptom: Dusk tests fail with SessionNotCreatedException or unknown error: Chrome version must be >= X.
   • Root Cause: ChromeDriver version doesn’t match Chrome/Chromium major version.
   • Fix:
     • Pin versions explicitly (e.g., update 114 for Chrome 114.x).
     • Use detect to validate compatibility:

       ./vendor/bin/dusk-updater detect --auto-update
       

3. Stale ChromeDriver Processes:

   • Symptom: Tests pass locally but fail in CI with Another ChromeDriver server seems to be running.
   • Fix: Kill existing processes before updating:

     pkill chromedriver
     ./vendor/bin/dusk-updater update
     

4. Network Issues:

   • Symptom: Update hangs or fails with cURL error 28.
   • Fix:
     • Use --cache to store releases locally:

       ./vendor/bin/dusk-updater update --cache /tmp/chromedriver-cache
       

     • Proxy support (if behind a firewall):

       export HTTP_PROXY=http://proxy.example.com:8080
       ./vendor/bin/dusk-updater update
       

5. Windows Path Issues:

   • Symptom: Failed to download ChromeDriver on Windows.
   • Fix: Use full paths and ensure vendor/bin/ is in PATH:

     & .\vendor\bin\dusk-updater update 114
     

Debugging Tips

1. Verbose Mode:

   ./vendor/bin/dusk-updater update --verbose
   

   • Reveals download URLs, checksums, and file operations.

2. Dry Run:

   • Check what would happen without downloading:

     ./vendor/bin/dusk-updater detect --dry-run
     

3. Manual Download:

   • If the updater fails, download manually:

     curl -LO https://chromedriver.storage.googleapis.com/114.0.5735.90/chromedriver_linux64.zip
     unzip chromedriver_linux64.zip -d vendor/bin/
     chmod +x vendor/bin/chromedriver
     

Configuration Quirks

1. Cache Directory:

   • Default cache: ~/.cache/dusk-updater (Linux/macOS) or %USERPROFILE%\.cache\dusk-updater (Windows).
   • Override with --cache:

     ./vendor/bin/dusk-updater update --cache /custom/path
     

2. Chrome Detection:

   • The updater checks:
     • google-chrome, google-chrome-stable, chromium, or chromium-browser.
   • Custom paths require --chrome-dir (Linux/macOS only).

3. Version Parsing:

   • Supports:
     • Major version: update 114 (downloads latest 114.x).
     • Exact version: update 114.0.5735.90.
   • Avoid partial versions (e.g., update 114.0 may fail).

Extension Points

1. Custom ChromeDriver Sources:

   • Fork the package to add support for mirror URLs or private repositories.
   • Modify src/ChromeDriverUpdater.php to extend getDownloadUrl().

2. Post-Update Hooks:

   • Add a script to run after updates (e.g., restart services):

     ./vendor/bin/dusk-updater update && ./post-update-hook.sh
     

3. Integration with Other Tools:

   • Playwright: Use the updater to manage ChromeDriver for Playwright’s Chromium.
   • Selenium: Extend to support other WebDriver binaries.

4. GitHub Actions Action:

   • Package as a reusable workflow:

     # .github/actions/update-chromedriver/action.yml
     uses: your-repo/update-chromedriver@v1
     with:
       version: ${{ inputs.version }}
     

Pro Tips

1. Version Pinning in CI:

   jobs:
     test:
       strategy:
         matrix:
           chromedriver: [114, 115]
       steps:
         - run: vendor/bin/dusk-updater update ${{ matrix.chromedriver }}
   

2. Automated Rollback:

   • Backup old binaries before updating:

     cp vendor/bin/chromedriver vendor/bin/chromedriver.bak
     ./vendor/bin/dusk-updater update
     

3. Monitoring:

   • Log updates to a file:

     ./vendor/bin/dusk-updater update >> /var/log/chromedriver-updates.log
     

4. Offline Mode:

   • Pre-download releases and use --cache:

     ./vendor/bin/dusk-updater update --cache /offline-cache