Microcks Aspire .NET

Build Status

Sonarcloud Quality metrics

Fossa license and security scans

OpenSSF best practices on Microcks core

Community

How to use it?

Include it into your project dependencies

dotnet add package Microcks.Aspire --version 0.1.0

Setup with Aspire

var microcks = builder.AddMicrocks("microcks")
 .WithImage("microcks/microcks-uber", "latest");

Import content in Microcks

var microcks = builder.AddMicrocks("microcks")
 .WithMainArtifacts(
 "resources/third-parties/apipastries-openapi.yaml",
 "resources/order-service-openapi.yaml"
 )
 .WithSecondaryArtifacts(
 "resources/order-service-postman-collection.json",
 "resources/third-parties/apipastries-postman-collection.json"
 );

var microcks = builder.AddMicrocks("microcks")
 .WithSnapshots("microcks-repository.json");

Using mock endpoints for your dependencies

// From the MicrocksResource directly
var pastryApiUrl = microcksResource
 .GetRestMockEndpoint("API Pastries", "0.0.1")
 .ToString();

var webApplicationFactory = new WebApplicationFactory<Program>()
 .WithWebHostBuilder(builder =>
 {
 builder.UseEnvironment("Test");
 builder.UseSetting("PastryApi:BaseUrl", pastryApiUrl);
 });

Verifying mock endpoint has been invoked

var app = orderHostAspireFactory.App;
var microcksClient = app.CreateMicrocksClient("microcks");
bool isVerified = await microcksClient.VerifyAsync(
 "API Pastries", "0.0.1", 
 cancellationToken: TestContext.Current.CancellationToken);
Assert.True(isVerified, "API should be verified successfully");

double initialCount = await microcksClient.GetServiceInvocationsCountAsync(
 "API Pastries", "0.0.1", 
 cancellationToken: TestContext.Current.CancellationToken);
// ... perform your API calls ...
double finalCount = await microcksClient.GetServiceInvocationsCountAsync(
 "API Pastries", "0.0.1", 
 cancellationToken: TestContext.Current.CancellationToken);
Assert.Equal(initialCount + expectedCalls, finalCount);

Launching contract-tests with Aspire

{
 "profiles": {
 "YourTestProject": {
 "environmentVariables": {
 "ASPIRE_ENABLE_CONTAINER_TUNNEL": "true"
 }
 }
 }
}

[Fact]
public async Task TestOpenApiContract()
{
 // Arrange
 var app = _fixture.App;
 // Use GetEndpointForNetwork with the container network context so that Microcks (running in a container)
 // can access the order-api service from the Aspire container network
 Uri endpoint = app.GetEndpointForNetwork("order-api", KnownNetworkIdentifiers.DefaultAspireContainerNetwork);
 TestRequest request = new()
 {
 ServiceId = "Order Service API:0.1.0",
 RunnerType = TestRunnerType.OPEN_API_SCHEMA,
 TestEndpoint = $"{endpoint.Scheme}://{endpoint.Host}:{endpoint.Port}/api",
 };
 var microcksClient = app.CreateMicrocksClient("microcks");
 var testResult = await microcksClient.TestEndpointAsync(request, TestContext.Current.CancellationToken);
 // Assert
 // You may inspect complete response object with following:
 var json = JsonSerializer.Serialize(testResult, new JsonSerializerOptions { WriteIndented = true });
 testOutputHelper.WriteLine(json);
 Assert.True(testResult.Success);
 Assert.False(testResult.InProgress, "Test should not be in progress");
 Assert.Single(testResult.TestCaseResults);
}

Business conformance checks

var messages = await microcksClient.GetMessagesForTestCaseAsync(testResult, "POST /orders", TestContext.Current.CancellationToken);
foreach (var message in messages)
{
 if ("201".Equals(message.Response.Status))
 {
 var responseDocument = JsonDocument.Parse(message.Response.Content);
 var requestDocument = JsonDocument.Parse(message.Request.Content);
 var requestProductQuantities = requestDocument.RootElement.GetProperty("productQuantities");
 var responseProductQuantities = responseDocument.RootElement.GetProperty("productQuantities");
 Assert.Equal(requestProductQuantities.GetArrayLength(), responseProductQuantities.GetArrayLength());
 for (int i = 0; i < requestProductQuantities.GetArrayLength(); i++)
 {
 var reqProductName = requestProductQuantities[i].GetProperty("productName").GetString();
 var respProductName = responseProductQuantities[i].GetProperty("productName").GetString();
 Assert.Equal(reqProductName, respProductName);
 }
 }
}

