Mocking and Testing
Relevant source files
The following files were used as context for generating this wiki page:
The Resend .NET SDK employs a multi-layered testing strategy to ensure API client reliability, payload integrity, and documentation accuracy. The system includes unit tests for data models, integration tests using a hosted mock server, and specialized tools to verify code samples within documentation.
Testing spans three primary areas:
- Payload Verification: Validating JSON serialization and deserialization against real-world and edge-case API responses.
- Client Integration: Testing
ResendClientmethods against a local test server to verify HTTP request formation and response handling. - Documentation Validation: Automatically compiling and checking code snippets in Markdown files to prevent API drift.
Automated Documentation Testing
The Resend.DocsCheck tool verifies the technical accuracy of code samples found in the project's .mdx documentation. It extracts C# code blocks, wraps them in a valid program structure, and performs a Roslyn-based compilation to ensure the samples are syntactically correct and compatible with the current SDK version.
Compilation Flow
The tool iterates through directories to find documentation files, extracts code blocks marked with csharp .NET, and attempts to compile them into memory using CSharpCompilation.
The tool specifically includes references to IResend, HttpClient, and core System libraries to simulate a real development environment.
Sources: tools/Resend.DocsCheck/Program.cs:113-162, tools/Resend.DocsCheck/Program.cs:175-200
Client Integration Testing
Integration tests for the ResendClient utilize WebApplicationFactory<Program> to spin up a local instance of a mock API server. This allows tests to perform actual HTTP calls without reaching the external Resend production API.
Test Architecture
Tests inherit from IClassFixture<WebApplicationFactory<Program>>, which provides a pre-configured HttpClient pointing to the in-memory test server.
Request Recording
For fine-grained verification of the JSON sent to the API, the SDK uses a RecordingHandler pattern. This custom HttpMessageHandler intercepts outgoing requests and stores the body for assertion.
| Component | Purpose |
|---|---|
RecordingHandler | Captures HttpRequestMessage and reads body content into JsonDocument. |
Bodies List | Stores captured request bodies for post-call assertion. |
ResendClient.Create | Accepts the custom handler via an HttpClient instance. |
Sources: tests/Resend.Tests/ContactRequestTests.cs:89-105, tests/Resend.Tests/ResendClientTests.Metrics.cs:228-245
Payload and Serialization Testing
Unit tests validate the robust handling of API-specific wire formats, particularly regarding non-standard date formats and polymorphic data structures.
Serialization Challenges
- Postgres Timestamps: Deserialization logic is tested to handle non-ISO 8601 strings (e.g., "2023-10-06 23:47:56.678+00") which include space separators and two-digit offsets.
- Polymorphic Webhooks: Tests verify that
WebhookEventConvertercorrectly reconstructs specific data types (e.g.,EmailEventData,SuppressionEventData) based on thetypefield in the webhook JSON. - Filtering Logic: Verification that multiple query parameters (like
domain_id) are correctly comma-joined when sent to metrics endpoints.
Sources: tests/Resend.Tests/SuppressionTests.cs:141-160, tests/Resend.Webhooks.Tests/WebhookEventConverterTests.cs:10-40, tests/Resend.Tests/ResendClientTests.Metrics.cs:117-133
Mocking for Resilience
The project provides a ResendMockClient (referenced in examples) specifically for testing application error-handling logic. This mock is used in background job scenarios to simulate transient failures, such as failing the first two attempts of an email send to verify that retry mechanisms (like Hangfire) function correctly.
Sources: examples/AsyncHangfire/README.md:28-36
Test Data Tables
The following table summarizes key test areas and the files responsible for their validation:
| Test Area | Target Functionality | Source File |
|---|---|---|
| Suppression | Non-UUID source IDs, Postgres timestamps | SuppressionTests.cs |
| Metrics | DateKind handling, Dimension combinations | ResendClientTests.Metrics.cs |
| Webhooks | Event roundtrip, literal wire types | WebhookEventConverterTests.cs |
| Contacts | JSON property types (number vs string) | ContactRequestTests.cs |
| API Coverage | Inboxes, Domains, Webhooks, Automations | ResendClientTests.*.cs |
Sources: tests/Resend.Tests/SuppressionTests.cs, tests/Resend.Tests/ResendClientTests.Metrics.cs, tests/Resend.Webhooks.Tests/WebhookEventConverterTests.cs
Testing is integral to the development lifecycle, with the cicd/release.sh script enforcing that dotnet test must pass before any NuGet package is published.
Sources: cicd/release.sh:42-47