Json Test Fixtures Laravel Package

Product Decisions This Supports

• Test-infrastructure strategy: whether to standardize on a shared attachment-fixture library versus hand-rolled fixtures duplicated across test classes and repos. A single canonical representation of "an attachment" makes assertions portable between services and teams.
• Upgrade planning and breaking-change triage: v2.0.0 changes the fixture contract — an attachment fixture is now an object with up to two keys, metadata (the JSON-encoded attachment) and optional content (raw attachment bytes). Any suite that consumed the old flat value must be migrated. This is a bounded, mechanical migration and should be scoped as a scheduled maintenance task, not treated as a re-architecture.
• Coverage investment: because content is now optional, teams can express metadata-only attachments (filename, mime type, size, headers) without generating or loading a payload. Attachment test cases become cheap to add, which raises coverage per engineering hour.
• CI cost and runtime: raw content is opt-in, so large binary fixtures no longer have to be materialized in every test that touches attachments. A direct lever on suite runtime and memory for file- and mail-heavy test suites.
• Build vs buy: continue consuming this rather than maintaining an internal fixture builder. The v2 split between descriptive metadata and raw bytes is the abstraction an internal implementation would converge on anyway — the maintainer has done that design work for us.
• Dependency risk posture: shipping a breaking major to clean up a data shape is a healthy but notable signal. Plan for pinned majors and a periodic upgrade review rather than set-and-forget adoption.

When to Consider This Package

Adopt when:

• Laravel test suites construct or assert on attachments (mail, notifications, exports, file handling) and fixture-building code is repeated across test classes or repositories.
• Multiple teams or services need a consistent attachment representation so assertions look the same everywhere.
• You specifically need to distinguish an attachment's descriptive metadata from its bytes in tests — v2's two-key object maps one-to-one onto that distinction.
• You can pin the major version and absorb a one-time fixture migration.

Look elsewhere when:

• Attachment testing needs are trivial (one or two inline fixtures); a small local helper costs less in total than a dependency plus its upgrade cadence.
• You need production attachment handling — storage, streaming, virus scanning, signed URLs. This is a test-fixture concern, not runtime plumbing.
• You are on a Laravel/PHP version the release no longer supports, or you cannot take a breaking change this cycle. Stay on the prior major and revisit next quarter.
• Your release process requires strict backward-compatibility guarantees from dependencies. A package willing to ship a breaking major for a schema cleanup should sit behind a thin internal wrapper.

Migration checklist for teams already on the prior major: inventory every fixture construction site, convert each to { metadata, content? }, decide per fixture whether raw content is genuinely asserted on, then re-run suites. Expect failures wherever tests assumed a flat encoded value.

How to Pitch It (Stakeholders)

Executives: this is a small, low-risk test-infrastructure dependency, and v2.0.0 is a breaking change with a bounded, mechanical migration. Cost is a few engineer-days of fixture updates; the offset is cheaper attachment coverage, since raw content is now optional and we stop paying to materialize bytes we never assert on. No customer-facing impact and no architecture change. The only real decision is timing — fold the upgrade into the next maintenance window rather than letting it become an ad-hoc scramble later.

Engineering: v2 changes the fixture contract. Each attachment fixture is now an object with up to two keys — metadata (JSON-encoded attachment) and, when present, content (raw attachment content). Anything consuming the old shape must be updated. The tradeoff is worth taking: metadata and bytes are now separable, so metadata-only fixtures are cheap and large binaries are opt-in. Recommendation is to pin the major, do the conversion as one mechanical commit per repo, and record the convention so new tests are written against the v2 shape from day one.