Mink Extension Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package**:
   ```bash
   composer require --dev friends-of-behat/mink-extension

2. Configure behat.yml with a basic session (e.g., goutte for headless testing):

   default:
     extensions:
       FriendsOfBehat\MinkExtension:
         base_url: 'http://localhost:8000'
         sessions:
           default:
             goutte: ~
   

3. Extend MinkContext in your feature context:

   use Behat\MinkExtension\Context\MinkContext;
   
   class FeatureContext extends MinkContext {}
   

4. Run tests:

   vendor/bin/behat
   

First Use Case: Basic Web Interaction

Use pre-defined steps like:

Given I am on "/login"
When I fill in "email" with "user@example.com"
And I press "Login"
Then I should see "Welcome"

Implementation Patterns

1. Session Management

• Multi-session workflows: Tag scenarios to switch sessions (e.g., @mink:selenium for JS-heavy tests):

  @mink:selenium
  Scenario: JavaScript-heavy feature
  

• Dynamic session selection: Configure default_session and javascript_session in behat.yml:

  suites:
    default:
      mink_session: default
      mink_javascript_session: selenium
  

2. Context Inheritance

• Reuse MinkContext: Extend once per feature suite (avoid redundant step definitions):

  class AdminContext extends MinkContext {
      /**
       * @Then /^I see the admin dashboard$/
       */
      public function iSeeAdminDashboard() {
          $this->assertSession()->pageTextContains('Admin Panel');
      }
  }
  

• Compose contexts: Include MinkContext directly in behat.yml:

  contexts:
    - FeatureContext
    - Behat\MinkExtension\Context\MinkContext
  

3. Driver-Specific Workflows

• Headless (Goutte): Fast API/HTML tests:

  sessions:
    api:
      goutte: ~
  

• Browser Automation (Selenium2): JS-heavy features:

  sessions:
    selenium:
      selenium2:
        browser: chrome
  

• Remote Testing (SauceLabs/BrowserStack):

  sessions:
    sauce:
      sauce_labs:
        username: ${SAUCE_USERNAME}
        access_key: ${SAUCE_ACCESS_KEY}
  

4. Custom Steps

• Extend MinkContext for reusable logic:

  class CustomContext extends MinkContext {
      /**
       * @Then /^I wait for element "([^"]*)" to appear$/
       */
      public function waitForElement($selector) {
          $this->getSession()->wait(5000, "$('$selector').is(':visible')");
      }
  }
  

• Use MinkAwareContext for lightweight integration:

  use Behat\MinkExtension\Context\MinkAwareContext;
  
  class LightweightContext implements MinkAwareContext {
      protected $mink;
  
      public function setMink(Mink $mink) {
          $this->mink = $mink;
      }
  
      /**
       * @Then I do something with Mink
       */
      public function customStep() {
          $this->mink->getSession()->visit('/');
      }
  }
  

5. File Uploads

• Configure files_path in behat.yml:

  files_path: '%paths.base%/tests/_data/uploads'
  

• Use steps like:

  When I attach the file "profile.jpg" to "avatar"
  

Gotchas and Tips

Pitfalls

1. Redundant Step Definitions:

   • Extending MinkContext only once per feature suite (throws RedundantStepException if duplicated).
   • Fix: Use composition (include MinkContext in behat.yml) or extend RawMinkContext.

2. Driver Deprecations:

   • goutte, selenium, sahi, and zombie drivers are deprecated. Migrate to selenium2 or goutte (with Guzzle 4+).
   • Fix: Update behat.yml and install behat/mink-selenium2-driver.

3. HTTPS Self-Signed Certificates:

   • Goutte fails on self-signed certs by default.
   • Fix: Configure Guzzle parameters:

     sessions:
       default:
         goutte:
           guzzle_parameters:
             verify: false
     

4. Session Isolation:

   • Scenarios share sessions by default. Use @mink:session_name tags to isolate:

     @mink:api
     Scenario: API-only test
     

Debugging Tips

1. Visual Debugging:

   • Enable show_auto: true in behat.yml to auto-open failed pages:

     show_cmd: 'open %s'  # macOS
     # or
     show_cmd: 'start %s' # Windows
     

2. Session Inspection:

   • Dump session state in contexts:

     $this->getSession()->dump();
     

3. Slow Tests:

   • Add explicit waits:

     $this->getSession()->wait(2000, "$('#loader').is(':hidden')");
     

Extension Points

1. Custom Drivers:

   • Implement Behat\Mink\Driver\DriverInterface and register via behat.yml:

     sessions:
       custom:
         custom_driver: ~
     

2. Hooks:

   • Override beforeScenario/afterScenario in your context for setup/teardown:

     protected function beforeScenario(Scenario $scenario) {
         $this->getSession()->start();
     }
     

3. Configuration Overrides:

   • Use environment variables for dynamic configs:

     sessions:
       selenium:
         selenium2:
           browser: ${BROWSER:-chrome}
     

4. Laravel-Specific:

   • Artisan Integration: Run Behat via Laravel’s Artisan:

     php artisan behat
     

   • Environment Awareness: Use Laravel’s .env for base_url:

     base_url: '%env(APP_URL)%'
     

   • Service Providers: Bind Mink sessions to Laravel’s container (advanced):

     $this->app->bind('mink', function () {
         return Mink::create();
     });
     

Performance Quirks

• Goutte vs. Selenium2:
  • Goutte is ~10x faster but lacks JS support. Use for API/HTML tests.
  • Selenium2 is slower but required for SPAs (React/Vue).
• Parallel Testing:
  • Use @mink:session_name tags to avoid session conflicts in parallel runs.

Laravel-Specific Workarounds

1. Auth State:

   • Reset sessions between scenarios:

     $this->getSession()->reset();
     

   • Or use Laravel’s actingAs() in hooks:

     $this->getSession()->visit('/login');
     $this->getSession()->getDriver()->getClient()->request('POST', '/login', [
         'email' => 'user@example.com',
         'password' => 'password',
     ]);
     

2. CSRF Tokens:

   • Goutte may fail on CSRF-protected forms. Disable CSRF in tests or:

     $this->getSession()->getDriver()->getClient()->getCookieJar()->clear();
     

3. Queue Workers:

   • Disable queues in phpunit.xml or behat.yml:

     extensions:
       FriendsOfBehat\MinkExtension:
         goutte:
           http_client_parameters:
             headers:
               X-Queue-Worker: 'false'
     

---