Mink Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev behat/mink
   

   Mink is primarily used with Behat, but can be standalone for testing. For Laravel, pair it with behat/behat and mink-browserkit-driver (for testing HTTP requests) or mink-selenium-driver (for browser automation).

2. Basic Configuration (in behat.yml or standalone PHP):

   default:
     extensions:
       Behat\MinkExtension:
         base_url: 'http://your-laravel-app.test'
         browser_name: 'chrome'
         goutte: ~  # For simple HTTP testing (no JS)
         selenium2: ~  # For browser automation (requires Selenium server)
   

3. First Use Case: Test a Laravel route with GoutteDriver (no JS):

   use Behat\Mink\Session;
   use Behat\Mink\Driver\GoutteDriver;
   
   $client = new \GuzzleHttp\Client();
   $driver = new GoutteDriver($client);
   $session = new Session($driver);
   $session->start();
   
   $session->visit('/login');
   $session->getPage()->fillField('email', 'user@example.com');
   $session->getPage()->pressButton('Login');
   

Implementation Patterns

Laravel-Specific Workflows

1. Testing Auth Routes: Use Mink to simulate login flows with Laravel’s session handling:

   $session->visit('/login');
   $session->getPage()->fillField('email', 'user@example.com');
   $session->getPage()->fillField('password', 'secret');
   $session->getPage()->pressButton('Login');
   
   // Assert session cookie is set (Laravel's auth cookie)
   $cookies = $session->getCookieJar()->all();
   assert(array_key_exists('laravel_session', $cookies));
   

2. Integration with Laravel’s HTTP Tests: Combine Mink with Laravel’s Testing facade for hybrid testing:

   use Illuminate\Foundation\Testing\TestCase;
   
   class ExampleTest extends TestCase {
       public function testWithMink() {
           $this->app->make('mink')->getSession()->visit('/dashboard');
           $this->assertEquals('Dashboard', $this->app->make('mink')->getSession()->getPage()->getTitle());
       }
   }
   

3. Selenium for JavaScript-Heavy Apps: Configure Selenium in behat.yml:

   selenium2:
     wd_host: "http://localhost:4444/wd/hub"
   

   Then use it in tests:

   $session = $this->getSession('selenium2');
   $session->visit('/dashboard');
   $session->wait(3000); // Wait for JS to load
   

4. Data-Driven Testing: Use Mink with Behat’s Gherkin syntax to externalize test cases:

   Feature: User Login
     Scenario: Successful login
       Given I am on the "/login" page
       When I fill in "email" with "user@example.com"
       And I fill in "password" with "secret"
       And I press "Login"
       Then I should see "Dashboard"
   

Gotchas and Tips

Pitfalls

1. Session Management:

   • Mink sessions do not share cookies with Laravel’s default TestResponse or HttpClient. Use getCookieJar() to inspect or manually set cookies.
   • Fix: For Laravel auth, manually set the session cookie after login:

     $session->getCookieJar()->set('laravel_session', $laravelSessionCookie);
     

2. Selenium Dependencies:

   • Requires a running Selenium server (e.g., Docker: selenium/standalone-chrome).
   • Tip: Use docker-compose.yml to spin up Selenium:

     services:
       selenium:
         image: selenium/standalone-chrome
         ports:
           - "4444:4444"
     

3. Goutte Limitations:

   • No JavaScript execution. For SPAs or JS-dependent features, use Selenium.
   • Workaround: Test API endpoints directly with Laravel’s Http tests.

4. Headless Mode:

   • Selenium in headless mode (--headless) may miss visual issues (e.g., overlapping elements).
   • Tip: Run visually in CI with xvfb (X virtual framebuffer):

     xvfb-run --server-args="-screen 0, 1280x800x24" behat
     

5. Slow Tests:

   • Selenium tests are slow. Use wait() sparingly and prefer Goutte for non-JS paths.
   • Tip: Cache Selenium sessions or use mink-parallel-testrunner for parallel execution.

Debugging Tips

1. Inspect the Page:

   $html = $session->getPage()->getHtml();
   file_put_contents('debug.html', $html); // Save to file
   

2. Enable Mink’s Debug Output:

   $session->getDriver()->setDebug(true);
   

3. Laravel-Specific Debugging:

   • Dump Laravel’s session data:

     dd(session()->all());
     

   • Compare Mink’s cookies with Laravel’s:

     dd($session->getCookieJar()->all(), session()->getCookieJar()->get('laravel_session'));
     

Extension Points

1. Custom Drivers: Extend Mink\Driver\DriverInterface for Laravel-specific needs (e.g., Laravel’s HttpClient). Example:

   class LaravelDriver implements DriverInterface {
       public function visit($uri) {
           $response = app('http')->get($uri);
           // Parse response into Mink's Page object
       }
   }
   

2. Behat Contexts: Create reusable contexts for Laravel-specific interactions:

   use Behat\Behat\Context\Context;
   use Behat\Mink\Mink;
   
   class LaravelContext implements Context {
       private $mink;
   
       public function __construct(Mink $mink) {
           $this->mink = $mink;
       }
   
       /**
        * @Given I am logged in as :user
        */
       public function iAmLoggedInAs($user) {
           $session = $this->mink->getSession();
           $session->visit('/login');
           // ... login logic
       }
   }
   

3. Hooks for Laravel: Use Behat hooks to set up Laravel’s app:

   use Behat\Behat\Event\SuiteEvent;
   use Behat\Behat\Hook\Scope\BeforeSuiteScope;
   
   $eventDispatcher->addListener(
       SuiteEvent::BEFORE_SUITE,
       function (SuiteEvent $event) {
           $kernel = require __DIR__.'/../bootstrap/app.php';
           $app = $kernel->getContainer();
           // Configure app for testing (e.g., set queue worker to "sync")
       }
   );