Nabs.Launchpad.Core.Testing.Silos 9.0.145

Nabs Launchpad Core Testing Silos Library

A .NET 9 library providing Orleans test cluster capabilities for integration testing of Orleans grains in the Nabs Launchpad framework. This library simplifies the setup and configuration of Orleans test environments with support for containerized SQL Server databases and comprehensive service configuration.

Overview

The Nabs.Launchpad.Core.Testing.Silos library enables developers to create isolated test environments for Orleans grains using Microsoft Orleans TestingHost. It provides a unified approach to testing grain interactions, database migrations, and service integrations in a controlled environment.

Features

• Orleans Test Cluster: Easy setup of Orleans test clusters with configurable replica count
• Containerized SQL Server: Integrated MS SQL Server containers using Testcontainers
• Database Migrations: Automated database setup with EF Core migrations and seed data
• Localization Support: Configurable culture settings for testing internationalized applications
• Serialization Configuration: Flexible Orleans serialization setup for custom types
• Service Configuration: Extensible service container configuration for both silo and client
• Memory Storage: Pre-configured in-memory grain storage for fast test execution

Installation

This library is part of the Nabs Launchpad framework and is typically referenced as a project dependency:

<ProjectReference Include="..\Nabs.Launchpad.Core.Testing.Silos\Nabs.Launchpad.Core.Testing.Silos.csproj" />

Dependencies

• Microsoft.Orleans.TestingHost: Orleans testing framework
• Microsoft.EntityFrameworkCore.SqlServer: Entity Framework Core SQL Server provider
• Testcontainers.MsSql: MS SQL Server container support
• Microsoft.Extensions.Localization: Localization services
• Nabs.Launchpad.Core.Interfaces: Shared grain interfaces and serialization options
• Nabs.Launchpad.Core.SeedData: Database seeding infrastructure

Key Components

TestSiloStartup

The main entry point for configuring and starting Orleans test clusters:

public class TestSiloStartup
{
    public TestSiloStartup(TestSiloStartupOptions options)
    public void ConfigureSiloServices(Action<IServiceCollection> configureServices)
    public void ConfigureClientServices(Action<IServiceCollection> configureServices)
    public async Task StartMsSqlContainer<TDbContext>(string containerName, string catalogName)
    public void DeployCluster()
    public async Task RunMigrations<TDbContext, TMigrationProcess, TSeedDataProcessor>()
    public async ValueTask StopAsync()
}

TestSiloStartupOptions

Configuration options for the test cluster:

public sealed class TestSiloStartupOptions
{
    public string DefaultCulture { get; init; } = string.Empty;
    public short Replicas { get; init; } = 1;
    public bool UseMigrations { get; init; } = false;
    public List<string> SerializationSupportedPrefixes { get; } = [];
}

TestSiloConfigurator

Internal configurator for Orleans silo services with memory storage and extensible service configuration.

TestClientConfigurator

Internal configurator for Orleans client services with localization and extensible service configuration.

Usage Examples

Basic Test Setup

[Fact]
public async Task TestGrainBehavior()
{
    // Arrange
    var options = new TestSiloStartupOptions
    {
        DefaultCulture = "en-US",
        Replicas = 1,
        SerializationSupportedPrefixes = { "MyApp.Contracts" }
    };

    var testSilo = new TestSiloStartup(options);
    
    testSilo.ConfigureSiloServices(services =>
    {
        services.AddTransient<IMyService, MyService>();
    });

    testSilo.DeployCluster();

    // Act
    var grain = TestSiloStartup.Cluster.GrainFactory.GetGrain<IMyGrain>("test-key");
    var result = await grain.DoSomethingAsync();

    // Assert
    result.Should().NotBeNull();

    // Cleanup
    await testSilo.StopAsync();
}

Test with SQL Server Container

[Fact]
public async Task TestGrainWithDatabase()
{
    // Arrange
    var options = new TestSiloStartupOptions
    {
        DefaultCulture = "en-US",
        UseMigrations = true
    };

    var testSilo = new TestSiloStartup(options);

    // Start SQL Server container
    await testSilo.StartMsSqlContainer<MyDbContext>("test-sql-container", "TestDatabase");

    testSilo.ConfigureSiloServices(services =>
    {
        services.AddScoped<IMyRepository, MyRepository>();
    });

    testSilo.DeployCluster();

    // Run migrations and seed data
    await testSilo.RunMigrations<MyDbContext, MyMigrationProcessor, MySeedDataProcessor>();

    // Act
    var grain = TestSiloStartup.Cluster.GrainFactory.GetGrain<IDataGrain>("data-key");
    var data = await grain.GetDataAsync();

    // Assert
    data.Should().NotBeNull();

    // Cleanup
    await testSilo.StopAsync();
}

Advanced Configuration

