Testing the SDK

Relevant source files

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

• tests/conftest.py
• tests/request_test.py
• tests/templates_test.py
• tests/templates_async_test.py
• tests/webhooks_test.py
• tests/exceptions_test.py
• tests/inboxes_test.py

Testing the SDK ensures the Resend Python library correctly handles API requests, processes responses, and manages error states. The test suite verifies both synchronous and asynchronous operations across all available modules, including Emails, Templates, Webhooks, and Inboxes.

The testing infrastructure relies on pytest and custom base classes to mock network interactions. This allows for comprehensive validation of request parameters, URL encoding, and the internal logic of the SDK without making real HTTP calls to the Resend production API.

Sources: tests/templates_test.py, tests/templates_async_test.py, tests/request_test.py

Test Infrastructure and Mocking

The project uses a structured inheritance model for tests to maintain consistency and provide shared mocking utilities.

Base Test Classes

Tests inherit from two primary base classes:

• ResendBaseTest: Provides synchronous mocking capabilities using unittest.mock.
• AsyncResendBaseTest: Extends testing to asyncio operations, typically used with pytestmark = pytest.mark.asyncio.

These base classes provide the set_mock_json() method. This method configures the internal mock client to return a specific JSON payload, simulating an API response.

Sources: tests/conftest.py, tests/templates_test.py:7, tests/templates_async_test.py:12

HTTP Client Mocking

The SDK tests verify that requests are dispatched with correct headers and URLs. This include:

• Authentication: Validating that the Authorization: Bearer <key> header is present.
• User-Agent: Ensuring the User-Agent string follows the format resend-python:<version>.
• Idempotency: Confirming the Idempotency-Key is passed when provided in request options.

The diagram shows how a test case interacts with the mock infrastructure to verify SDK behavior.

Sources: tests/request_test.py:53-73, tests/inboxes_test.py:507-522

API Module Testing

Each functional module of the SDK has corresponding test files that validate CRUD operations and specialized endpoints.

Request Validation

Tests verify that the SDK correctly constructs URLs and encodes parameters. For example, when identifiers like email addresses contain special characters, the tests ensure they are URL-encoded before the request is made.

Feature Tested	Validation Logic
URL Encoding	Encodes / as %2F and @ as %40 in paths.
Pagination	Appends limit, before, and after as query strings.
JSON Body	Verifies the request body matches the expected schema.

Sources: tests/inboxes_test.py:533-542, tests/templates_test.py:165-185

Webhook Verification Testing

The Webhooks module includes specialized tests for signature verification. These tests manually generate HMAC signatures using sha256 and verify the SDK's ability to:

1. Validate correct signatures against a secret.
2. Reject signatures if the timestamp is outside the 5-minute tolerance window.
3. Handle multiple signatures in the header.
4. Detect tampered payloads.

Sources: tests/webhooks_test.py:161-260

Exception and Error Handling

The SDK testing suite validates that the library raises appropriate exceptions based on API status codes and response bodies.

Error Mapping

Tests in tests/exceptions_test.py use the raise_for_code_and_type function to verify the mapping of HTTP status codes to custom Python exceptions.

HTTP Code	Error Type	Exception Raised
401	missing_api_key	MissingApiKeyError
422	validation_error	ValidationError
422	missing_required_field	MissingRequiredFieldsError
429	rate_limit_exceeded	RateLimitError
500	application_error	ApplicationError

Sources: tests/exceptions_test.py:15-60

Response Decoding Errors

Specific tests verify that the SDK handles malformed API responses. If the API returns non-JSON content or invalid characters, the SDK raises a ResendError with a "Failed to decode JSON response" message while preserving the original HTTP status code and headers.

Sources: tests/request_test.py:20-45

Async Testing Implementation

Asynchronous tests use pytest-asyncio to validate the non-blocking versions of SDK methods. These tests follow the same pattern as synchronous tests but utilize await and AsyncMock to handle coroutines.

The sequence diagram illustrates the flow of an asynchronous test execution.

Sources: tests/templates_async_test.py:15-32, tests/webhooks_async_test.py:190-210

Testing the SDK provides the primary mechanism for ensuring reliability across the library's features. By combining standardized mocking with rigorous error and edge-case validation, the test suite maintains the integrity of both synchronous and asynchronous communication with the Resend API.