Mink Debug Extension Laravel Package

Product Decisions This Supports

• Roadmap: test reliability and CI observability. This package sits squarely in the "engineering productivity" bucket rather than the customer-facing roadmap. If the team already runs Behat + Mink acceptance suites, it converts an opaque red build into an actionable artifact (failed-step logs, current URL, page source, and optionally a screenshot). That supports roadmap commitments around shorter feedback loops and fewer flaky-test escalations.
• Build vs. buy (buy = adopt). The alternative is custom CI scripting that dumps Mink state on failure. This extension is one composer require plus a three-key YAML block (directory, screenshot, clean_start), so the build comparison is trivially favourable if the Behat/Mink prerequisite is already met. If it isn't, the "build" option isn't custom code either — it's changing test frameworks, which is a much larger decision.
• Feature prioritization and investment sizing. The value case is MTTR on failed acceptance builds and reduction of "cannot reproduce locally" handoffs. That is measurable, but only against a baseline the PM should insist on capturing before adoption: current time-to-triage for a red Behat build, and the share of failures that required a local rerun.
• Use cases worth naming explicitly. (1) Laravel/PHP projects that maintain a Behat acceptance layer alongside PHPUnit/Pest. (2) CI pipelines (GitHub Actions, GitLab, Jenkins, Travis) where failure artifacts should be attached rather than requested. (3) QA triage of intermittent, environment-specific UI failures. (4) Onboarding — new engineers get failure context without needing tribal knowledge of the suite.
• Explicit non-use cases (the most important decision this supports). This is not a Laravel package: no service provider, no facade, no config/*.php, no container registration, no integration with php artisan test. Projects on Laravel Dusk, Pest, PHPUnit, Cypress, or Playwright get zero value. A PM should treat "we don't run Behat" as a closed decision, not a backlog item.
• Risk and dependency posture decision. Frame adoption as a bounded, internal, dev-only utility — not a platform dependency. The evidence supports that framing: 204 stars (largely legacy from the original Lakion era), 0 listed dependents, a NOASSERTION license requiring legal sign-off, and a single-maintainer-shaped project now stewarded by FriendsOfBehat. It is replaceable in an afternoon; treat it that way in architecture reviews so it never becomes load-bearing.
• Versioning/upgrade decision that has real PM cost. v2.0.0 was a breaking release: namespace moved from Lakion\Behat\MinkDebugExtension to FriendsOfBehat\MinkDebugExtension, log extension changed .log → .html, and the upload-textfiles / upload-screenshots / wait-for-port helper binaries were removed. Any existing CI script calling vendor/lakion/.../travis/tools/* breaks. Plan for native CI artifact upload instead. v2.2.0 adds Behat 4 support; v2.1.0 requires PHP ≥7.4 and v2.0.0+ targets PHP 8.0 — confirm the runtime line before committing.

When to Consider This Package

Consider adoption when all of these are true:

• You run Behat with Mink for acceptance/UI tests today, in one or more suites.
• CI failures currently produce little more than a stack trace, and engineers routinely rerun locally to understand what the browser saw.
• You want a config-only change with no application-code impact and no production blast radius.
• Your CI can write to a log directory and upload artifacts on failure.
• Your Mink driver supports screenshots if you intend to enable screenshot: true — otherwise scope the promise down to logs only.

Run a time-boxed pilot when:

• The NOASSERTION license hasn't been cleared. Get the actual LICENSE file reviewed in writing before broader rollout, especially if the repo is audited or shipped to regulated customers.
• The team is unfamiliar with the extension. Pilot on one high-friction suite, enable logging first, add screenshots second, wire artifact upload third, then measure triage time against the pre-adoption baseline.
• You're unsure which Mink driver(s) are in use. Verify before promising screenshots to stakeholders.

Look elsewhere when:

• You don't use Behat/Mink. This is a hard stop — the extension is architecturally inert without it.
• You're standardizing on Laravel Dusk, Pest, PHPUnit, Cypress, Playwright, or raw Selenium. Solve failure artifacts with native framework/CI tooling instead.
• You need interactive or real-time debugging rather than post-failure snapshots.
• You require vendor support, an SLA, or a maintained security-response commitment.
• Licensing policy blocks unclassified dependencies and legal won't clear it.
• The 0-dependent, low-adoption profile is unacceptable without an internal owner named up front.

Caveats to carry into any decision:

• Log/HTML dumps of page source can contain session tokens, emails, and customer data. clean_start: true limits accumulation, not sensitivity. Decide who can read artifacts, where they're stored, and the retention window before enabling this in any environment handling real user data.
• Screenshot capture is driver-conditional; Goutte-class drivers produce logs only. Don't let "screenshots on failure" become the accepted narrative until the driver is confirmed.
• Log directories must be writable by the CI user; missing-directory and permission failures are the most common adoption snag.
• Adopting Behat in order to use this extension is backwards. The framework decision must stand on its own.

How to Pitch It (Stakeholders)

To executives (30 seconds): "This is a small, low-cost improvement to our test infrastructure — but only for teams already running Behat acceptance tests. When a build goes red, it automatically captures the page state and, where the driver allows, a screenshot, so engineers spend minutes instead of hours working out what broke. It is not a customer-facing feature; the return is engineering throughput and release confidence. Two things to know: it doesn't apply to Laravel Dusk/Pest/PHPUnit suites, and its license is unclassified, so I'd recommend a time-boxed pilot on one suite with legal review in parallel before we call it standard."

To engineering and DevOps: "MinkDebugExtension is a Behat extension — not a Laravel package. One composer require --dev, one behat.yml block (directory required; screenshot: false and clean_start: true by default), and it hooks the Mink step lifecycle to write failure artifacts. It touches no application code and no production path; blast radius is test infrastructure only. Three things to check before rollout: (1) confirm which Mink driver we run and whether screenshot: true does anything; (2) replace any legacy vendor/lakion/.../travis/tools/* invocations with native artifact upload (actions/upload-artifact, GitLab artifacts:) — those binaries were removed in v2.0.0; (3) note the namespace changed from Lakion\Behat\... to FriendsOfBehat\..., so old wiki pages and StackOverflow snippets will silently fail to load. Also: the log dir must be writable by the CI user, and we need a retention policy — HTML page dumps can contain tokens and customer data."

To QA and testing teams: "This automates the first step of failure triage. When a scenario fails, you get the failed-step context, the current URL, page source, and — if the driver supports it — a screenshot, without rerunning anything locally. It's most valuable on flaky or environment-specific acceptance tests. We'll pilot it on our highest-friction suite first: week one logs only, week two add screenshots, and we'll compare triage time against how long a red build takes us today. If it doesn't move that number, we drop it — the cost of removing it is one dependency and one YAML block."