Rust Advanced Testing Workshop

This workshop provides a structured learning path for advanced testing techniques in Rust. The curriculum is divided into several key modules:

• Better Assertions: Moving beyond standard assertions using googletest for matchers (Eq, Option, Result, Enums, Collections), custom matchers, and expect_that!.
• Snapshot Testing: Using insta for snapshot testing, managing storage locations, and implementing redactions.
• Mocks: Implementing mocks using mockall, including handling traits, call sequences, checkpoints, and mocking foreign traits.
• Filesystem Isolation: Using tempfile and named_tempfile to manage temporary files and directories safely during tests.
• Database Isolation: Using sqlx::test for isolated database testing.
• HTTP Mocking: Using wiremock to mock HTTP services, including the use of matchers and checkpoints.
• Macros: Learning how to write test-related macros, from no-op macros to parsing tokens and arguments.
• Test Harnesses: Creating custom test harnesses and using libtest_mimic for CLI-based testing.

The workshop concludes with a Capstone project to apply these integrated skills.

To use test doubles (mocks/stubs) in Rust, you must decouple your functions from concrete implementations. Because Rust is statically typed, a function expecting a specific type like Auth0Client cannot accept a mock object.

To solve this, you must refactor to an interface by using Traits. A trait defines a collection of methods that can be implemented by both your real production types and your test doubles. This allows the function to remain polymorphic, accepting any type that implements the required trait.

// 1. Define the interface (Trait)
trait Authenticator {
    async fn verify(&self, jwt: &str) -> Result<UserId, VerificationError>;
}

// 2. Implement the trait for the real production type
impl Authenticator for Auth0Client {
    async fn verify(&self, jwt: &str) -> Result<UserId, VerificationError> {
        // real implementation
    }
}

// 3. Update the function to use a generic type bounded by the trait
async fn login<A>(
    request: &HttpRequest,
    database_pool: &DatabasePool,
    authenticator: &A,
    rate_limiter: &RateLimiter,
) -> Result<LoginResponse, LoginError>
where
    A: Authenticator,
{
    // ...
}

When testing code that relies on external network services, there are three primary strategies to consider:

1. End-to-End Testing: Run a real test instance of the external service. This provides the highest confidence and realism but can be expensive, complex to orchestrate in microservice architectures, or impossible if the service is inaccessible.
2. HTTP Interception (Mocking): Use a library to intercept HTTP requests and return pre-determined responses. This exercises your production HTTP client stack while avoiding the overhead of a real service. The main risk is 'mock drift', where mocks become out of sync with the actual service API.
3. Abstraction/Test Doubles: Hide the network dependency behind a trait or interface and inject a test double (mock/stub) instead of the production implementation. This was covered in the workshop's mocking section.

This workshop focuses on Option #2 using the wiremock crate.

Custom test macros (like #[tokio::test] or #[sqlx::test]) are implemented as attribute procedural macros. These act as token transformers that intercept Rust code during compilation.

An attribute procedural macro receives two inputs:

1. args: A stream of tokens representing the arguments passed to the macro.
2. item: A stream of tokens representing the Rust code being annotated.

The macro processes these and returns a new stream of tokens, which is the actual code that gets compiled.

Example: #[tokio::test] transformation

When you write an async test with #[tokio::test], the macro rewrites it into a synchronous function that uses a runtime to block on the async block:

Input code:

#[tokio::test(flavor = "multi_thread")]
async fn it_works() {
    assert!(true);
}

Transformed code (what actually compiles):

#[test]
fn it_works() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            assert!(true);
        })
}

use proc_macro::TokenStream;

#[proc_macro_attribute]
pub fn test(args: TokenStream, item: TokenStream) -> TokenStream {
    // Implementation logic goes here
}