[wazum]

Rebased and reworked version of #102, which was closed as stale.

@Jamesking56 as suggested in #102, here is a fresh PR against current master.

Resolves: #12, #98

What's new

• Every "last email" action has an "nth email" counterpart, e.g. seeInNthEmail($nth, $text), seeInNthEmailTo($nth, $address, $text), grabUrlsFromNthEmail($nth), seeNthEmailAttachmentCount($nth, $count), nthMessage($nth) and nthMessageTo($nth, $address). Positions start at 1 and count in the order the emails were received. The ...To variants only count emails sent to that address.
• seeInLastEmailSender, seeInNthEmailSender, seeInLastEmailRecipient and seeInNthEmailRecipient. A recipient check passes when any one recipient matches.
• Email::getSender(). The sender is an optional last constructor argument, so existing new Email(...) calls keep working.
• The README documents all new actions.

Fix

The sort tie-breaker from #13 compared created_at . id as a string, which puts id 10 before id 9 when both arrive in the same second. That was mostly harmless for "last email" but breaks positional lookups. It now compares [created_at, id] tuples.

Changes compared to #102

• Dropped nthMessageFrom. It counted in the opposite direction from nthMessage and no action used it.
• The recipient check no longer requires every recipient to match.
• nthMessageTo no longer counts an email twice when several of its recipients match.
• The unit tests now exercise the module's real selection logic. Before, a copy of that logic lived in the test double.
• The last and nth variants share the attachment and URL code.
• The old lastMessageFrom unit test never ran because its name lacked the test prefix. It is now a real test.

Tests

Unit and acceptance suites pass on PHP 8.5 with the latest dependencies and on PHP 8.3 with --prefer-lowest (Codeception 5.0.0, PHPUnit 9.6.0, mail-mime-parser 3.0.1): 84 tests, 132 assertions.

[Jamesking56]

Please fix the recipient assertion so it passes only when an individual recipient contains the expected value. I confirmed the false positive in both the last and nth variants with a focused PHP reproduction.

[Jamesking56]

Medium — check each recipient separately. Joining the recipients allows a match to span recipient boundaries. For example, with ['<alice@example.com>', '<bob@example.com>'], an expectation of '<alice@example.com>, <bob@example.com>' passes even though neither recipient contains that string. This violates the documented ‘one recipient matches’ behavior and affects both seeInLastEmailRecipient() and seeInNthEmailRecipient(). A focused PHP reproduction confirmed that both assertions incorrectly pass. Please check each recipient separately and pass only when at least one contains the expected value. Add a regression test for an expectation that spans recipient boundaries.

[wazum]

Good catch, thanks. Fixed in e54a249: seeInEmailRecipients now checks each recipient on its own and passes only if at least one contains the expected value. On failure the message still lists all recipients.

Regression tests:

• Unit: testSeeInLastEmailRecipientDoesNotMatchAcrossRecipients uses your '<alice@example.com>, <bob@example.com>' example. It failed on the old code.
• Acceptance: test_see_in_email_recipient_checks_each_recipient sends one real email to two recipients. It checks that a single recipient matches and that a value spanning both fails through seeInNthEmailRecipient.

1019fa4 adds a test that nth positions follow created_at before the id tie-breaker. It also notes in the README that addresses match by substring, the same way the existing ...To actions already work.

[Jamesking56]

Reviewed all changed PHP files and checked the README against the implementation. No actionable findings. The local unit suite passed with 31 tests and 60 assertions; all six CI test jobs passed.

[Jamesking56]

Thanks @wazum

[github-actions]

Released in 4.1.0.