Mink Debug Extension Laravel Package

Technical Evaluation

Framing correction (must be stated up front). This is not a Laravel package. There is no service provider, no facade, no config/*.php, and no integration with Laravel's container, Artisan, or test runner. It is a Behat extension — a Composer library loaded via a block in behat.yml that hooks the Mink step lifecycle and writes artifacts when a step fails. A TPM who frames this as "a Laravel test improvement" will mis-set expectations with stakeholders; the accurate framing is "a post-failure artifact collector for teams already running Behat + Mink acceptance tests." If the team runs PHPUnit, Pest, or Laravel Dusk, the package delivers zero functional value regardless of how well it is installed.

Architecture fit. Fit is binary rather than graduated: near-perfect where a Behat/Mink suite already exists, zero everywhere else. Where it fits, it is architecturally clean. It operates at the Behat extension boundary — it does not modify application code, does not wrap or replace the Mink driver, and does not instrument anything in production paths. On each failed step it serialises Mink session state (current URL, page source, driver metadata) to a directory, and can additionally persist a screenshot when the underlying driver supports it. That containment is the main architectural virtue from a delivery-risk standpoint: the blast radius of adoption is confined to test infrastructure and CI configuration.

Integration feasibility. Genuinely low effort at the install layer: one composer require --dev, one YAML block, three options (directory required; screenshot defaults false; clean_start defaults true). No migrations, no schema, no runtime configuration, no coupling to application code. The real work is not installation — it is the surrounding CI plumbing: making the artifact directory writable by the CI user and uploading the artifacts on failure so engineers can actually open them. Treat the install as a half-day task and the CI wiring plus team communication as the actual scoped work.

Technical risk. Moderate-low overall, with several items that must be surfaced before commitment:

Key questions to resolve before commitment.

1. Do we run Behat + Mink today, across how many suites and steps? If zero, this is a non-decision — close it.
2. If we don't today, are we about to? Adopting Behat in order to use this extension is backwards.
3. Which Mink driver(s) are in use — will screenshot: true actually do anything?
4. Where do artifacts land, who can read them, and for how long? Is any of that content in scope for data-handling policy?
5. Has legal cleared a NOASSERTION dependency for our tier?
6. What is the current MTTR for a red Behat build? Without a baseline, any "faster debugging" claim is unfalsifiable.
7. Which version line are we on — v2.1.0+ requires PHP ≥7.4, and v2.0.0+ is the PHP 8 support line. Does that match our runtime?

Integration Approach

Stack fit. Valid only in this intersection: PHP project + Behat + Mink + a CI pipeline. Laravel is incidental — a Laravel app can host a Behat suite, but Laravel's own tooling (php artisan test, Dusk, Pest listeners) does not compose with this extension at all. Secondary fit: any PHP codebase with a Behat acceptance layer. Non-fit: PHPUnit/Pest-only suites, Dusk-only suites, JS-based E2E (Cypress, Playwright), or anything where the driver in use cannot produce screenshots and log-only output is not worth the wiring.

Migration path. Two distinct paths depending on starting point:

Greenfield (no Behat debugging today):

1. composer require --dev friends-of-behat/mink-debug-extension.
2. Add the FriendsOfBehat\MinkDebugExtension block to the relevant Behat profile with directory: %paths.base%/var/behat-logs.
3. Ship log-only first (screenshot: false) to validate the directory, permissions, and artifact shape with no driver dependency.
4. Add native CI artifact upload on job failure.
5. Only then enable screenshot: true on a suite whose driver supports it.

Upgrading from the Lakion era (v1.x):

1. Read UPGRADE.md before touching composer.
2. Replace every Lakion\Behat\MinkDebugExtension namespace reference in behat.yml and internal docs with FriendsOfBehat\MinkDebugExtension.
3. Remove CI steps invoking vendor/lakion/mink-debug-extension/travis/tools/* — those binaries no longer exist. Replace with native pipeline artifact upload.
4. Expect the log extension to change to .html; update any glob patterns, artifact paths, or dashboard links that match *.log.

Compatibility. Requires PHP ≥7.4 on the v2.1.0 line; v2.2.0 adds Behat 4 support. Verify the Behat major version in use before pinning — a Behat 3 project must not float onto a v2.2.0 requirement it cannot satisfy. Pin an explicit version rather than allowing a floating constraint, given the thin maintainer base.

Sequencing. Run this as a bounded pilot, not a rollout:

1. Week 1 — decision gate. Confirm an active Behat/Mink suite exists; confirm driver capability; open the license question with legal in parallel.
2. Week 2 — pilot on one suite. Log-only, one profile, one CI job. Capture the baseline red-build MTTR before enabling.
3. Weeks 3–4 — observability wiring. Native artifact upload on failure, retention policy set, access scope defined, sensitive-data review of a sample of captured HTML.
4. Week 5 — go/no-go. Re-measure MTTR and triage handoffs. Enable screenshots only if the driver supports them and the pilot data justifies it.
5. Post-pilot — standardise or stop. If it worked, document the namespace gotcha and the artifact path convention once, centrally, so the next team does not rediscover it.

Operational Impact

Maintenance. Low code-level maintenance but non-zero dependency risk. The package is a small, effectively single-maintainer utility with 0 listed dependents; there is no vendor, no SLA, and no commercial backstop. Assign an explicit internal owner (typically a QA lead or the platform/test-infra engineer) so it does not become orphaned config that nobody understands. Budget a periodic review: Behat major bumps, PHP runtime upgrades, and driver changes are all events that can silently break artifact capture.

Support. No vendor support path. Support is internal: whoever owns the Behat suite owns the extension. The single highest-value support artifact is a short internal runbook covering the namespace rename trap, the required directory setting, where artifacts land, and how to download them from CI. Without that, every new engineer will re-hit the same two failure modes.

Scaling. Scales well horizontally in the sense that cost per job is trivial — writing a few HTML files per failure is negligible against browser-driven acceptance test runtime. The scaling concern is storage and noise, not compute: clean_start: true clears logs per execution, but with parallel CI runners each job writes its own directory and artifact uploads accumulate per pipeline. Set retention (e.g. 14–30 days on failed builds only) at the pipeline level, not the package level. Also note artifacts should upload only on failure — uploading on every green build is pure cost with no diagnostic value.

Failure modes to plan for.

• Silent no-op on namespace mismatch. The extension block simply does not load; no error, no logs. Engineers conclude "the tool doesn't work." Mitigate by verifying at least one artifact appears during the pilot.
• Permission denied on the log directory. CI user cannot write to %paths.base%/.... Fails opaquely or produces empty output. Mitigate with an explicit writable path and a smoke assertion in the pipeline.
• Screenshots silently absent. Driver does not support capture. Looks like a bug in the extension; is actually a driver capability mismatch. Verify driver before promising the capability.
• Artifacts produced but never surfaced. The most common real-world failure: files land in the container and are discarded when the job ends. This is the single item most likely to make the whole pilot look worthless — do the artifact upload wiring before judging value.
• Sensitive data leakage. HTML page-source dumps landing in CI artifacts readable by a wide audience. Mitigate with retention limits, restricted artifact visibility, and a content spot-check during the pilot.
• Unclassified license blocking a later audit. Discovered late, after adoption has spread. Resolve before the pilot ends, not after.

Ramp-up. Very low for engineers: it is configuration, not code, and the mental model ("failed step writes a file") takes minutes to grasp. The genuine ramp-up cost sits with CI/DevOps (artifact upload, retention, permissions) and compliance (license, data handling). Estimate roughly one engineer-day of engineering effort plus legal turnaround for the pilot; the dominant calendar risk is the license review, not the technical work.

Value measurement. Track three things against the pre-pilot baseline: time-to-first-diagnosis on red acceptance builds, count of "cannot reproduce locally" handoffs, and proportion of failures resolved without a local rerun. If those do not move after four weeks on one suite, the honest conclusion is that the team's bottleneck is elsewhere, and the pilot should be closed rather than expanded.