Mink Selenium Driver Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation:

   composer require behat/mink-selenium-driver
   

   (Note: Requires facebook/webdriver and behat/mink as dependencies. Install them first if missing.)

2. First Use Case:

   • Test a Login Flow:

     use Behat\Mink\Mink;
     use Behat\Mink\Session;
     use Behat\Mink\Driver\SeleniumDriver;
     use Facebook\WebDriver\Remote\RemoteWebDriver;
     
     $mink = new Mink([
         'selenium' => new Session(new SeleniumDriver(RemoteWebDriver::create([
             'browserName' => 'chrome',
             'browser_version' => 'latest',
             'platform' => 'LINUX',
             'selenium_version' => '3.141.59',
         ]), 'http://localhost:4444/wd/hub')),
     ]);
     
     $session = $mink->getSession('selenium');
     $session->visit('/login');
     $session->fillField('email', 'user@example.com');
     $session->fillField('password', 'secret');
     $session->pressButton('Login');
     

3. Where to Look First:

   • Mink Documentation (for Mink basics).
   • Selenium WebDriver Docs (for browser-specific quirks).
   • Laravel-specific: Use Artisan commands to spin up Selenium Grid (e.g., via Docker) for local testing.

Implementation Patterns

Workflows

1. Integration with Laravel Testing:

   • Use Mink in Laravel’s phpunit.xml or a custom test listener:

     <listeners>
         <listener class="App\Tests\MinkTestListener" />
     </listeners>
     

   • Example listener to initialize Mink:

     public function startTestSuite(TestSuite $suite) {
         $this->mink = new Mink([
             'selenium' => new Session(new SeleniumDriver(RemoteWebDriver::create($caps))),
         ]);
     }
     

2. Reusable Test Helpers:

   • Create a trait for common Selenium interactions:

     trait SeleniumHelper {
         public function loginAsUser($email, $password) {
             $session = $this->mink->getSession('selenium');
             $session->visit('/login');
             $session->fillField('email', $email)->fillField('password', $password)->pressButton('Login');
         }
     }
     

3. Parallel Testing:

   • Use Selenium Grid to distribute tests across multiple browsers/machines:

     $caps = DesiredCapabilities::chrome();
     $driver = RemoteWebDriver::create('http://grid-hub:4444/wd/hub', $caps);
     

4. Headless Mode:

   • Run Chrome in headless mode for CI/CD:

     $caps = DesiredCapabilities::chrome();
     $caps->setCapability('goog:chromeOptions', [
         'args' => ['--headless', '--disable-gpu']
     ]);
     

Laravel-Specific Tips

• Service Container Binding: Bind Mink to Laravel’s IoC container for dependency injection:

  $this->app->singleton(Mink::class, function ($app) {
      return new Mink([
          'selenium' => new Session(new SeleniumDriver(RemoteWebDriver::create($app['config']['mink.selenium.caps'])))
      ]);
  });
  

• Configuration: Store Selenium settings in config/mink.php:

  return [
      'selenium' => [
          'hub_url' => env('SELENIUM_HUB_URL', 'http://localhost:4444/wd/hub'),
          'browser' => 'chrome',
          'headless' => env('SELENIUM_HEADLESS', false),
      ],
  ];
  

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • The package is archived and targets Selenium 1/2. Use facebook/webdriver (Selenium 3+) for modern compatibility.
   • Example: Replace Selenium\Client with Facebook\WebDriver\Remote\RemoteWebDriver.

2. Session Management:

   • Mink sessions are not automatically reset between tests. Clean up:

     $session->reset();
     

   • Or use Mink::setDefaultSessionName() to avoid leaks.

3. Browser-Specific Issues:

   • Chrome/Edge may require explicit options for stability:

     $caps->setCapability('goog:chromeOptions', [
         'args' => ['--no-sandbox', '--disable-dev-shm-usage']
     ]);
     

   • Firefox may need geckodriver path:

     $caps->setCapability('moz:firefoxOptions', [
         'binary' => '/path/to/geckodriver'
     ]);
     

4. Performance:

   • Selenium Grid timeouts can kill tests. Set explicit waits:

     $session->wait(10000, function ($context) {
         return $context->getPage()->hasContent('Expected content');
     });
     

Debugging

1. Logs:

   • Enable Selenium verbose logging:

     $driver = RemoteWebDriver::create($caps, 'http://localhost:4444/wd/hub', 5000, true);
     

   • Check Mink’s debug output:

     $session->getDriver()->getStatus();
     

2. Screenshots:

   • Capture failures automatically:

     try {
         $session->clickLink('Broken Link');
     } catch (\Exception $e) {
         $session->takeScreenshot('screenshot.png');
         throw $e;
     }
     

3. Common Errors:

   • "Session not created": Verify Selenium Server is running (java -jar selenium-server.jar).
   • "Element not found": Use explicit waits or check for iframes:

     $session->switchToIFrame('iframe-id')->clickLink('Link');
     

Extension Points

1. Custom Drivers:

   • Extend SeleniumDriver for Laravel-specific logic:

     class LaravelSeleniumDriver extends SeleniumDriver {
         public function loginAsAdmin() {
             $this->getSession()->fillField('email', config('admin.email'));
             // ...
         }
     }
     

2. Event Listeners:

   • Hook into Mink events (e.g., SessionStarted) for setup/teardown:

     $mink->getSession('selenium')->getDriver()->on('sessionStarted', function () {
         // Pre-test setup (e.g., DB seeding)
     });
     

3. Hybrid Testing:

   • Combine with Laravel’s HTTP tests for API + UI flows:

     $response = $this->post('/api/login', ['email' => 'user@example.com']);
     $this->mink->getSession('selenium')->visit('/dashboard'); // Post-login UI test