Driver Testsuite Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your Laravel project via Composer:

   composer require --dev minkphp/driver-testsuite
   

   Ensure mink/mink and a Mink driver (e.g., mink/selenium-driver or mink/goutte-driver) are also installed.

2. Basic Configuration Extend Laravel’s phpunit.xml to include the test suite:

   <phpunit>
       <extensions>
           <extension class="Mink\Driver\TestSuite\Extension"/>
       </extensions>
   </phpunit>
   

   Configure Mink in phpunit.xml or config/testing.php:

   <env name="MINK_DRIVER" value="selenium2"/>
   

3. First Test Case Use Laravel’s createApplication() and Mink’s Mink facade:

   use Laravel\Dusk\Browser;
   use Mink\Mink;
   use Mink\Driver\TestSuite\Extension;
   
   public function testBasicNavigation()
   {
       $mink = new Mink(new Extension());
       $session = $mink->createSession('selenium2');
       $session->start();
   
       $session->visit('/');
       $this->assertEquals('Home', $session->getPage()->getTitle());
   }
   

Implementation Patterns

Workflow Integration

1. Laravel + Mink/Dusk Hybrid

   • Use Laravel\Dusk\Browser for UI tests and Mink for cross-driver validation.
   • Example: Reuse Dusk’s Browser in Mink tests:

     $browser = Browser::task(function () {
         $this->visit('/dashboard');
     });
     $session = $mink->createSession('goutte');
     $session->setPage($browser->driver()->getSession()->getPage());
     

2. Driver-Specific Testing

   • Selenium: Test JavaScript-heavy interactions.

     $session->clickLink('Login');
     $this->assertTrue($session->getPage()->hasContent('Welcome'));
     

   • Goutte: Test HTML/CSS-only paths.

     $session->visit('/api/docs');
     $this->assertCount(3, $session->getPage()->findAll('h2'));
     

3. Test Data Isolation

   • Use Laravel’s DatabaseTransactions trait to reset state:

     use Illuminate\Foundation\Testing\DatabaseTransactions;
     
     class ExampleTest extends TestCase
     {
         use DatabaseTransactions;
     }
     

4. Parallel Testing

   • Configure PHPUnit’s --group flag to run driver-specific tests in parallel:

     phpunit --group selenium --parallel
     

Gotchas and Tips

Common Pitfalls

1. Driver Mismatches

   • Issue: Tests pass in Goutte but fail in Selenium due to JS dependencies.
   • Fix: Use @group selenium and @group goutte annotations to isolate tests.

2. Session Leaks

   • Issue: Unclosed sessions cause memory leaks.
   • Fix: Wrap tests in try-finally or use Laravel’s tearDown():

     protected function tearDown(): void
     {
         $this->mink->closeAllSessions();
         parent::tearDown();
     }
     

3. Configuration Overrides

   • Issue: Local phpunit.xml overrides global Mink settings.
   • Fix: Use environment variables for dynamic driver selection:

     <env name="MINK_DRIVER" value="%env.MINK_DRIVER%"/>
     

Debugging Tips

• Enable Mink Debugging:

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

• Log Driver Output: Redirect Selenium logs to a file:

  <env name="SELENIUM_BROWSER" value="firefox"/>
  <env name="SELENIUM_LOG" value="/tmp/selenium.log"/>
  

Extension Points

1. Custom Assertions Extend Mink’s Assert class for domain-specific checks:

   use Mink\Element\NodeElement;
   
   class CustomAssertions extends \PHPUnit\Framework\Assert
   {
       public static function assertButtonEnabled(NodeElement $element)
       {
           self::assertTrue($element->isVisible(), 'Button is not visible');
           self::assertFalse($element->hasAttribute('disabled'));
       }
   }
   

2. Hook into TestSuite Override Mink\Driver\TestSuite\Extension to add pre/post-test logic:

   class CustomExtension extends \Mink\Driver\TestSuite\Extension
   {
       public function onPreTest()
       {
           // Setup (e.g., clear cookies)
       }
   }
   

3. Laravel Service Provider Bind Mink to Laravel’s container for dependency injection:

   $this->app->singleton(Mink::class, function ($app) {
       return new Mink(new CustomExtension());
   });