Testing Strategy & Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• src/templates.rs
• src/topics.rs
• src/batch.rs
• src/automations.rs
• src/contacts.rs
• src/error.rs
• src/segments.rs
• src/emails.rs
• src/events.rs

Testing within the resend-rust SDK ensures that API client implementations correctly interact with the Resend production environment and handle data serialization/deserialization accurately. The strategy relies on integration tests that perform live API calls and unit tests that validate JSON structures.

Integration Testing

Integration tests verify the full request-response lifecycle between the SDK and the Resend API. These tests require a valid RESEND_API_KEY environment variable to authenticate requests.

Execution Environment

The project uses a shared client for testing to manage rate limits and prevent server-side errors. Because some API operations (like resource creation) are asynchronous on the server, tests include thread::sleep statements to ensure resources are fully processed before the next assertion.

Sources: CONTRIBUTING.md:3-15

Test Attributes

The SDK employs specific Rust crates to manage test execution flow:

• tokio_shared_rt: Manages a shared asynchronous runtime across tests.
• serial_test::serial: Ensures tests run sequentially when they modify shared resources or require specific timing.
• maybe_async: Facilitates testing for both async and blocking features.

Sources: src/templates.rs:252-255, src/topics.rs:188-191, src/automations.rs:374-377

Integration Flow Diagram

The following diagram illustrates the typical lifecycle of an integration test for a resource (e.g., a Template or Topic).

The delay duration varies based on the resource type; for example, Templates typically use 1-second delays, while Topics or Contacts often require 4-second delays to settle.
Sources: src/templates.rs:271, src/topics.rs:200, src/contacts.rs:1062

Unit Testing & Serialization

Unit tests validate the internal logic of the SDK, primarily focusing on the correct serialization of request options and deserialization of API responses. These tests do not require a network connection or an API key.

Data Validation

Tests ensure that the SDK correctly handles nullable fields and strongly typed enums during the transformation from raw JSON strings to Rust structures.

Test Type	Target Component	Validation Logic
Deserialization	Template	Validates variables field handles null vs missing keys.
Deserialization	Topic	Validates mapping of default_subscription strings to enums.
Serialization	CreateAutomationOptions	Ensures nested Step structures map to correct JSON tags.
Serialization	ContactChanges	Verifies HashMap properties serialize to JSON objects.

Sources: src/templates.rs:343-393, src/topics.rs:242-255, src/automations.rs:319-351, src/contacts.rs:1255-1282

Error Integrity Testing

The project includes a specific test to ensure ErrorKind remains synchronized with the official Resend API documentation. This test scrapes the Resend documentation site and compares the listed error codes against the ErrorKind enum variants.

Sources: src/error.rs:249-317

Batch & Permissive Testing

Batch testing covers scenarios involving multiple email operations in a single call. These tests specifically target the BatchSvc to validate Strict and Permissive validation modes.

Batch Validation Modes

Tests confirm that:

1. Strict Mode: The entire batch fails if one email is invalid.
2. Permissive Mode: Valid emails are processed even if others fail, allowing for partial success verification.

Sources: src/batch.rs:127-184

Batch Process Flow

Summary of Testing Requirements

Resource	Required Sleep (Seconds)	Source File
Templates	1s	src/templates.rs
Topics	1s - 4s	src/topics.rs
Automations	2s	src/automations.rs
Contacts	2s - 4s	src/contacts.rs
Segments	2s	src/segments.rs

The resend-rust testing strategy combines rigorous integration tests for live API compatibility with detailed unit tests for data integrity. The reliance on sequential execution and artificial delays ensures stability against the rate-limited nature of the production Resend API.