Behat Mink Selenium2 Driver Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require atk4/behat-mink-selenium2-driver
   

   Ensure behat/mink and behat/mink-selenium2-driver (or similar) are also installed.

2. Configure Mink in behat.yml Update your Behat config to use the ATK4 driver:

   default:
     extensions:
       Behat\MinkExtension:
         base_url: 'http://your-laravel-app.test'
         goutte: ~
         selenium2: ~
         drivers:
           selenium2:
             host: 'localhost'
             port: 4444
             browser: 'chrome'
             atk4:
               class: 'Atk4\Mink\Driver\Selenium2\Atk4Driver'
   

3. First Use Case: Basic Test Write a feature file to test a Laravel route:

   Feature: Login Test
     Scenario: User logs in successfully
       Given I am on "/login"
       When I fill in "email" with "user@example.com"
       And I fill in "password" with "password123"
       And I press "Login"
       Then I should see "Dashboard"
   

Implementation Patterns

Workflow: Laravel Integration

1. Laravel Session Handling Use the driver’s ability to persist sessions across tests:

   // In a Behat context
   public function __construct() {
       $this->getSession()->start();
   }
   

2. Dynamic URL Generation Leverage Laravel’s URL helpers in Behat contexts:

   use Illuminate\Support\Facades\URL;
   
   public function visitLaravelRoute($route) {
       $url = URL::to($route);
       $this->getSession()->visit($url);
   }
   

3. Form Submission with CSRF Tokens Extract CSRF tokens from Laravel’s meta tags:

   public function fillFormWithCsrf($form, $fields) {
       $csrfToken = $this->getSession()->getPage()->find('meta[name="csrf-token"]')->getAttribute('content');
       $fields['_token'] = $csrfToken;
       foreach ($fields as $name => $value) {
           $this->getSession()->getPage()->fillField($name, $value);
       }
       $this->getSession()->getPage()->pressButton('submit');
   }
   

4. Database Testing Use Laravel’s DatabaseTransactions trait to reset the DB after each test:

   use Illuminate\Foundation\Testing\DatabaseTransactions;
   
   class FeatureContext extends MinkContext {
       use DatabaseTransactions;
   }
   

Gotchas and Tips

Pitfalls

1. Selenium Server Dependency

   • Issue: Tests fail if Selenium Server isn’t running.
   • Fix: Use Docker or a local instance:

     docker run -d -p 4444:4444 selenium/standalone-chrome
     

   • Tip: Add a pre-test hook to start/stop Selenium in behat.yml:

     suites:
       default:
         before_scenarios:
           - Atk4\Mink\Driver\Selenium2\Atk4Driver::ensureSeleniumRunning
     

2. Headless Mode Quirks

   • Issue: Chrome headless may render elements incorrectly.
   • Fix: Use args in the driver config:

     drivers:
       selenium2:
         atk4:
           args:
             - '--headless=new'
             - '--disable-gpu'
     

3. Laravel Mix Assets

   • Issue: Tests fail if assets aren’t compiled.
   • Fix: Run npm run dev or npm run prod in a pre-test hook.

4. Slow Tests

   • Issue: Selenium is slower than Goutte.
   • Tip: Use @mink tags to skip Selenium tests in CI:

     @mink
     Scenario: Slow Selenium test
     

Debugging Tips

1. Screenshots on Failure Add this to your behat.yml:

   extensions:
     Behat\MinkExtension:
       selenium2:
         atk4:
           screenshot_on_failure: true
   

2. Log Driver Output Enable Selenium logs:

   drivers:
     selenium2:
       atk4:
         log_level: 'info'
   

3. Inspect Elements Use the executeScript method to debug:

   $this->getSession()->executeScript('return document.body.innerHTML');
   

Extension Points

1. Custom Wait Conditions Extend the driver for Laravel-specific waits:

   use Atk4\Mink\Driver\Selenium2\Atk4Driver;
   
   class LaravelAtk4Driver extends Atk4Driver {
       public function waitForAJAX() {
           return $this->wait(10, function () {
               return $this->executeScript('return jQuery.active == 0');
           });
       }
   }
   

2. Laravel Auth Context Create a context for auth flows:

   class AuthContext implements Context {
       public function loginAs($user) {
           $this->visit('/login');
           $this->fillField('email', $user['email']);
           $this->fillField('password', $user['password']);
           $this->pressButton('Login');
       }
   }
   

3. API + UI Testing Combine with Laravel’s HTTP tests:

   public function assertAPIAndUI($endpoint, $expectedUI) {
       $response = Http::post('/api/' . $endpoint);
       $this->visit('/dashboard');
       $this->assertPageContains($expectedUI);
   }