Advanced features with Aspire

Advanced Configuration

var microcks = builder.AddMicrocks("microcks")
 .WithMainArtifacts("pastry-orders-asyncapi.yml")
 // Additional configuration can be added here
 .WithPostmanRunner(); // Enables Postman contract-testing support

Postman contract-testing

var microcksClient = app.CreateMicrocksClient("microcks");
var testRequest = new TestRequest
{
 ServiceId = "API Pastries:0.0.1",
 RunnerType = TestRunnerType.POSTMAN,
 TestEndpoint = $"{app.GetEndpoint("my-api")}/api",
 Timeout = TimeSpan.FromSeconds(3)
};
TestResult testResult = await microcksClient.TestEndpointAsync(testRequest, TestContext.Current.CancellationToken);

var microcks = builder.AddMicrocks("microcks")
 .WithPostmanRunner(postmanBuilder =>
 {
 // Customize Postman runner settings
 postmanBuilder.WithEnvironment("MY_ENV_VAR", "sample");
 });

Async API contract-testing and mocking

var kafkaBuilder = Builder.AddKafka("kafka")
 .WithKafkaUI();
var microcksBuilder = builder.AddMicrocks("microcks")
 .WithMainArtifacts("pastry-orders-asyncapi.yml")
 .WithAsyncFeature(minion => {
 minion.WithKafkaConnection(kafkaBuilder, 9093);
 });

Using mock endpoints for your dependencies

// Retrieve MicrocksAsyncMinionResource from application
var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
var microcksAsyncMinionResource = appModel.GetContainerResources()
 .OfType<MicrocksAsyncMinionResource>()
 .Single();
// Get the Kafka topic for mock messages
string kafkaTopic = microcksAsyncMinionResource
 .GetKafkaMockTopic("Pastry orders API", "0.1.0", "SUBSCRIBE pastry/orders");
// Subscribe to the topic and consume messages
consumer.Subscribe(kafkaTopic);
var consumeResult = consumer.Consume(TimeSpan.FromMilliseconds(5000));

Launching new contract-tests

var testRequest = new TestRequest
{
 ServiceId = "Pastry orders API:0.1.0",
 RunnerType = TestRunnerType.ASYNC_API_SCHEMA,
 TestEndpoint = "kafka://kafka:9093/pastry-orders",
 Timeout = TimeSpan.FromSeconds(5)
};
var microcksClient = app.CreateMicrocksClient("microcks");
// Start the test, making Microcks listen to the endpoint
var taskTestResult = microcksClient.TestEndpointAsync(testRequest, cancellationToken);
// Wait a bit to let the test initialize
await Task.Delay(750, cancellationToken);
// Produce your events to the Kafka topic
producer.Produce("pastry-orders", new Message<string, string>
{
 Key = Guid.NewGuid().ToString(),
 Value = yourMessage
});
// Now retrieve the final test result and assert
TestResult testResult = await taskTestResult;
Assert.True(testResult.Success);

Retrieving event messages

// Retrieve event messages for the failing test case
List<UnidirectionalEvent> events = await microcksClient.GetEventMessagesForTestCaseAsync(
 testResult, "SUBSCRIBE pastry/orders", TestContext.Current.CancellationToken);
// Inspect the events
Assert.True(events.Count >= 1);
// Check event message content
foreach (var eventItem in events)
{
 Assert.NotNull(eventItem.EventMessage);
 var messageContent = eventItem.EventMessage.Content;
 
 // Parse and validate message structure
 var jsonDocument = JsonDocument.Parse(messageContent);
 var root = jsonDocument.RootElement;
 
 // Validate required fields
 Assert.True(root.TryGetProperty("id", out _));
 Assert.True(root.TryGetProperty("customerId", out _));
 Assert.True(root.TryGetProperty("productQuantities", out _));
}

Features

Initialization

Accessing endpoints

Testing features

Supported Mocking Protocols