.NET library for Testcontainers that enables embedding Microcks into your unit tests with lightweight, throwaway instance thanks to containers.
Latest released version is 0.1.0
.
Current development version is 0.2.0
.
- Documentation
- Microcks Community and community meeting
- Join us on Discord, on GitHub Discussions or CNCF Slack #microcks channel
To get involved with our community, please make sure you are familiar with the project's Code of Conduct.
dotnet add package Microcks.Testcontainers --version 0.1.0
You just have to specify the container image you'd like to use. This library requires a Microcks uber
distribution (with no MongoDB dependency).
MicrocksContainer container = new MicrocksBuilder()
.WithImage("quay.io/microcks/microcks-uber:1.10.0")
.Build();
await container.StartAsync();
To use Microcks mocks or contract-testing features, you first need to import OpenAPI, Postman Collection, GraphQL or gRPC artifacts. Artifacts can be imported as main/Primary ones or as secondary ones. See Multi-artifacts support for details.
You can do it before starting the container using simple paths:
MicrocksContainer container = new MicrocksBuilder()
.WithMainArtifacts("apipastries-openapi.yaml")
.WithSecondaryArtifacts("apipastries-postman-collection.json")
.Build();
await container.StartAsync();
or once the container started using File
arguments:
container.ImportAsMainArtifact("apipastries-openapi.yaml");
container.ImportAsSecondaryArtifact("apipastries-postman-collection.json");
You can also import full repository snapshots at once:
MicrocksContainer container = new MicrocksBuilder()
.WithSnapshots("microcks-repository.json")
.Build();
await container.StartAsync();
During your test setup, you'd probably need to retrieve mock endpoints provided by Microcks containers to setup your base API url calls. You can do it like this:
var baseApiUrl = container.GetRestMockEndpoint("API Pastries", "0.0.1");
The container provides methods for different supported API styles/protocols (Soap, GraphQL, gRPC,...).
The container also provides GetHttpEndpoint()
for raw access to those API endpoints.
If you want to ensure that your application under test is conformant to an OpenAPI contract (or other type of contract), you can launch a Microcks contract/conformance test using the local server port you're actually running.
private int port;
public async Task InitializeAsync()
{
container = new MicrocksBuilder()
.WithExposedPort(port)
.Build();
await container.StartAsync();
}
[Fact]
public async Task testOpenAPIContract()
{
var testRequest = new TestRequest
{
ServiceId = "API Pastries:0.0.1",
RunnerType = TestRunnerType.OPEN_API_SCHEMA,
TestEndpoint = $"http://host.testcontainers.internal:{port}",
Timeout = TimeSpan.FromMilliseconds(2000)
};
TestResult testResult = await container.TestEndpointAsync(testRequest);
testResult.Success.Should().BeTrue();
}
The TestResult
gives you access to all details regarding success of failure on different test cases.
The MicrocksContainer
referenced above supports essential features of Microcks provided by the main Microcks container.
The list of supported features is the following:
- Mocking of REST APIs using different kinds of artifacts,
- Contract-testing of REST APIs using
OPEN_API_SCHEMA
runner/strategy, - Mocking and contract-testing of SOAP WebServices,
- Mocking and contract-testing of GraphQL APIs,
- Mocking and contract-testing of gRPC APIs.
To support features like Asynchronous contract-testing, we introduced MicrocksContainersEnsemble
that allows managing
additional Microcks services. MicrocksContainersEnsemble
allow you to implement
Different levels of API contract testing
in the Inner Loop with Testcontainers!
A MicrocksContainersEnsemble
presents the same methods as a MicrocksContainer
.
You can create and build an ensemble that way:
MicrocksContainersEnsemble ensemble = new MicrocksContainerEnsemble(network, MicrocksImage)
.WithMainArtifacts("pastry-orders-asyncapi.yml")
.WithKafkaConnection(new KafkaConnection($"kafka:19092"));
ensemble.StartAsync();
A MicrocksContainer
is wrapped by an ensemble and is still available to import artifacts and execute test methods.
You have to access it using:
MicrocksContainer microcks = ensemble.MicrocksContainer;
microcks.ImportAsMainArtifact(...);
Once started, the ensemble.AsyncMinionContainer
provides methods for retrieving mock endpoint names for the different
supported protocols (Kafka only at the moment).
string kafkaTopic = ensemble.AsyncMinionContainer
.GetKafkaMockTopic("Pastry orders API", "0.1.0", "SUBSCRIBE pastry/orders");
Using contract-testing techniques on Asynchronous endpoints may require a different style of interacting with the Microcks container. For example, you may need to:
- Start the test making Microcks listen to the target async endpoint,
- Activate your System Under Tests so that it produces an event,
- Finalize the Microcks tests and actually ensure you received one or many well-formed events.
For that the MicrocksContainer
now provides a TestEndpointAsync(TestRequest request)
method that actually returns a Task<TestResult>
.
Once invoked, you may trigger your application events and then await
the future result to assert like this:
// Start the test, making Microcks listen the endpoint provided in testRequest
Task<TestResult> testResultFuture = ensemble.MicrocksContainer.TestEndpointAsync(testRequest);
// Here below: activate your app to make it produce events on this endpoint.
// myapp.InvokeBusinessMethodThatTriggerEvents();
// Now retrieve the final test result and assert.
TestResult testResult = await testResultFuture;
testResult.IsSuccess.Should().BeTrue();