Json Test Fixtures Laravel Package

Getting Started

Install the package via Composer and review the package’s README and tests/Fixtures (or equivalent) directory first. The v2.0.0 release changes attachment fixtures from plain strings to objects with two possible keys:

• metadata – the JSON-encoded attachment (always present)
• content – the raw attachment bytes (present only when available)

Minimal first use case: in a test, obtain a fixture object and feed its metadata to any code that expects the encoded attachment payload.

$fixture = AttachmentFixture::make('example.pdf');

// Most common: hand the JSON metadata to your application
$this->postJson('/attachments', [
    'attachment' => $fixture->metadata,
]);

// When you need the actual bytes (e.g. fake disk writes)
if (isset($fixture->content)) {
    Storage::fake('local')->put('example.pdf', $fixture->content);
}

Run your existing test suite immediately after upgrading. Any place that treated a fixture as a string will fail; update those call sites to use $fixture->metadata or $fixture->content.

Implementation Patterns

Test data factories and seeders
Use fixture objects as the source of truth for attachment payloads. Extract metadata for database columns that store JSON, and content for filesystem or blob columns.

$fixture = AttachmentFixture::make('invoice.pdf');

Attachment::factory()->create([
    'metadata' => $fixture->metadata,
    'content'  => $fixture->content ?? null,
]);

HTTP and API tests
When submitting multipart forms, use $fixture->content if the endpoint expects raw bytes. For JSON APIs that accept encoded attachments, use $fixture->metadata.

$this->post('/upload', [
    'file' => $fixture->content,
]);

$this->postJson('/api/attachments', [
    'file' => $fixture->metadata,
]);

Combining with Storage::fake and UploadedFile
Use fixture content to create fake uploads or seed storage without hitting real files. Keep metadata for assertions on stored JSON.

Storage::fake('attachments');
Storage::disk('attachments')->put('doc.pdf', $fixture->content);

$response = $this->postJson('/attachments', [
    'metadata' => $fixture->metadata,
]);
$response->assertCreated();

Custom fixtures
If the package exposes a fixture builder or contract, extend it to generate domain-specific attachments (e.g. PDFs with specific metadata). Always return an object with metadata and optionally content.

class InvoiceFixture extends AttachmentFixture
{
    public static function make(string $name = 'invoice.pdf'): self
    {
        return parent::make($name)->withMetadata([
            'type' => 'invoice',
            'mime' => 'application/pdf',
        ]);
    }
}

Integration with queues and jobs
When dispatching jobs that process attachments, pass metadata for serialized payloads and content only when the job truly needs the raw bytes. Avoid serializing large content into queue payloads unless required.

Gotchas and Tips

• v2.0.0 is a breaking change. Fixtures are no longer strings. Search your codebase for string operations on fixtures (strlen, concatenation, json_decode($fixture)) and replace them with $fixture->metadata or $fixture->content.
• content is optional. Always guard with isset($fixture->content) or $fixture->content ?? null. Do not assume every fixture has raw bytes.
• metadata is already JSON encoded. Do not double-encode it. If you need an array, decode explicitly: json_decode($fixture->metadata, true).
• Debugging fixture shape. Use dd($fixture) or dump($fixture) in a test to confirm which keys are present. The object may expose metadata and content as properties or array keys depending on the package’s implementation; check the package’s fixture class.
• Config quirks. Look for a published config file (e.g. config/attachment-fixtures.php) that controls fixture paths, default disk, or MIME mappings. Clear config cache after changes: php artisan config:clear.
• Upgrade checklist:
  1. composer require the v2 release.
  2. Run php artisan test and fix failures caused by string assumptions.
  3. Grep for fixture and attachment in tests and factories.
  4. Update any helper methods that returned fixture strings to return fixture objects.
• Extension points. If the package provides a fixture contract or base class, implement it for custom attachment types. Keep metadata as the canonical encoded payload and only add content when raw bytes are needed.