Behat Chrome Extension Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev dmore/behat-chrome-extension
   

   Register the extension in behat.yml:

   extensions:
       Behat\ChromeExtension\Extension: ~
   

2. First Use Case Configure Chrome in features/bootstrap/ChromeContext.php:

   use Behat\ChromeExtension\Context\ChromeContext;
   
   class FeatureContext extends ChromeContext
   {
       protected function getChromeOptions(): array
       {
           return [
               'args' => ['--headless', '--disable-gpu'],
               'binary' => '/path/to/chromium',
           ];
       }
   }
   

3. Basic Test Example

   Feature: Chrome Interaction
     Scenario: Open a URL
       Given I open "/"
       Then I should see "Welcome"
   

   Implement steps in FeatureContext:

   use Behat\ChromeExtension\Context\ChromeContext;
   
   class FeatureContext extends ChromeContext
   {
       /**
        * @Given I open :url
        */
       public function openUrl($url)
       {
           $this->getSession()->getPage()->open($url);
       }
   
       /**
        * @Then I should see :text
        */
       public function assertPageContainsText($text)
       {
           $this->assertSession()->pageTextContains($text);
       }
   }
   

Implementation Patterns

Workflows

1. Page Object Pattern Encapsulate Chrome interactions in reusable classes:

   class LoginPage
   {
       use ChromeContext;
   
       public function login($username, $password)
       {
           $this->fillField('#username', $username);
           $this->fillField('#password', $password);
           $this->pressButton('#submit');
       }
   }
   

2. Session Management Reuse Chrome sessions across scenarios:

   /**
    * @BeforeScenario
    */
   public function startSession()
   {
       $this->getSession()->start();
   }
   
   /**
    * @AfterScenario
    */
   public function stopSession()
   {
       $this->getSession()->stop();
   }
   

3. Integration with Laravel Use Chrome for testing API-driven UIs:

   /**
    * @Given I make a POST request to :endpoint with :data
    */
   public function makePostRequest($endpoint, $data)
   {
       $response = Http::post($endpoint, $data);
       $this->getSession()->getPage()->setContent($response->body());
   }
   

Tips for Daily Use

• Leverage Chrome DevTools Protocol (CDP) Access CDP methods directly:

  $this->getSession()->getDriver()->executeScript('Network.enable()');
  

• Headless vs. Headful Toggle headless mode dynamically:

  $this->getChromeOptions()['args'] = ['--no-sandbox']; // Headful
  

• Custom Chrome Profiles Use pre-configured profiles:

  # behat.yml
  extensions:
      Behat\ChromeExtension\Extension:
          profile: '~/.config/google-chrome/Default'
  

Gotchas and Tips

Pitfalls

1. Binary Path Issues

   • Symptom: Chrome fails to launch with execvp: No such file or directory.
   • Fix: Ensure binary path in getChromeOptions() is correct. Use absolute paths.

     'binary' => '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
     

2. Session Leaks

   • Symptom: Tests hang or Chrome processes remain after execution.
   • Fix: Explicitly stop sessions in @AfterScenario or use try-finally:

     try {
         $this->getSession()->start();
         // Test logic
     } finally {
         $this->getSession()->stop();
     }
     

3. CDP Version Mismatch

   • Symptom: CDP commands fail with Protocol error (Session closed).
   • Fix: Ensure Chrome version matches the CDP protocol version supported by the extension. Update Chrome or the extension:

     composer update dmore/behat-chrome-extension
     

Debugging Tips

• Enable Chrome Logging Add debug flags to getChromeOptions():

  'args' => [
      '--headless=new',
      '--disable-gpu',
      '--remote-debugging-port=9222',
      '--v=1' // Enable verbose logging
  ]
  

• Inspect CDP Traffic Use Chrome DevTools to monitor CDP traffic at http://localhost:9222.

• Check for Conflicting Extensions Disable Chrome extensions that may interfere with CDP commands (e.g., ad blockers).

Extension Points

1. Custom Chrome Drivers Extend the base driver for specialized needs:

   use Behat\ChromeExtension\Driver\ChromeDriver;
   
   class CustomChromeDriver extends ChromeDriver
   {
       public function customMethod()
       {
           return $this->executeScript('return customFunction();');
       }
   }
   

2. Hook into Session Events Override session lifecycle methods:

   class FeatureContext extends ChromeContext
   {
       protected function onSessionStart()
       {
           $this->getSession()->getDriver()->executeScript('window.testVar = "started";');
       }
   }
   

3. Add Custom Step Definitions Extend the context with domain-specific steps:

   /**
    * @Given I take a screenshot and save it to :path
    */
   public function takeScreenshot($path)
   {
       $screenshot = $this->getSession()->getScreenshot();
       file_put_contents($path, $screenshot);
   }