Getting Started

Minimal Setup

Install the package:

composer require oleg-andreyev/mink-phpwebdriver

Configure Mink in your Laravel project (typically in phpunit.xml or a test config file):

<php>
    <server name="MINK_DRIVER_ARGS" value="{'browser':'chrome','host':'localhost','port':9515}"/>
</php>

Start WebDriver (e.g., Chrome):
```
./vendor/bin/phpwebdriver --browser=chrome --port=9515
```
(Use the provided start_webdriver.sh script from the repo for convenience.)

Write a basic test (using Laravel's BrowserKitTestingTrait or Mink integration):

use Facebook\WebDriver\WebDriverBy;
use Facebook\WebDriver\WebDriverExpectedCondition;

$session = $this->getSession();
$session->get('https://example.com');
$this->assertEquals('Example Domain', $session->findElement(WebDriverBy::id('example'))->getText());

First Use Case: Automated UI Testing

Use MinkPhpWebDriver to replace Selenium2Driver in Laravel's test suite.
Ideal for feature tests where you need to interact with a real browser (e.g., form submissions, JavaScript-heavy workflows).

Example:

use MinkPhpWebDriver\Driver;

$driver = new Driver([
    'browser' => 'chrome',
    'host' => 'localhost',
    'port' => 9515,
]);
$mink = new Mink($driver);
$session = $mink->getSession();

Implementation Patterns

Core Workflows

Driver Initialization:

Configure the driver in Laravel's config/testing.php or via environment variables:

'mink' => [
    'driver' => MinkPhpWebDriver\Driver::class,
    'driver_args' => [
        'browser' => env('BROWSER', 'chrome'),
        'host' => env('WEBDRIVER_HOST', 'localhost'),
        'port' => env('WEBDRIVER_PORT', 9515),
        'headless' => env('HEADLESS', false),
    ],
],

Use Laravel's Mink facade or inject the driver directly into tests.

Session Management:
- Start/stop sessions explicitly for long-running tests:
```
$session = $this->getSession();
$session->start();
// Test logic...
$session->quit();
```
- Leverage Mink's built-in session handling for shorter tests.
Headless Mode:
- Enable headless Chrome/Firefox for CI:
```
$driver = new Driver([
    'browser' => 'chrome',
    'headless' => true,
]);
```
- Useful for GitHub Actions or Dockerized test environments.
Screenshot Capture:
- Attach a screenshot listener for debugging:
```
$session->addListener(new \MinkPhpWebDriver\Listener\ScreenshotListener());
```
- Screenshots auto-save to storage/logs/mink-screenshots/ (configurable).

Integration Tips

Laravel Testing: Extend Laravel\BrowserKitTesting\Concerns\ProvidesBrowserKitToApplication to include MinkPhpWebDriver:

use MinkPhpWebDriver\Driver;

protected function createApplication()
{
    $app = parent::createApplication();
    $app->make('mink')->setDriver(new Driver($this->driverArgs));
    return $app;
}

Behat Integration: Use the MinkPhpWebdriverExtension for BDD:

# behat.yml
extensions:
    MinkPhpWebdriverExtension:
        browser: chrome
        host: localhost
        port: 9515

Parallel Testing: Spin up multiple WebDriver instances (e.g., Chrome + Firefox) for parallel test suites:

# Terminal 1
./vendor/bin/phpwebdriver --browser=chrome --port=9515
# Terminal 2
./vendor/bin/phpwebdriver --browser=firefox --port=9516

Gotchas and Tips

Pitfalls

Driver Version Mismatches:
- Ensure facebook/webdriver and browser drivers (e.g., ChromeDriver) are compatible.
- Use the start_driver.sh script to auto-download matching drivers:
```
./vendor/bin/start_driver.sh chrome latest
```
Headless Mode Quirks:
- Firefox headless may require additional args (e.g., --headless=new for v100+).
- Chrome headless needs --disable-gpu in some Docker environments:
```
$driver->setCapability('goog:chromeOptions', [
    'args' => ['--headless', '--disable-gpu'],
]);
```

Session Leaks:

Always call $session->quit() to avoid zombie sessions:

public function tearDown(): void
{
    $this->getSession()->quit();
    parent::tearDown();
}

Time Input Handling:
- Workarounds for <input type="time"> may fail in older browsers. Use explicit JS:
```
$session->executeScript("document.querySelector('input[type=time]').value = '12:00'");
```

Firefox Prompts:

Handle alerts/prompts with:

$alert = $session->wait(5, function () use ($session) {
    return $session->getAlert();
});
$alert->accept();

Debugging Tips

Logs: Enable verbose logging via MINK_DRIVER_ARGS:

'driver_args' => [
    'browser' => 'chrome',
    'logging' => ['browser' => 'ALL'],
],

Check logs in storage/logs/mink-*.log.

Network Issues: Use host: 'localhost' for local testing, but switch to host: 'host.docker.internal' in Docker:
```
'driver_args' => ['host' => 'host.docker.internal'],
```

Element Interaction: Use executeScript for complex interactions (e.g., drag-and-drop):

$session->executeScript("
    const source = document.querySelector('#draggable');
    const target = document.querySelector('#droppable');
    source.dispatchEvent(new DragEvent('dragstart'));
    target.dispatchEvent(new DragEvent('drop'));
");

Extension Points

Custom Capabilities: Override browser capabilities for advanced use cases:

$driver->setCapability('marionette', true); // Firefox
$driver->setCapability('excludeSwitches', ['enable-automation']); // Chrome

Event Listeners: Extend \MinkPhpWebDriver\Listener\BaseListener to add custom hooks (e.g., for analytics):

class CustomListener extends BaseListener
{
    public function onSessionStart(Session $session)
    {
        $session->executeScript("console.log('Test started')");
    }
}

Driver Pooling: Reuse sessions across tests by implementing a custom SessionManager:

$pool = new \MinkPhpWebDriver\SessionPool($driver);
$session = $pool->get('test-123'); // Reuses if exists

CI Optimization: Cache WebDriver binaries in CI (e.g., GitHub Actions):

- name: Cache WebDriver
  uses: actions/cache@v3
  with:
    path: ~/.cache/webdriver
    key: ${{ runner.os }}-webdriver-${{ hashFiles('**/composer.lock') }}

Mink Phpwebdriver Laravel Package