Testing Emails

Purpose and Scope

This page documents the testing infrastructure provided by the hypervel/mail package for verifying email functionality without sending actual emails. The system provides two specialized transport drivers for testing scenarios (ArrayTransport and LogTransport) and a comprehensive suite of assertion methods built into the Mailable class.

For information about configuring transports in general, see Transport System Overview. For details on creating and working with Mailable classes, see Working with Mailables.

---

Testing Architecture Overview

The mail testing system provides two primary approaches: transport-based testing and assertion-based testing. Transport-based testing intercepts outgoing emails at the transport layer, while assertion-based testing validates mailable content and properties directly.

Sources: src/Mailable.php991-1296 src/Transport/ArrayTransport.php src/Transport/LogTransport.php

---

ArrayTransport

The ArrayTransport class stores sent messages in an in-memory collection, allowing tests to inspect the full message content without external dependencies. This is the recommended approach for unit and integration testing.

Configuration

Configure the ArrayTransport in your test configuration:

Core Functionality

Method	Return Type	Purpose
send()	?SentMessage	Stores message in collection and returns SentMessage
messages()	Collection	Retrieves all stored messages
flush()	Collection	Clears the message collection

The ArrayTransport implements TransportInterface and stores each sent message as a SentMessage object containing both the raw message and envelope.

Usage Pattern

Sources: src/Transport/ArrayTransport.php1-57

---

LogTransport

The LogTransport class writes email messages to the application log instead of sending them. This is useful for development environments and debugging scenarios where you want to inspect email content without setting up a full testing infrastructure.

Configuration

Message Processing

The LogTransport performs special handling to make logged messages more readable:

1. Quoted-Printable Decoding: Messages with Content-Transfer-Encoding: quoted-printable are automatically decoded src/Transport/LogTransport.php41-43
2. Multipart Boundary Handling: For multipart messages, each part is processed separately src/Transport/LogTransport.php29-40

Accessing the Logger

The underlying logger instance can be accessed via the logger() method src/Transport/LogTransport.php70-72:

Sources: src/Transport/LogTransport.php1-82

---

Mailable Assertion Methods

The Mailable class provides a comprehensive set of assertion methods that leverage PHPUnit's assertion framework. These methods allow direct validation of mailable properties and rendered content without sending the email.

Assertion Architecture

All assertion methods follow a common pattern:

1. Call renderForAssertions() to prepare the mailable src/Mailable.php1303-1334
2. Validate the condition using the appropriate hasX() method
3. Use PHPUnit assertions to report failures

Sources: src/Mailable.php1299-1335

Recipient Assertions

Method	Parameters	Purpose
assertFrom()	$address, $name = null	Verify sender address
assertTo()	$address, $name = null	Verify "to" recipient
assertHasCc()	$address, $name = null	Verify "cc" recipient
assertHasBcc()	$address, $name = null	Verify "bcc" recipient
assertHasReplyTo()	$address, $name = null	Verify "reply to" address

Each recipient assertion method:

1. Calls renderForAssertions() to prepare the mailable
2. Formats the recipient for display using formatAssertionRecipient() src/Mailable.php1086-1097
3. Checks using the corresponding hasX() method (e.g., hasFrom(), hasTo())
4. Asserts with a descriptive error message

Example usage:

Sources: src/Mailable.php991-1081

Subject Assertion

The assertHasSubject() method verifies the email subject line src/Mailable.php1102-1112:

The method checks both the subject property and the envelope()->subject if the envelope() method exists src/Mailable.php727-731

Sources: src/Mailable.php1102-1112 src/Mailable.php727-731

Content Assertions (HTML)

Method	Parameters	Purpose
assertSeeInHtml()	$string, $escape = true	Assert text appears in HTML body
assertDontSeeInHtml()	$string, $escape = true	Assert text does not appear in HTML body
assertSeeInOrderInHtml()	$strings, $escape = true	Assert strings appear in specified order

The HTML content assertions use the first element of the assertionableRenderStrings array, which contains the rendered HTML output src/Mailable.php1117-1162

The $escape parameter controls whether the search string is HTML-escaped before comparison, defaulting to true for safety.

Example:

Sources: src/Mailable.php1114-1162

Content Assertions (Plain Text)

Method	Parameters	Purpose
assertSeeInText()	$string	Assert text appears in plain-text body
assertDontSeeInText()	$string	Assert text does not appear in plain-text body
assertSeeInOrderInText()	$strings	Assert strings appear in specified order

The text content assertions use the second element of the assertionableRenderStrings array src/Mailable.php1167-1206

Example:

Sources: src/Mailable.php1164-1206

Attachment Assertions

Method	Purpose
assertHasAttachment($file, $options = [])	Verify file attachment by path or Attachment object
assertHasAttachedData($data, $name, $options = [])	Verify in-memory data attachment
assertHasAttachmentFromStorage($path, $name = null, $options = [])	Verify storage attachment (default disk)
assertHasAttachmentFromStorageDisk($disk, $path, $name = null, $options = [])	Verify storage attachment from specific disk

Example:

Sources: src/Mailable.php1208-1266

Metadata Assertions

Method	Parameters	Purpose
assertHasTag()	$tag	Verify tag header exists
assertHasMetadata()	$key, $value	Verify metadata key-value pair

Tags and metadata are transport-specific headers supported by services like AWS SES and Mailgun src/Mailable.php1271-1296

Example:

Sources: src/Mailable.php1268-1296 src/Mailable.php954-988

---

Testing Workflow Patterns

Pattern 1: Using ArrayTransport for Full Integration Testing

This pattern tests the complete email sending pipeline:

Pattern 2: Using Assertion Methods for Unit Testing

This pattern tests mailable configuration without sending:

Pattern 3: Testing Queued Emails

For emails that implement ShouldQueue, test the mailable properties before queueing:

Pattern 4: Testing Attachments

Sources: src/Mailable.php163-182 src/Mailable.php991-1296 src/Transport/ArrayTransport.php29-48

---

Assertion Method Reference Table

Category	Method	Key Features
Recipients	assertFrom()	Validates sender, checks both property and envelope
assertTo()	Validates primary recipient
assertHasTo()	Alias for assertTo()
assertHasCc()	Validates carbon copy recipient
assertHasBcc()	Validates blind carbon copy recipient
assertHasReplyTo()	Validates reply-to address
Subject	assertHasSubject()	Validates subject line, checks property and envelope
HTML Content	assertSeeInHtml()	Text in HTML body, optional escaping
assertDontSeeInHtml()	Text not in HTML body, optional escaping
assertSeeInOrderInHtml()	Multiple strings in order, optional escaping
Text Content	assertSeeInText()	Text in plain-text body
assertDontSeeInText()	Text not in plain-text body
assertSeeInOrderInText()	Multiple strings in order
Attachments	assertHasAttachment()	File path or Attachment object
assertHasAttachedData()	In-memory data attachment
assertHasAttachmentFromStorage()	Storage file from default disk
assertHasAttachmentFromStorageDisk()	Storage file from specific disk
Metadata	assertHasTag()	Transport-specific tag header
assertHasMetadata()	Transport-specific metadata key-value

All assertion methods return $this for fluent chaining src/Mailable.php991-1296

Sources: src/Mailable.php991-1296