[Fact]
public async Task TestWithAdvancedConfiguration()
{
    // Arrange
    var options = new TestSiloStartupOptions
    {
        DefaultCulture = "fr-FR",
        Replicas = 2, // Multi-silo cluster
        UseMigrations = true,
        SerializationSupportedPrefixes = 
        {
            "MyApp.Contracts",
            "MyApp.Events",
            "MyApp.Models"
        }
    };

    var testSilo = new TestSiloStartup(options);

    await testSilo.StartMsSqlContainer<MyDbContext>("multi-silo-test", "MultiSiloDb");

    // Configure silo services
    testSilo.ConfigureSiloServices(services =>
    {
        services.AddScoped<IBusinessService, BusinessService>();
        services.AddSingleton<IEventProcessor, EventProcessor>();
    });

    // Configure client services
    testSilo.ConfigureClientServices(services =>
    {
        services.AddHttpClient<IExternalApiClient, ExternalApiClient>();
    });

    testSilo.DeployCluster();
    await testSilo.RunMigrations<MyDbContext, MyMigrationProcessor, MySeedDataProcessor>();

    // Act & Assert
    var grain1 = TestSiloStartup.Cluster.GrainFactory.GetGrain<IBusinessGrain>("business-1");
    var grain2 = TestSiloStartup.Cluster.GrainFactory.GetGrain<IBusinessGrain>("business-2");

    var result1 = await grain1.ProcessBusinessLogicAsync();
    var result2 = await grain2.ProcessBusinessLogicAsync();

    result1.IsSuccess.Should().BeTrue();
    result2.IsSuccess.Should().BeTrue();

    // Cleanup
    await testSilo.StopAsync();
}

Base Test Class Pattern

public abstract class GrainTestBase : IAsyncLifetime
{
    protected TestSiloStartup TestSilo { get; private set; } = default!;
    protected IGrainFactory GrainFactory => TestSiloStartup.Cluster.GrainFactory;

    public virtual async Task InitializeAsync()
    {
        var options = new TestSiloStartupOptions
        {
            DefaultCulture = "en-US",
            SerializationSupportedPrefixes = { "MyApp" }
        };

        TestSilo = new TestSiloStartup(options);
        ConfigureServices();
        TestSilo.DeployCluster();
        await SetupDatabaseAsync();
    }

    protected virtual void ConfigureServices()
    {
        TestSilo.ConfigureSiloServices(services =>
        {
            // Override in derived classes
        });
    }

    protected virtual async Task SetupDatabaseAsync()
    {
        // Override in derived classes if database is needed
    }

    public virtual async Task DisposeAsync()
    {
        await TestSilo.StopAsync();
    }
}

public class MyGrainTests : GrainTestBase
{
    [Fact]
    public async Task MyGrain_ShouldWork()
    {
        // Arrange
        var grain = GrainFactory.GetGrain<IMyGrain>("test");

        // Act
        var result = await grain.DoWorkAsync();

        // Assert
        result.Should().NotBeNull();
    }
}

Container Management

The library uses Testcontainers for SQL Server management with the following features:

• Container Reuse: Containers are reused across test runs for performance
• Automatic Cleanup: Containers are properly disposed when tests complete
• Isolated Databases: Each test can use its own database catalog
• Migration Support: Automatic EF Core migration execution

Memory Storage

All test clusters use in-memory grain storage by default:

• Fast test execution
• No external dependencies
• Automatic cleanup between tests
• Suitable for most grain testing scenarios

Localization Testing

Configure culture-specific testing:

var options = new TestSiloStartupOptions
{
    DefaultCulture = "de-DE" // Test German localization
};

Integration with Launchpad

This library integrates with other Nabs Launchpad components:

• Core.Interfaces: Grain interfaces and serialization configuration
• Core.SeedData: Database migration and seeding infrastructure
• Core.Silo: Production silo configuration patterns
• Core.Context: Entity Framework context integration

Best Practices

1. Container Naming: Use unique container names for parallel test execution
2. Resource Cleanup: Always call StopAsync() in test cleanup
3. Base Classes: Use base test classes for common setup patterns
4. Isolation: Each test should be independent and not rely on shared state
5. Serialization: Configure serialization prefixes for all custom types used in grains

Testing Guidelines

• Use xUnit with Microsoft.Testing.Platform
• Follow the AAA pattern (Arrange, Act, Assert)
• Implement IAsyncLifetime for proper async setup/cleanup
• Use FluentAssertions for readable test assertions
• Keep tests focused and test single behaviors

Contributing

This library follows the Nabs Launchpad coding standards:

• Use C# 13 features and latest language constructs
• Follow nullable reference types conventions
• Implement proper async/await patterns
• Include comprehensive unit tests
• Use file-scoped namespaces and modern C# syntax

License

Copyright � Net Advantage Business Solutions