Phpunit Dom Assertions Laravel Package

Product Decisions This Supports

• Unblocking a platform upgrade (the primary driver). PHPUnit deprecated and then removed its assertSelect* DOM assertions. Any Laravel/PHP app with a legacy suite that relies on them is pinned to an older PHPUnit, which in turn caps the Laravel/framework version, the PHP version, and eventually security patch cadence. This package is the cheapest known way to decouple "we have DOM assertions" from "we cannot upgrade PHPUnit." That's a roadmap unblocker, not a nice-to-have.
• Test-infrastructure modernization backlog. Gives you a concrete, low-effort epic ("PHPUnit major upgrade") instead of an open-ended "clean up the test suite" item that never gets prioritized. Scope is measurable: grep -r "assertSelect" gives you the size of the work in minutes.
• Build vs. buy vs. rewrite. Three options exist for the same problem: (a) adopt this package, (b) write ~50–150 lines of in-house assertion helpers wrapping Symfony\Component\DomCrawler, or (c) rewrite each call site to assertSee/assertSeeText or DomCrawler. Option (a) wins on time-to-value; option (b) wins on control and license certainty; option (c) wins on long-term hygiene but has the highest and lumpiest cost. This package lets you buy time to do (c) incrementally — that sequencing decision is the actual product call.
• Where DOM assertions actually live. In Laravel codebases they cluster in: Blade/component rendering tests, transactional email template tests, XML sitemap and RSS/Atom feed tests, and admin-table/HTML structure assertions. Those are real product surfaces, so "just delete the tests" is usually not acceptable to the owning team. That's the argument for a bridge rather than a purge.
• Blast-radius containment. This is a require-dev dependency. It ships nothing to production, cannot affect runtime behavior, and cannot break customers. That materially lowers the bar for approval compared to a runtime library and is worth stating explicitly in any decision record.
• Exit-plan discipline. Adopting it as a temporary bridge with a named removal ticket is a different decision than adopting it as a permanent dependency. Make that call up front; the answer changes the review you do.

When to Consider This Package

Adopt (as a pinned, temporary bridge) when:

• You have a non-trivial number of DOM assertion call sites — roughly 20+ is where rewriting costs more than integrating — or even a handful that sit in a critical, frequently-touched suite.
• A PHPUnit major upgrade is currently blocked or repeatedly deferred because of them, and that block is cascading into framework/PHP version lag.
• The team is comfortable with a dev-only, single-purpose dependency and can pin an exact version in composer.json.
• You accept that this is a work-in-progress package: 29 stars, one apparent maintainer surface, NOASSERTION license metadata, and an unresolved repository field. Treat the API as unstable until proven otherwise in your own CI.

Look elsewhere when:

• You have fewer than ~10 call sites. Rewriting to assertSee / assertSeeText / Symfony DomCrawler is a half-day and removes the dependency question entirely. Do that instead.
• License is a hard gate. NOASSERTION means the license could not be automatically determined from the package metadata. In many organizations that alone fails procurement. Before anything else, confirm the actual license from the repository/composer.json; if it's not a recognized permissive license (e.g. BSD-3-Clause, MIT), expect legal review and a possible no.
• You need vendor support, an SLA, or a stable public API contract. This is community/WIP tooling.
• Your real need is full browser behavior — JS execution, navigation, screenshots. That's Laravel Dusk, Pest's browser plugin, or Playwright, not this.
• You can tolerate the rewrite and would rather not add a dependency you'll have to remove later. Defensible; just cost it honestly.

Pre-adoption checklist (do these in order, cheap to expensive):

1. grep -r "assertSelect" tests/ | wc -l — size the problem. If it's small, stop here.
2. Resolve the license and the repository URL manually. No repository + no license = do not merge until resolved.
3. Prove drop-in-ness on a branch: bump PHPUnit, install the package, run the suite, count failures. Success looks like near-zero test-code changes.
4. Pin the exact version; add a Dependabot/Renovate exclusion or a note so a surprise minor bump doesn't silently change assertion semantics.
5. File a removal ticket at adoption time with an owner and a target quarter. Track it in the same epic as the framework upgrade.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our test suite uses PHPUnit features that the project has deprecated and removed, which is currently holding us back from upgrading the framework and the PHP runtime. That upgrade is a prerequisite for staying on supported versions. This is a small, free, development-only package that restores those assertions so the upgrade can proceed now instead of after a multi-sprint test rewrite. It ships nothing to customers, carries no runtime risk, and is explicitly a bridge — the long-term plan is to migrate tests off it incrementally. The main caveats are that it is early-stage community software and its license needs a five-minute legal confirmation before we merge it. Ask: approve as a temporary dev dependency, and accept the framework upgrade as the deliverable it unblocks.

For engineering (the practical case): It's a drop-in replacement for the removed assertSelect* family, installed with composer require --dev, intended to require little or no change at call sites. Practical guidance: pin the exact version, run it green in CI on a branch before merging, and don't build new tests on it — for new work use assertSee/assertSeeText or Symfony DomCrawler directly. It's WIP with a small user base, so treat any unexpected assertion semantics as a bug to report or work around, not a contract. Have an exit: each migrated suite should be a candidate for conversion to first-party assertions, and the dependency should be gone within a couple of quarters. If the call-site count turns out to be small, kill the dependency and just rewrite — that's the better outcome and we should be willing to take it.