feat: Add KAFKA mocking

.github/workflows/cicd.yml

@@ -60,6 +60,7 @@ jobs:
     uses: ./.github/workflows/steps.publish-test-reporter.yml
     with:
       runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.head.repo.full_name == github.repository && github.event_name == 'pull_request' }}
     secrets: inherit
 
   nuget_publish:

.github/workflows/steps.dotnet-build-test.yml

@@ -55,13 +55,16 @@ jobs:
       run: dotnet tool install --global dotnet-sonarscanner
 
     - name: 🔧 Restore .NET Tools
-      run: dotnet tool restore  
-      
+      run: dotnet tool restore
+
     - name: 🔧 Restore dependencies
       run: dotnet restore
 
     - name: 🔍 Start SonarQube Analysis
-      if: ${{ inputs.use-sonarcloud == true }}
+      # Only run SonarCloud analysis only for the original repository and not for forks (either on push or PR from the same repo)
+      if: ${{ inputs.use-sonarcloud == true &&
+          ( github.repository == 'microcks/microcks-testcontainers-dotnet') &&
+          ( github.event_name != 'pull_request' || ( github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') ) }}
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
@@ -99,7 +102,11 @@ jobs:
       shell: pwsh
 
     - name: Stop SonarQube Analysis
-      if: ${{ inputs.use-sonarcloud == true && (success() || steps.test-with-coverage.conclusion == 'failure') }}
+      # Only run SonarCloud analysis only for the original repository and not for forks (either on push or PR from the same repo)
+      if: ${{ inputs.use-sonarcloud == true &&
+          ( success() || steps.test-with-coverage.conclusion == 'failure' ) &&
+          ( github.repository == 'microcks/microcks-testcontainers-dotnet' ) &&
+          ( github.event_name != 'pull_request' || ( github.event.pull_request.head.repo.full_name == github.repository ) ) }}
       id: sonar
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -395,6 +395,7 @@ FodyWeavers.xsd
 *.msix
 *.msm
 *.msp
+*.sln.iml
 
 # JetBrains Rider
-*.sln.iml
+.idea

README.md

@@ -66,7 +66,7 @@ await container.StartAsync();
 
 ### Import content in Microcks
 
-To use Microcks mocks or contract-testing features, you first need to import OpenAPI, Postman Collection, GraphQL or gRPC artifacts. 
+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](https://microcks.io/documentation/using/importers/#multi-artifacts-support) for details.
 
 You can do it before starting the container using simple paths:
@@ -97,7 +97,7 @@ await container.StartAsync();
 
 ### Using mock endpoints for your dependencies
 
-During your test setup, you'd probably need to retrieve mock endpoints provided by Microcks containers to 
+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:
 
 ```csharp
@@ -141,3 +141,69 @@ public async Task testOpenAPIContract()
 ```
 
 The `TestResult` gives you access to all details regarding success of failure on different test cases.
+
+### Advanced features with MicrocksContainersEnsemble
+
+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](https://medium.com/@lbroudoux/different-levels-of-api-contract-testing-with-microcks-ccc0847f8c97)
+in the Inner Loop with Testcontainers!
+
+A `MicrocksContainersEnsemble` presents the same methods as a `MicrocksContainer`.
+You can create and build an ensemble that way:
+
+```csharp
+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:
+
+```csharp
+MicrocksContainer microcks = ensemble.MicrocksContainer;
+microcks.ImportAsMainArtifact(...);
+```
+##### Using mock endpoints for your dependencies
+
+Once started, the `ensemble.AsyncMinionContainer` provides methods for retrieving mock endpoint names for the different
+supported protocols (Kafka only at the moment).
+
+```csharp
+string kafkaTopic = ensemble.AsyncMinionContainer
+    .GetKafkaMockTopic("Pastry orders API", "0.1.0", "SUBSCRIBE pastry/orders");
+```
+##### Launching new contract-tests
+
+Using contract-testing techniques on Asynchronous endpoints may require a different style of interacting with the Microcks
+container. For example, you may need to:
+1. Start the test making Microcks listen to the target async endpoint,
+2. Activate your System Under Tests so that it produces an event,
+3. 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:
+
+```csharp
+// 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();
+```

microcks-testcontainers-dotnet.sln

@@ -7,6 +7,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 	ProjectSection(SolutionItems) = preProject
 		.editorconfig = .editorconfig
 		global.json = global.json
+		README.md = README.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{6B414F17-C857-4B37-B48F-4913F7E083CD}"

src/Microcks.Testcontainers/Connection/KafkaConnection.cs

@@ -0,0 +1,38 @@
+//
+// Copyright The Microcks Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//
+
+namespace Microcks.Testcontainers.Connection;
+
+/// <summary>
+/// Represents a connection to a Kafka broker.
+/// </summary>
+public class KafkaConnection
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="KafkaConnection"/> class with the specified bootstrap servers.
+    /// </summary>
+    /// <param name="bootstrapServers">The Kafka bootstrap servers.</param>
+    public KafkaConnection(string bootstrapServers)
+    {
+        this.BootstrapServers = bootstrapServers;
+    }
+
+    /// <summary>
+    /// Gets the Kafka bootstrap servers.
+    /// </summary>
+    public string BootstrapServers { get; }
+}

src/Microcks.Testcontainers/Microcks.Testcontainers.csproj

@@ -5,5 +5,6 @@
     </PropertyGroup>
     <ItemGroup>
 		<PackageReference Include="Testcontainers" Version="4.0.0" />
+        <PackageReference Include="System.Net.Http.Json" Version="8.0.1" />
     </ItemGroup>
-</Project>
+</Project>

src/Microcks.Testcontainers/MicrocksAsyncMinionBuilder.cs

@@ -0,0 +1,117 @@
+//
+// Copyright The Microcks Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//
+
+
+using DotNet.Testcontainers.Networks;
+using Microcks.Testcontainers.Connection;
+
+namespace Microcks.Testcontainers;
+
+/// <inheritdoc cref="ContainerBuilder{TBuilderEntity, TContainerEntity, TConfigurationEntity}" />
+public sealed class MicrocksAsyncMinionBuilder
+    : ContainerBuilder<MicrocksAsyncMinionBuilder, MicrocksAsyncMinionContainer, MicrocksAsyncMinionConfiguration>
+{
+    /// <summary>
+    /// The default HTTP port for the Microcks async minion.
+    /// </summary>
+    public const int MicrocksAsyncMinionHttpPort = 8081;
+
+    private const string MicrocksAsyncMinionFullImageName = "quay.io/microcks/microcks-uber-async-minion";
+
+    private readonly HashSet<string> _extraProtocols = [];
+    private readonly INetwork _network;
+
+    /// <inheritdoc />
+    protected override MicrocksAsyncMinionConfiguration DockerResourceConfiguration { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionBuilder"/> class with the specified network.
+    /// </summary>
+    /// <param name="network">The network to be used by the Microcks async minion container.</param>
+    public MicrocksAsyncMinionBuilder(INetwork network)
+        : this(new MicrocksAsyncMinionConfiguration())
+    {
+        this._network = network;
+        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionBuilder"/> class with the specified resource configuration.
+    /// </summary>
+    /// <param name="resourceConfiguration">The resource configuration for the Microcks async minion container.</param>
+    private MicrocksAsyncMinionBuilder(MicrocksAsyncMinionConfiguration resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        DockerResourceConfiguration = resourceConfiguration;
+    }
+
+    /// <inheritdoc />
+    public override MicrocksAsyncMinionContainer Build()
+    {
+        Validate();
+
+        return new MicrocksAsyncMinionContainer(DockerResourceConfiguration);
+    }
+
+    /// <inheritdoc />
+    protected override MicrocksAsyncMinionBuilder Init()
+    {
+        return base.Init()
+            .WithImage(MicrocksAsyncMinionFullImageName)
+            .WithNetwork(this._network)
+            .WithNetworkAliases("microcks-async-minion")
+            .WithEnvironment("MICROCKS_HOST_PORT", "microcks:" + MicrocksBuilder.MicrocksHttpPort)
+            .WithExposedPort(MicrocksAsyncMinionHttpPort)
+            .WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged(".*Profile prod activated\\..*"));
+    }
+
+    /// <inheritdoc />
+    protected override MicrocksAsyncMinionBuilder Clone(IResourceConfiguration<CreateContainerParameters> resourceConfiguration)
+    {
+        return Merge(DockerResourceConfiguration, new MicrocksAsyncMinionConfiguration(resourceConfiguration));
+    }
+
+    /// <inheritdoc />
+    protected override MicrocksAsyncMinionBuilder Clone(IContainerConfiguration resourceConfiguration)
+    {
+        return Merge(DockerResourceConfiguration, new MicrocksAsyncMinionConfiguration(resourceConfiguration));
+    }
+
+    /// <inheritdoc />
+    protected override MicrocksAsyncMinionBuilder Merge(MicrocksAsyncMinionConfiguration oldValue, MicrocksAsyncMinionConfiguration newValue)
+    {
+        return new MicrocksAsyncMinionBuilder(new MicrocksAsyncMinionConfiguration(oldValue, newValue));
+    }
+
+
+    /// <summary>
+    /// Configures the MicrocksAsyncMinionBuilder to use a Kafka connection.
+    /// </summary>
+    /// <param name="kafkaConnection">The Kafka connection details.</param>
+    /// <returns>The updated MicrocksAsyncMinionBuilder instance.</returns>
+    public MicrocksAsyncMinionBuilder WithKafkaConnection(KafkaConnection kafkaConnection)
+    {
+        _extraProtocols.Add("KAFKA");
+        var environments = new Dictionary<string, string>
+        {
+            { "ASYNC_PROTOCOLS", $",{string.Join(",", _extraProtocols)}" },
+            { "KAFKA_BOOTSTRAP_SERVER", kafkaConnection.BootstrapServers },
+        };
+
+        return Merge(DockerResourceConfiguration, new MicrocksAsyncMinionConfiguration(new ContainerConfiguration(environments: environments)));
+    }
+}

src/Microcks.Testcontainers/MicrocksAsyncMinionConfiguration.cs

@@ -0,0 +1,67 @@
+//
+// Copyright The Microcks Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0 
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//
+
+namespace Microcks.Testcontainers;
+
+/// <inheritdoc cref="ContainerConfiguration" />
+public sealed class MicrocksAsyncMinionConfiguration : ContainerConfiguration
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionConfiguration" /> class.
+    /// </summary>
+    /// <param name="config">The Microcks config.</param>
+    public MicrocksAsyncMinionConfiguration(object config = null)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public MicrocksAsyncMinionConfiguration(IResourceConfiguration<CreateContainerParameters> resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public MicrocksAsyncMinionConfiguration(IContainerConfiguration resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public MicrocksAsyncMinionConfiguration(MicrocksAsyncMinionConfiguration resourceConfiguration)
+        : this(new MicrocksAsyncMinionConfiguration(), resourceConfiguration)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MicrocksAsyncMinionConfiguration" /> class.
+    /// </summary>
+    /// <param name="oldValue">The old Docker resource configuration.</param>
+    /// <param name="newValue">The new Docker resource configuration.</param>
+    public MicrocksAsyncMinionConfiguration(MicrocksAsyncMinionConfiguration oldValue, MicrocksAsyncMinionConfiguration newValue)
+        : base(oldValue, newValue)
+    {
+    }
+}