Lib Innerbrowser Laravel Package

## Getting Started
For Laravel developers using Codeception, `lib-innerbrowser` is the backbone of DOM parsing and HTTP request simulation in `PhpBrowser` and `Symfony` modules. Start by ensuring it’s installed via Codeception’s dependencies (no direct Composer install needed unless extending modules).

**First use case**: Write a test to validate a form submission without a real browser:
```php
// tests/acceptance/LoginCest.php
public function testLoginFormSubmission(AcceptanceTester $I)
{
    $I->amOnPage('/login');
    $I->fillField('#email', 'user@example.com');
    $I->fillField('#password', 'secret');
    $I->click('#submit-btn');

    // InnerBrowser powers these assertions via Symfony's DomCrawler
    $I->see('Welcome, User');
    $I->seeInCurrentUrl('/dashboard');
}

Where to look first:

• Codeception’s PhpBrowser module docs (uses InnerBrowser under the hood).
• Laravel-specific examples in tests/_support/Helper/Acceptance.php for custom assertions.
• Debug DOM state with $I->debugSection('response', $I->grabPageSource()).

Implementation Patterns

1. DOM Interaction Workflows

Use InnerBrowser’s crawler methods for element inspection:

// Check for elements, links, or text
$I->seeElement('#user-profile');
$I->dontSee('Error message');

// Extract data
$title = $I->grabTextFrom('h1');
$links = $I->grabMultiple('//a[@class="nav-link"]');

// Click/Submit forms
$I->click('Submit');
$I->submitForm('#login-form', ['email' => 'test@example.com']);

2. HTTP Response Handling

Leverage InnerBrowser’s request/response utilities:

// Assert headers or status codes
$I->seeResponseCodeIs(200);
$I->seeHttpHeader('Content-Type', 'application/json');

// Debug raw responses
$headers = $I->grabHttpHeader('X-CSRF-TOKEN');
$body = $I->grabPageSource();

3. Laravel-Specific Patterns

• Middleware/Route Testing: Use PhpBrowser to simulate authenticated requests:

  $I->amGoingTo('/admin');
  $I->seeResponseContains('Admin Dashboard');
  

• Session/CSRF Handling: InnerBrowser automatically manages cookies/sessions via Symfony’s Client (backed by InnerBrowser).

4. Custom Helpers

Extend functionality in _support/Helper/Acceptance.php:

public function seeLaravelFlashMessage($message)
{
    $this->see($message, 'div.alert-success');
}

Gotchas and Tips

Pitfalls

1. No JavaScript Execution:

   • InnerBrowser parses static HTML only. For JS-heavy apps, use WebDriver or Playwright.
   • Fix: Avoid assertions like $I->see('Dynamic content') if it relies on JS.

2. DOM State Caching:

   • Each $I->amOnPage() resets the DOM. Avoid chaining requests without reloads.
   • Fix: Use $I->refreshPage() if needed.

3. Deprecated Methods:

   • deleteHeader() → Use unsetHeader() (since v4.0.4).
   • Fix: Update tests to use unsetHttpHeader().

4. Symfony/DOM-Crawler Quirks:

   • Numeric keys in forms may break (fixed in v4.0.1). Ensure form fields use name="field[0]" syntax if dynamic.
   • Fix: Use fillField('#dynamic-field', 'value') instead of array keys.

Debugging Tips

• DOM Inspection:

  $I->debugSection('dom', $I->getDom()->html());
  

• HTTP Dump:

  $I->debugSection('headers', $I->grabAllHttpHeaders());
  

• Enable Codeception Debug:

  # tests/acceptance.suite.yml
  modules:
    enabled:
      - PhpBrowser:
          debug: true
  

Extension Points

1. Custom DOM Manipulation: Override InnerBrowser in a module:

   // tests/_support/InnerBrowser.php
   class CustomInnerBrowser extends \Codeception\Module\InnerBrowser
   {
       public function customAssertion()
       {
           // Extend with Laravel-specific logic
       }
   }
   

   Register in suite.yml:

   modules:
     InnerBrowser:
       class: \tests\_support\InnerBrowser
   

2. Mocking HTTP Responses: Use Symfony’s Client mocking:

   $client = $this->getModule('PhpBrowser')->getClient();
   $client->getKernel()->getContainer()->set('router', $this->createMock(RouterInterface::class));
   

3. Performance:

   • Disable DOM caching for large apps (not recommended):

     $this->getModule('PhpBrowser')->getClient()->getContainer()->set('debug', false);
     

   • Tip: Cache test data in fixtures to avoid repeated DOM parsing.

Laravel-Specific Quirks

• CSRF Tokens: InnerBrowser handles them automatically, but custom middleware may interfere. Fix: Ensure VerifyCsrfToken middleware is disabled in test routes.
• Session Drivers: Use array driver in .env.testing for consistency:

  SESSION_DRIVER=array
  

• Queue Workers: Disable in tests to avoid blocking:

  // tests/_bootstrap.php
  putenv('QUEUE_CONNECTION=sync');
  

---
**Key Takeaway**: Treat `lib-innerbrowser` as a "black box" for DOM/HTTP interactions in Codeception. Focus on its integration with `PhpBrowser`/`Symfony` modules, and extend only when needed for Laravel-specific edge cases.