Mink Debug Extension Laravel Package

Getting Started

This is a Behat extension, not a Laravel package. It only pays off if your project already runs Behat + Mink acceptance tests. In a Laravel codebase, that means a separate behat.yml suite; it does nothing for PHPUnit, Pest, Laravel Dusk, or php artisan test.

Install it as a dev dependency:

composer require --dev friends-of-behat/mink-debug-extension

Minimal behat.yml configuration:

default:
    extensions:
        FriendsOfBehat\MinkDebugExtension:
            directory: '%paths.base%/var/behat-logs'
            screenshot: false
            clean_start: true

Then run your suite normally:

vendor/bin/behat

Your first use case: trigger one failing Mink step, open the generated .html file in var/behat-logs, and inspect the captured Mink state — current URL and page source. If your driver supports screenshots, switch screenshot: true after confirming driver support.

Look first at:

• behat.yml extension configuration
• The generated HTML log files
• Your CI artifact upload step, if failures happen remotely

Do not look for a Laravel service provider, facade, config/*.php, or Artisan command. There are none.

Implementation Patterns

Use Behat profiles for local vs CI behavior. Keep local runs cheap and CI runs diagnostic:

default:
    extensions:
        FriendsOfBehat\MinkDebugExtension:
            directory: '%paths.base%/var/behat-logs'
            screenshot: false
            clean_start: false

ci:
    extensions:
        FriendsOfBehat\MinkDebugExtension:
            directory: '%paths.base%/build/behat-logs'
            screenshot: true
            clean_start: true

Run CI with:

vendor/bin/behat --profile=ci

Upload artifacts natively from CI. Since v2.0.0, the old helper binaries like upload-textfiles and upload-screenshots are gone. Use your CI provider’s artifact mechanism. GitHub Actions example:

- name: Run Behat
  run: vendor/bin/behat --profile=ci

- name: Upload Behat failure artifacts
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: behat-failure-artifacts
    path: build/behat-logs
    if-no-files-found: ignore

Keep the log directory out of source control and out of the public web root. var/behat-logs or build/behat-logs are good defaults. Add them to .gitignore.

Use clean_start: false locally when comparing runs. The default clean_start: true wipes previous logs on every execution. That is usually right for CI, but locally you often want to compare a failed run against a previous one. Set it to false in your local profile.

Enable screenshots only where the driver supports them. Screenshot capture depends on the Mink driver. Since v2.0.0 more drivers are supported beyond Selenium2Driver, but Goutte-style drivers still produce logs only. Verify the actual driver before enabling screenshot: true.

Wrap Behat in a Composer script for Laravel teams. This keeps the workflow discoverable for developers used to composer test:

{
    "scripts": {
        "test:acceptance": "vendor/bin/behat --profile=ci"
    }
}

This is still Behat infrastructure, not Laravel test-runner integration.

Use %paths.base% for portable paths. Avoid absolute paths in behat.yml; %paths.base% resolves relative to the directory containing behat.yml, which works better across local machines, containers, and CI agents.

Prune or retain artifacts deliberately. clean_start: true limits accumulation in CI workspaces, but CI artifact retention is a separate setting. Set retention based on debugging needs and data sensitivity.

Gotchas and Tips

Package identity is split and confusing. The repository is associated with Lakion/MinkDebugExtension, but the installable package is friends-of-behat/mink-debug-extension, and the namespace changed from Lakion\Behat\MinkDebugExtension to FriendsOfBehat\MinkDebugExtension in v2.0.0. Old tutorials and internal wiki pages using the Lakion\... namespace will silently fail to load the extension. Budget time for this.

It is not a Laravel package. No service provider, facade, config publication, container binding, or Artisan command. Do not add it to config/app.php. It is a test-infrastructure-only Behat extension.

directory is required to enable the extension. If it is omitted or misconfigured, you get no logs. Make sure the directory is writable by the user or container running Behat in CI.

clean_start defaults to true. This deletes existing logs on each Behat execution. Good for CI, potentially annoying locally. Set clean_start: false locally when you want to inspect prior failures.

Screenshots are driver-dependent. screenshot: true does not magically work with every Mink driver. Confirm your driver supports screenshots before advertising “screenshots on failure” to the team. Otherwise you get logs only.

Log file extension changed in v2. Logs are now .html, not .log. Any CI script, dashboard, or documentation expecting .log needs updating. Old helper binaries under vendor/lakion/mink-debug-extension/travis/tools/* were removed; use native CI artifact upload instead.

Logs can contain sensitive data. HTML dumps of page source may include session tokens, emails, customer data, or internal URLs. Treat artifacts as sensitive: restrict who can download them, set retention, and avoid public artifact storage.

License is NOASSERTION. GitHub cannot classify the license. For internal dev-only test tooling this is often tolerable, but get legal/compliance clearance if your organization requires it, especially for regulated environments.

Adoption is thin. 204 stars but 0 listed dependents suggests a small, niche utility. Treat it as a bounded, low-cost improvement — not a strategic platform dependency. Pin the version and be prepared to own upgrades.

Check PHP and Behat compatibility. v2.1.0 drops PHP versions below 7.4; v2.0.0 added PHP 8.0 support; v2.2.0 added Behat 4 support. Match the package version to your PHP and Behat versions.

Debugging when no logs appear:

• Confirm the extension key is FriendsOfBehat\MinkDebugExtension, not the old Lakion\... namespace.
• Confirm directory is set and writable.
• Confirm the failing step actually uses a Mink session.
• Run Behat with the intended profile and more verbosity, e.g. vendor/bin/behat --profile=ci -vvv.
• Note that log content can be empty by design since v2.1.0, so an empty file is not necessarily a configuration failure.

It is post-failure artifact collection, not real-time debugging. It helps you triage a red build without manually reproducing the failure. It does not replace step debugging, driver logs, or application-level logging.