Webdriver Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-webdriver/php-webdriver
   

   (Note: The original facebook/webdriver is archived; use php-webdriver/php-webdriver as the README suggests.)

2. Basic Usage

   use Facebook\WebDriver\Remote\RemoteWebDriver;
   use Facebook\WebDriver\WebDriverBy;
   
   $host = 'http://localhost:4444/wd/hub'; // Selenium Server
   $capabilities = Facebook\WebDriver\Remote\DesiredCapabilities::chrome();
   
   $driver = RemoteWebDriver::create($host, $capabilities);
   $driver->get('https://example.com');
   echo $driver->getTitle();
   $driver->quit();
   

3. First Use Case Automate a login flow:

   $driver->findElement(WebDriverBy::name('username'))->sendKeys('user@example.com');
   $driver->findElement(WebDriverBy::name('password'))->sendKeys('password123');
   $driver->findElement(WebDriverBy::name('submit'))->click();
   

Implementation Patterns

Common Workflows

1. Page Object Pattern Encapsulate interactions in reusable classes:

   class LoginPage {
       private $driver;
   
       public function __construct(RemoteWebDriver $driver) {
           $this->driver = $driver;
       }
   
       public function login($username, $password) {
           $this->driver->findElement(WebDriverBy::name('username'))->sendKeys($username);
           $this->driver->findElement(WebDriverBy::name('password'))->sendKeys($password);
           $this->driver->findElement(WebDriverBy::name('submit'))->click();
       }
   }
   

2. Test Integration Use with PHPUnit for E2E testing:

   use Facebook\WebDriver\Testing\FBWebDriverTestCase;
   
   class ExampleTest extends FBWebDriverTestCase {
       public function testExample() {
           $this->driver->get('https://example.com');
           $this->assertEquals('Example Domain', $this->driver->getTitle());
       }
   }
   

3. Dynamic Element Handling Wait for elements with explicit waits:

   use Facebook\WebDriver\WebDriverWait;
   use Facebook\WebDriver\ExpectedCondition;
   
   $wait = new WebDriverWait($driver, 10);
   $element = $wait->until(ExpectedCondition::presenceOfElementLocated(WebDriverBy::id('dynamic-element')));
   

Integration Tips

• Docker Setup: Run Selenium Server in a container:

  # docker-compose.yml
  services:
    selenium:
      image: selenium/standalone-chrome
      ports:
        - "4444:4444"
  

• Headless Mode: Configure Chrome for headless testing:

  $capabilities = Facebook\WebDriver\Remote\DesiredCapabilities::chrome();
  $capabilities->setCapability('goog:chromeOptions', [
      'args' => ['--headless', '--disable-gpu']
  ]);
  

• Parallel Testing: Use multiple instances with unique ports or hubs.

Gotchas and Tips

Pitfalls

1. Deprecation Warnings

   • The facebook/webdriver package is archived; migrate to php-webdriver/php-webdriver.
   • Some methods (e.g., findElements()) may return WebElement objects that behave differently than expected. Always check for null or exceptions.

2. Session Management

   • Forgotten quit(): Always call $driver->quit() to release resources and avoid zombie sessions.
   • Implicit Waits: Overuse can slow tests. Prefer explicit waits (WebDriverWait) for reliability.

3. Cross-Browser Quirks

   • Firefox (GeckoDriver) and Chrome may require different capabilities or handle events differently.
   • Example: Chrome may need goog:chromeOptions for extensions or flags.

4. Stale Elements

   • Elements can become stale after page navigation or DOM changes. Re-fetch them:

     try {
         $element->click();
     } catch (\Facebook\WebDriver\Exception\StaleElementReferenceException $e) {
         $element = $driver->findElement(WebDriverBy::id('element-id'));
         $element->click();
     }
     

Debugging

1. Logs and Verbose Output Enable verbose logging for WebDriver:

   $capabilities->setCapability('loggingPrefs', ['browser' => 'ALL']);
   $logs = $driver->manage()->getLog('browser');
   

2. Screenshots on Failure Capture screenshots in tests:

   try {
       $driver->findElement(WebDriverBy::id('nonexistent'))->click();
   } catch (\Exception $e) {
       $driver->takeScreenshot('screenshot.png');
       throw $e;
   }
   

3. Common Exceptions

   • NoSuchElementException: Element not found. Verify selectors or waits.
   • TimeoutException: Adjust wait times or check network conditions.
   • WebDriverException: Server issues. Restart Selenium or check hub status.

Extension Points

1. Custom Commands Extend RemoteWebDriver for domain-specific actions:

   class CustomDriver extends RemoteWebDriver {
       public function scrollToBottom() {
           $this->executeScript("window.scrollTo(0, document.body.scrollHeight);");
       }
   }
   

2. Event Listeners Hook into browser events (e.g., beforeNavigate):

   $driver->manage()->addEventListener('beforeNavigate', function ($event) {
       // Log navigation events
   });
   

3. W3C WebDriver Support

   • Use W3C capabilities for modern browsers (Chrome 78+, Firefox 70+):

     $capabilities->setCapability('browserName', 'chrome');
     $capabilities->setCapability('browserVersion', 'latest');
     $capabilities->setCapability('platformName', 'Windows NT');
     

4. Proxy Configuration Route traffic through a proxy for testing:

   $capabilities->setCapability('proxy', [
       'httpProxy' => 'http://proxy.example.com:8080',
       'sslProxy' => 'http://proxy.example.com:8080'
   ]);
   

Configuration Quirks

• GeckoDriver Path: Ensure GeckoDriver is in PATH or specify its location:

  $capabilities->setCapability('marionette', true);
  putenv('PATH=' . getcwd() . '/path/to/geckodriver:' . getenv('PATH'));
  

• ChromeDriver Path: Similarly, set webdriver.chrome.driver for Chrome:

  putenv('webdriver.chrome.driver=' . getcwd() . '/chromedriver');
  

• Selenium Grid: For distributed testing, configure hub/node URLs:

  $host = 'http://hub.example.com:4444/wd/hub';