Mink Selenium2 Driver Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation:

   composer require behat/mink-selenium2-driver --dev
   

   Add to composer.json under require-dev to avoid production bloat.

2. First Use Case:

   • Test a Login Flow:

     use Behat\Mink\Mink;
     use Behat\Mink\Session;
     use Behat\Mink\Driver\Selenium2Driver;
     
     $mink = new Mink([
         'selenium2' => new Session(new Selenium2Driver('chrome')),
     ]);
     $session = $mink->getSession('selenium2');
     $session->visit('/login');
     $session->fillField('email', 'user@example.com');
     $session->fillField('password', 'secret');
     $session->pressButton('Login');
     

3. Where to Look First:

   • Mink Documentation (core Mink concepts).
   • Selenium2Driver README (browser-specific configs, e.g., firefox, chrome).
   • Laravel-specific: Use phpunit.xml or behat.yml for configuration (see below).

Implementation Patterns

Laravel Integration Workflows

1. PHPUnit + Mink:

   • Extend PHPUnit\Framework\TestCase and initialize Mink in setUp():

     protected function setUp(): void
     {
         $this->mink = new Mink([
             'selenium2' => new Session(new Selenium2Driver('chrome', '/path/to/chromedriver')),
         ]);
     }
     

   • Tear Down: Quit sessions in tearDown() to avoid zombie processes:

     protected function tearDown(): void
     {
         $this->mink->getSession()->quit();
     }
     

2. Behat Integration:

   • Configure behat.yml:

     default:
       extensions:
         Behat\MinkExtension:
           base_url: 'http://localhost:8000'
           selenium2:
             wd_host: 'http://localhost:4444/wd/hub'
           browsers:
             chrome:
               browser: 'chrome'
               wd_host: 'http://localhost:4444/wd/hub'
     

   • Run tests:

     vendor/bin/behat --config behat.yml
     

3. Dusk Alternative:

   • If using Laravel Dusk, avoid duplication by reusing Mink’s Selenium2Driver for cross-browser testing:

     use Laravel\Dusk\Browser;
     use Behat\Mink\Driver\Selenium2Driver;
     
     // In a custom Dusk trait:
     protected function createMinkSession(): Session
     {
         return new Session(new Selenium2Driver('firefox'));
     }
     

4. Dynamic Browser Selection:

   • Use environment variables (e.g., .env.testing) to switch browsers:

     $browser = env('BROWSER', 'chrome');
     $driver = new Selenium2Driver($browser, env('WD_HOST'));
     

Gotchas and Tips

Pitfalls

1. Driver Paths:

   • Chrome/Firefox: Ensure chromedriver/geckodriver is in PATH or specify full paths:

     new Selenium2Driver('chrome', '/usr/local/bin/chromedriver')
     

   • Docker: Mount drivers into containers or use pre-built images (e.g., selenium/standalone-chrome).

2. Session Management:

   • Zombie Sessions: Always call $session->quit() to free resources. Use try-finally for safety:

     try {
         $session->visit('/dashboard');
     } finally {
         $session->quit();
     }
     

   • Laravel Artisan: Avoid memory leaks in CLI tests by resetting sessions:

     Artisan::call('mink:quit'); // Custom Artisan command to quit all sessions.
     

3. Headless Mode:

   • Chrome: Add arguments for headless testing:

     $driver = new Selenium2Driver('chrome', null, [
         'chromeOptions' => ['args' => ['--headless', '--disable-gpu']],
     ]);
     

   • Firefox: Use moz:firefoxOptions:

     $driver = new Selenium2Driver('firefox', null, [
         'moz:firefoxOptions' => ['args' => ['-headless']],
     ]);
     

4. Slow Tests:

   • Implicit Waits: Set a global timeout to avoid flaky tests:

     $session->getDriver()->wait(2000); // 2-second implicit wait.
     

   • Parallelization: Use Selenium Grid for distributed testing (configure wd_host to point to hub).

Debugging Tips

1. Logs:

   • Enable verbose logging for Selenium commands:

     $driver = new Selenium2Driver('chrome', null, [], null, [
         'loggingPrefs' => ['browser' => 'ALL'],
     ]);
     

   • Check logs in var/log/mink.log (if configured in MinkExtension).

2. Screenshots:

   • Capture screenshots on failure:

     if ($session->getPage()->hasContent('Error')) {
         $session->takeScreenshot('error.png');
     }
     

3. Common Errors:

   • SessionNotCreatedException: Verify browser/driver compatibility (e.g., Chrome 100+ requires chromedriver 100+).
   • ElementNotFoundException: Use explicit waits:

     $session->wait(5000, function ($context) {
         return $context->getSession()->getPage()->has('css', '.loader');
     });
     

Extension Points

1. Custom Capabilities:

   • Extend browser capabilities for advanced setups (e.g., mobile emulation):

     $driver = new Selenium2Driver('chrome', null, [
         'chromeOptions' => [
             'args' => ['--window-size=375,812'], // iPhone X
             'extensions' => ['path/to/extension.crx'],
         ],
     ]);
     

2. Proxy Support:

   • Route traffic through a proxy (e.g., for testing geo-restrictions):

     $driver = new Selenium2Driver('chrome', null, [
         'proxy' => [
             'httpProxy' => 'http://proxy-server:8080',
             'sslProxy' => 'http://proxy-server:8080',
         ],
     ]);
     

3. Laravel Service Provider:

   • Bind Mink to the container for dependency injection:

     // app/Providers/AppServiceProvider.php
     public function register()
     {
         $this->app->singleton(Mink::class, function () {
             return new Mink([
                 'selenium2' => new Session(new Selenium2Driver('chrome')),
             ]);
         });
     }