Statamic Latte Laravel Package

Technical Evaluation

Package profile (inferred): A Laravel testing/assertion package that inspects rendered HTML responses, exposing Nette/Latte-style attribute and tag conventions (n:href, n:iftext) alongside fieldtype-aware escaping. Release 2.6.0 is a minor-version feature release in the assertion/rendering layer, not a framework or runtime dependency change.

Architecture fit

• The package sits entirely in the test/QA tier (require-dev), operating on HTTP responses and view output. It does not intercept routing, container bindings, or Eloquent, so it imposes no architectural constraints on application code.
• The 2.6.0 features are additive: a new attribute (n:href), a new tag/attribute pair (iftext/n:iftext), and refinement of escaping behavior for HTML-emitting fieldtypes. Additive surface area is the lowest-risk category of change, but "smart escaping" is a behavior change on an existing code path and deserves separate scrutiny from the two new selectors.
• The n:* naming signals deliberate affinity with Nette/Latte conventions rather than Blade-native idioms. That is a reasonable design choice for DOM-assertion ergonomics, but it means the package carries its own mental model that new contributors will not arrive with.

Integration feasibility

• Adoption is low-friction: composer dev dependency, a trait or base test case, and assertions added incrementally to existing feature tests. No schema, queue, or config migration implied.
• The new selectors reduce the need for hand-rolled XPath/CSS selectors and brittle assertSee string matching, which is the primary reason teams adopt this class of package.
• iftext/n:iftext is the highest-value addition: asserting on visible content rather than raw markup aligns tests with what a user actually sees and cuts false positives from hidden markup, JSON blobs, or commented-out blocks.

Technical risk

• Escaping change (moderate): "Smart escaping for fieldtypes with html output" alters existing rendered output or assertion expectations. Any test asserting on exact markup for rich-text/WYSIWYG fields could flip from pass to fail without an obvious cause. This is the one item in 2.6.0 that can break a green suite on upgrade.
• n:href classification (low–moderate): Distinguishing current / external / download links is heuristic. Query strings, trailing slashes, protocol-relative URLs, subdomain vs. apex hosts, download attributes, and target="_blank" all create edge cases where classification may not match intent. Expect a period of "is this a package bug or a test bug?" triage.
• iftext visibility semantics (moderate): "Visible" is only well-defined if the package resolves CSS hiding, hidden attributes, and inline styles. If detection is shallow (class-name matching), tests may pass on content that is hidden in a real browser — a false sense of coverage, which is worse than no assertion.
• Overall blast radius is small: test-tier only, no production runtime exposure. Worst case is a red CI pipeline, not an incident.

Key questions for the maintainer

1. Is the new escaping behavior opt-in, and is there a documented migration note or deprecated prior mode?
2. What exactly does iftext consider "visible" — inline styles, display:none, hidden, class-based CSS from a stylesheet, or markup presence only?
3. How does n:href classify current vs. external (host comparison? configured APP_URL? relative resolution?), and how are query strings and trailing slashes normalized?
4. Are these features covered by the package's own tests across supported Laravel versions?
5. Can the new attribute/tag be used selectively, or does enabling them change global parsing behavior?

Integration Approach

Stack fit

• Compatible with any Laravel application running PHPUnit or Pest. No conflict expected with Blade, Inertia, or Livewire, though Livewire/DOM-diff assertions may need care since rendering is partially client-side and iftext cannot see Alpine/JS-driven visibility.
• For teams already using assertSee/assertSeeText heavily, this is a natural consolidation rather than a competing tool.

Migration path

• Upgrade as a normal minor bump; pin the version in composer.json so an unexpected patch does not land mid-sprint.
• Treat the escaping change as the migration work item: run the full suite on a branch, catalogue failures, and classify each as (a) genuinely corrected expectation, (b) stale snapshot needing update, or (c) regression to report upstream.
• Do not mass-rewrite existing assertions to the new n:* syntax. Convert opportunistically where a test is already being touched.

Compatibility

• Confirm the package's supported Laravel/PHP matrix covers the team's versions before adopting the new selectors; a minor release may target a framework version the team has not upgraded to.
• Verify behavior in the CI PHP version specifically — DOM parsing and escaping edge cases are the kind of thing that varies by extension build.

Sequencing

1. Upgrade on a branch; run the suite; quantify escaping-related failures.
2. Resolve failures and merge; hold here for one iteration to confirm stability.
3. Pilot iftext/n:iftext in one or two view-heavy feature tests; validate visibility semantics against a deliberately hidden element.
4. Pilot n:href in navigation/link tests; validate classification against real internal, external, and download links.
5. Document both conventions in the team testing guide, then broaden adoption.

Operational Impact

Maintenance

• Low. A dev-only dependency with no runtime footprint; upgrades are occasional and isolated to test code.
• The real maintenance cost is assertion drift: teams that adopt n:* conventions create a package-specific dialect that new hires must learn. Budget a short section in the testing guide.
• The n:* attribute syntax is not standard HTML, so it only works through this package's parser. That is an acceptable but real coupling — swapping test tooling later means rewriting those assertions.

Support

• No production support burden; no on-call implications.
• Escalation path is the upstream issue tracker. Mitigation for a blocking bug is straightforward: revert the version bump, since nothing in production depends on it.
• The escaping change is the most likely source of "why did my test break" support tickets internally. Pre-empt with a note in the upgrade PR.

Scaling

• Assertions run per test; DOM parsing adds overhead but is negligible next to database and HTTP round-trips in typical feature suites.
• iftext may be slower than raw string matching on very large pages. Only a concern for large suites; parallelization absorbs it.

Failure modes

• Silent false negatives in iftext: content asserted as visible that a browser would hide. Worst failure mode here, because it inflates confidence in UI tests.
• Over-strict n:href matching: internal links misclassified as external (or vice versa) after a domain or environment change, producing confusing failures in CI that pass locally.
• Escaping regressions surfacing as unrelated test failures: markup assertions on rich-text fields fail with diffs that look cosmetic, obscuring whether output is genuinely wrong.
• Version drift: an unpinned minor upgrade landing in CI and turning the pipeline red without a code change.

Ramp-up

• New selectors are learnable in under an hour for anyone comfortable with PHPUnit assertions.
• Plan roughly a half-day of engineering time for the upgrade itself (mostly triaging escaping-related failures), plus a short documentation update. No training budget or dedicated owner required.
• Recommended owner: whoever owns the test suite / CI health, not the application feature teams.

Recommendation: Adopt 2.6.0, but sequence it as a test-tier upgrade with the escaping change explicitly validated before enabling the new selectors. Treat iftext visibility semantics as an open question to verify empirically rather than assume — and gate broad adoption of n:href on confirming its link-classification rules.