Asset Mapper Test Bundle Laravel Package

Product Decisions This Supports

• Front-end test strategy for AssetMapper apps. This package is the enabler for "we want unit tests on our JS without adopting npm/Vite/Webpack." It shims AssetMapper's assets/vendor layout into node_modules-style resolution so a Node test runner (Vitest/Jest) can resolve bare specifiers like @hotwired/stimulus or jquery-ui/ui/widgets/sortable. That makes "keep importmap as the single source of dependency truth, test with Node anyway" a viable roadmap option rather than a tradeoff.
• Build vs. buy vs. build-internally. The alternative is a hand-rolled CI script that generates symlinks/shims — typically 50–150 lines of fragile glue owned by whoever last touched the front-end. This is a small dev-only dependency that replaces that glue; the 0.2.2 fixes are exactly the bugs an internal script would have shipped with and never fixed.
• Scope and sequencing of a JS testing initiative. Because it works with both the symlink and loader variants, it does not force a decision on AssetMapper's vendor strategy first — you can start writing tests before settling that architectural question.
• Upgrade/pin policy as a risk decision. 0.2.2 fixes a genuine data-integrity bug: prior versions could write index.js and package.json through a directory symlink into assets/vendor/, permanently contaminating project source assets. If this is already in a codebase, "pin to ≥0.2.2" is a maintenance decision worth making explicitly, not a nice-to-have.
• CI investment. Reducing ERR_MODULE_NOT_FOUND flakiness in the JS test job directly affects whether the team treats front-end tests as trustworthy signal or as noise to be muted.

When to Consider This Package

Consider it when all of these hold:

• The application uses Symfony AssetMapper (or a comparable importmap-based vendor layout) as its front-end dependency mechanism — no bundler in the loop.
• You want JS unit tests running under a Node test runner, and the code under test imports vendor bare specifiers (Stimulus controllers, jQuery plugins, etc.).
• You want to avoid maintaining a parallel package.json/npm install just to satisfy the test runner.
• Your vendor set includes real-world packages with directory-based layouts and chunk files — i.e. the messy cases 0.2.2 addresses.

Look elsewhere when:

• You already use Vite, Webpack Encore, or any bundler — the bundler's own resolution already handles this, and the shim adds a layer with no payoff.
• Your JS tests only cover your own modules with no vendor imports, or you mock vendor dependencies at the test boundary.
• You need this at runtime in production — it is test/dev tooling; keep it in require-dev and out of deployed artifacts.
• Laravel specifically: most Laravel projects use Vite, not AssetMapper. There is no natural insertion point unless the project has deliberately adopted a Symfony-style importmap vendor layout. Validate that assumption before spending roadmap time on it — this is a niche fit, not a default Laravel recommendation.

Given 0.2.x versioning, treat adoption as piloting, not standardizing: the 0.2.2 changelog is a list of real-world layouts that broke, which is a reasonable proxy for "more layouts are out there that haven't broken yet."

How to Pitch It (Stakeholders)

To executives: A small, dev-only dependency that lets us write automated tests for our front-end code without adding an npm build pipeline or a second dependency list to maintain. The 0.2.2 release is maintenance-grade — bug fixes, no breaking changes, no new features, nothing to re-architect. It also closes a bug where earlier versions could write files into our source asset directory; that alone justifies pinning to this version if we adopt. Cost is near zero; the upside is test coverage on JS we currently can't test cheaply.

To engineering: Drop-in test-time shim that maps AssetMapper vendor entries into Node-resolvable modules. 0.2.2 fixes three resolution failures (<basename>.index.js directory layouts, subpath file entries, CSS entries shadowing JS entries) and, most importantly, stops writing through existing symlinks into assets/vendor/ — upgrade if you're on 0.2.1 or below, and audit assets/vendor for stray index.js/package.json files if you've already run the old version. Not a runtime dependency; keep it in require-dev. Caveat: it's 0.2.x and only pays off if we're committed to importmap-style vendor assets — if we're on Vite, skip it.