MinimalLambda.Testing

In-memory Lambda runtime for end-to-end and integration testing with the MinimalLambda framework.

📚 View Full Documentation

Overview

MinimalLambda.Testing lets you run Lambda functions entirely in memory, exercising the same runtime API that AWS provides without deploying or opening network ports. It follows the familiar ASP.NET Core WebApplicationFactory pattern: reusing your real Program entry point via LambdaApplicationFactory<TEntryPoint> and driving it through a LambdaTestServer that mimics the Lambda Runtime API (init, invocation, and shutdown).

Use it to:

Boot real apps: Spin up your Lambda entry point with LambdaApplicationFactory just like ASP.NET's WebApplicationFactory
Simulate Runtime API: LambdaTestServer feeds events and receives responses/errors over the Lambda Runtime HTTP contract—no mocks or stubs
Typed Invocations: InvokeAsync<TEvent, TResponse> sends strongly typed events and returns typed responses, including structured error details
Lifecycle Coverage: Exercise OnInit and OnShutdown hooks and verify cold-start logic
Host Customization: Override configuration and services for tests with WithHostBuilder

Installation

This package extends MinimalLambda; install both:

dotnet add package MinimalLambda
dotnet add package MinimalLambda.Testing

Ensure your project uses C# 11 or later:

<PropertyGroup>
  <LangVersion>11</LangVersion>
  <!-- or <LangVersion>latest</LangVersion> -->
</PropertyGroup>

Quick Start

Write an end-to-end test that drives your Lambda through the in-memory runtime:

using MinimalLambda.Testing;
using Xunit;

public class LambdaTests
{
    [Fact]
    public async Task HelloWorldHandler_ReturnsGreeting()
    {
        await using var factory = new LambdaApplicationFactory<Program>();

        await factory.TestServer.StartAsync();

        var response = await factory.TestServer.InvokeAsync<string, string>("World");

        Assert.True(response.WasSuccess);
        Assert.Equal("Hello World!", response.Response);
    }
}

Customize the host configuration for a specific test:

await using var factory = new LambdaApplicationFactory<Program>().WithHostBuilder(builder =>
{
    builder.ConfigureServices((_, services) =>
    {
        // Override registrations or configuration for this test run
    });
});

Use LambdaServerOptions to tweak runtime details such as timeouts, ARN, or custom headers returned by the simulated Runtime API.

Key Features

Runtime-accurate simulation – Emulates the Lambda Runtime API (init, /invocation/next, response/error posts) over an in-memory message channel
End-to-end coverage – Drives source-generated handlers, middleware, envelopes, DI scopes, and lifecycle hooks exactly as they run in production
Typed invocation helpers – InvokeAsync<TEvent, TResponse> returns structured InvocationResponse objects with success flags and error payloads
Host customization – WithHostBuilder and LambdaApplicationFactoryContentRootAttribute mirror ASP.NET testing patterns for overriding configuration and locating content roots
Concurrency safe – Handles multiple pending invocations FIFO with per-request correlation

Other Packages

Additional packages in the minimal-lambda framework for abstractions, observability, and event source handling.

Package	NuGet	Downloads
MinimalLambda
MinimalLambda.Abstractions
MinimalLambda.OpenTelemetry
MinimalLambda.Testing
MinimalLambda.Envelopes
MinimalLambda.Envelopes.Sqs
MinimalLambda.Envelopes.ApiGateway
MinimalLambda.Envelopes.Sns
MinimalLambda.Envelopes.Kinesis
MinimalLambda.Envelopes.KinesisFirehose
MinimalLambda.Envelopes.Kafka
MinimalLambda.Envelopes.CloudWatchLogs
MinimalLambda.Envelopes.Alb