Mink Phpwebdriver Extension Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev oleg-andreyev/mink-phpwebdriver-extension
   

2. Configure behat.yml: Add the extension under Behat\MinkExtension with wd_host pointing to your Selenium Grid or standalone WebDriver:

   default:
     extensions:
       OAndreyev\MinkPhpWebdriverExtension: ~
       Behat\MinkExtension:
         default_session: webdriver
         webdriver:
           wd_host: "http://localhost:4444/wd/hub"  # Default Selenium 4+ endpoint
   

3. First Use Case: Write a feature with Mink steps (e.g., Given I am on "/login"). The extension bridges Mink’s PhpBrowser with PhpWebDriver, enabling real browser automation.

Implementation Patterns

Workflow Integration

1. Replace PhpBrowser with PhpWebDriver: The extension overrides Mink’s default session to use PhpWebDriver instead of PhpBrowser. No additional code changes are needed for basic Mink steps (e.g., click, fillField).

2. Leverage WebDriver-Specific Features: Use WebDriver’s capabilities (e.g., JavaScript execution, mobile emulation) via Mink’s getSession():

   $session = $this->getSession();
   $session->executeScript('return window.innerWidth;');
   

3. Session Management:

   • Start/stop sessions via Behat hooks:

     BeforeScenario:
       - Mink\Driver\WebDriver\WebDriverDriver::startSession
     AfterScenario:
       - Mink\Driver\WebDriver\WebDriverDriver::stopSession
     

4. Parallel Testing: Configure multiple wd_host environments in behat.yml and use Behat’s parallel tags:

   environments:
     chrome:
       webdriver:
         wd_host: "http://chrome-grid:4444"
     firefox:
       webdriver:
         wd_host: "http://firefox-grid:4444"
   

Common Patterns

• Dynamic Capabilities: Pass WebDriver capabilities via behat.yml:

  webdriver:
    capabilities:
      browserName: chrome
      chromeOptions:
        args: ["--headless"]
  

• Custom Drivers: Extend PhpWebDriver for project-specific needs (e.g., custom wait conditions):

  use Facebook\WebDriver\Remote\RemoteWebDriver;
  class CustomWebDriver extends RemoteWebDriver { ... }
  

Gotchas and Tips

Pitfalls

1. Host Configuration:

   • Issue: wd_host misconfigured (e.g., missing /wd/hub for Selenium 4).
   • Fix: Use http://localhost:4444/wd/hub for Selenium 4+ or http://localhost:4444 for older versions.

2. Session Leaks:

   • Issue: Unclosed sessions cause port exhaustion.
   • Fix: Always use AfterScenario hooks to stop sessions or enable Behat’s stop_on_failure.

3. Dependency Conflicts:

   • Issue: Conflicts with other Mink extensions (e.g., Behat\MinkExtension).
   • Fix: Ensure oleg-andreyev/mink-phpwebdriver-extension is listed after Behat\MinkExtension in behat.yml.

4. JavaScript Errors:

   • Issue: WebDriver ignores JS errors by default.
   • Fix: Configure capabilities to throw errors:

     webdriver:
       capabilities:
         goog:chromeOptions:
           args: ["--disable-js-harmony"]
     

Debugging Tips

• Logs: Enable WebDriver logs via capabilities:

  webdriver:
    capabilities:
      loggingPrefs:
        browser: ALL
  

  Access logs in Behat:

  $logs = $session->getLog('browser');
  

• Headless Mode: Use Chrome/Firefox headless options for CI:

  webdriver:
    capabilities:
      browserName: chrome
      chromeOptions:
        args: ["--headless=new", "--disable-gpu"]
  

Extension Points

1. Custom Drivers: Override the default PhpWebDriver by binding a service in Behat’s DI container:

   services:
     mink.driver.webdriver:
       class: Your\Custom\WebDriver
   

2. Hooks: Extend session lifecycle with custom hooks:

   BeforeScenario:
     - @customHook
   

   public function customHook(BeforeScenarioScope $scope) {
       $session = $scope->getEnvironment()->getContext()->getSession();
       $session->executeScript('window.customSetup = true;');
   }
   

3. Environment-Specific Configs: Use Behat’s environments to switch WebDriver setups:

   environments:
     staging:
       webdriver:
         wd_host: "https://staging-selenium:4444"
         capabilities:
           browserName: firefox