{"id":20915076,"url":"https://github.com/microcks/microcks-testcontainers-dotnet","last_synced_at":"2025-04-11T09:14:49.483Z","repository":{"id":263115305,"uuid":"885267459","full_name":"microcks/microcks-testcontainers-dotnet","owner":"microcks","description":".NET lib for Testcontainers that enables embedding Microcks into your unit tests with lightweight, throwaway instance thanks to containers.","archived":false,"fork":false,"pushed_at":"2025-04-06T17:20:42.000Z","size":183,"stargazers_count":8,"open_issues_count":6,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-06T17:37:56.131Z","etag":null,"topics":["api","contract-testing","csharp","dotnet","microcks","mocking"],"latest_commit_sha":null,"homepage":"https://microcks.io","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microcks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY-INSIGHTS.yml","support":null,"governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"microcks","patreon":null,"open_collective":"microcks","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2024-11-08T09:18:22.000Z","updated_at":"2025-04-06T17:20:40.000Z","dependencies_parsed_at":"2024-11-16T10:17:21.349Z","dependency_job_id":"6ec780f5-2d93-4d64-b533-acc404b95446","html_url":"https://github.com/microcks/microcks-testcontainers-dotnet","commit_stats":{"total_commits":28,"total_committers":3,"mean_commits":9.333333333333334,"dds":0.4285714285714286,"last_synced_commit":"175a6174334b732a252530c1ae2e95a457bd9ae4"},"previous_names":["microcks/microcks-testcontainers-dotnet"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-testcontainers-dotnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-testcontainers-dotnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-testcontainers-dotnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-testcontainers-dotnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microcks","download_url":"https://codeload.github.com/microcks/microcks-testcontainers-dotnet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247631833,"owners_count":20970069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","contract-testing","csharp","dotnet","microcks","mocking"],"created_at":"2024-11-18T16:12:54.685Z","updated_at":"2025-04-11T09:14:49.474Z","avatar_url":"https://github.com/microcks.png","language":"C#","funding_links":["https://github.com/sponsors/microcks","https://opencollective.com/microcks"],"categories":[],"sub_categories":[],"readme":"# Microcks Testcontainers .NET\n\n.NET library for Testcontainers that enables embedding Microcks into your unit tests with lightweight, throwaway instance thanks to containers.\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/microcks/microcks-testcontainers-dotnet/cicd.yml?logo=github\u0026style=for-the-badge)](https://github.com/microcks/microcks-testcontainers-dotnet/actions)\n[![Version](https://img.shields.io/nuget/v/Microcks.Testcontainers?color=blue\u0026style=for-the-badge)](https://www.nuget.org/packages/Microcks.Testcontainers)\n[![License](https://img.shields.io/github/license/microcks/microcks-testcontainers-java?style=for-the-badge\u0026logo=apache)](https://www.apache.org/licenses/LICENSE-2.0)\n[![Project Chat](https://img.shields.io/badge/discord-microcks-pink.svg?color=7289da\u0026style=for-the-badge\u0026logo=discord)](https://microcks.io/discord-invite/)\n[![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/microcks-uber-image\u0026style=for-the-badge)](https://artifacthub.io/packages/search?repo=microcks-uber-image)\n[![CNCF Landscape](https://img.shields.io/badge/CNCF%20Landscape-5699C6?style=for-the-badge\u0026logo=cncf)](https://landscape.cncf.io/?item=app-definition-and-development--application-definition-image-build--microcks)\n\n## Build Status\n\nLatest released version is `0.2.0`.\n\nCurrent development version is `0.3.0`.\n\n#### Sonarcloud Quality metrics\n\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=code_smells)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-testcontainers-dotnet)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-testcontainers-dotnet)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-testcontainers-dotnet)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-testcontainers-dotnet)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-testcontainers-dotnet)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=microcks_microcks)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-testcontainers-dotnet\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-testcontainers-dotnet)\n\n#### Fossa license and security scans\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet.svg?type=shield\u0026issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet?ref=badge_shield\u0026issueType=license)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet.svg?type=shield\u0026issueType=security)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet?ref=badge_shield\u0026issueType=security)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet.svg?type=small)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet?ref=badge_small)\n\n#### OpenSSF best practices on Microcks core\n\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/7513/badge)](https://bestpractices.coreinfrastructure.org/projects/7513)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/microcks/microcks/badge)](https://securityscorecards.dev/viewer/?uri=github.com/microcks/microcks)\n\n## Community\n\n* [Documentation](https://microcks.io/documentation/tutorials/getting-started/)\n* [Microcks Community](https://github.com/microcks/community) and community meeting\n* Join us on [Discord](https://microcks.io/discord-invite/), on [GitHub Discussions](https://github.com/orgs/microcks/discussions) or [CNCF Slack #microcks channel](https://cloud-native.slack.com/archives/C05BYHW1TNJ)\n\nTo get involved with our community, please make sure you are familiar with the project's [Code of Conduct](./CODE_OF_CONDUCT.md).\n\n## How to use it?\n\n### Include it into your project dependencies\n\n```\ndotnet add package Microcks.Testcontainers --version 0.2.0\n```\n\n### Startup the container\n\nYou just have to specify the container image you'd like to use. This library requires a Microcks `uber` distribution (with no MongoDB dependency).\n\n\n```csharp\nMicrocksContainer container = new MicrocksBuilder()\n\t.WithImage(\"quay.io/microcks/microcks-uber:1.11.0\")\n\t.Build();\nawait container.StartAsync();\n```\n\n### Import content in Microcks\n\nTo use Microcks mocks or contract-testing features, you first need to import OpenAPI, Postman Collection, GraphQL or gRPC artifacts.\nArtifacts 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.\n\nYou can do it before starting the container using simple paths:\n\n```csharp\nMicrocksContainer container = new MicrocksBuilder()\n\t  .WithMainArtifacts(\"apipastries-openapi.yaml\")\n\t  .WithSecondaryArtifacts(\"apipastries-postman-collection.json\")\n\t  .Build();\nawait container.StartAsync();\n```\n\nor once the container started using `File` arguments:\n\n```csharp\ncontainer.ImportAsMainArtifact(\"apipastries-openapi.yaml\");\ncontainer.ImportAsSecondaryArtifact(\"apipastries-postman-collection.json\");\n```\n\nYou can also import full [repository snapshots](https://microcks.io/documentation/administrating/snapshots/) at once:\n\n```csharp\nMicrocksContainer container = new MicrocksBuilder()\n      .WithSnapshots(\"microcks-repository.json\")\n\t  .Build();\nawait container.StartAsync();\n```\n\n### Using mock endpoints for your dependencies\n\nDuring your test setup, you'd probably need to retrieve mock endpoints provided by Microcks containers to\nsetup your base API url calls. You can do it like this:\n\n```csharp\nvar baseApiUrl = container.GetRestMockEndpoint(\"API Pastries\", \"0.0.1\");\n```\n\nThe container provides methods for different supported API styles/protocols (Soap, GraphQL, gRPC,...).\n\nThe container also provides `GetHttpEndpoint()` for raw access to those API endpoints.\n\n### Launching new contract-tests\n\nIf you want to ensure that your application under test is conformant to an OpenAPI contract (or other type of contract),\nyou can launch a Microcks contract/conformance test using the local server port you're actually running.\n\n```csharp\nprivate int port;\n\npublic async Task InitializeAsync()\n{\n\tcontainer = new MicrocksBuilder()\n\t\t.WithExposedPort(port)\n\t\t.Build();\n\tawait container.StartAsync();\n}\n\n[Fact]\npublic async Task testOpenAPIContract()\n{\n\tvar testRequest = new TestRequest\n\t{\n\t\tServiceId = \"API Pastries:0.0.1\",\n\t\tRunnerType = TestRunnerType.OPEN_API_SCHEMA,\n\t\tTestEndpoint = $\"http://host.testcontainers.internal:{port}\",\n\t\tTimeout = TimeSpan.FromMilliseconds(2000)\n\t};\n\tTestResult testResult = await container.TestEndpointAsync(testRequest);\n\n\ttestResult.Success.Should().BeTrue();\n}\n```\n\nThe `TestResult` gives you access to all details regarding success of failure on different test cases.\n\n### Advanced features with MicrocksContainersEnsemble\n\nThe `MicrocksContainer` referenced above supports essential features of Microcks provided by the main Microcks container.\nThe list of supported features is the following:\n\n* Mocking of REST APIs using different kinds of artifacts,\n* Contract-testing of REST APIs using `OPEN_API_SCHEMA` runner/strategy,\n* Mocking and contract-testing of SOAP WebServices,\n* Mocking and contract-testing of GraphQL APIs,\n* Mocking and contract-testing of gRPC APIs.\n\nTo support features like Asynchronous contract-testing, we introduced `MicrocksContainersEnsemble` that allows managing\nadditional Microcks services. `MicrocksContainersEnsemble` allow you to implement\n[Different levels of API contract testing](https://medium.com/@lbroudoux/different-levels-of-api-contract-testing-with-microcks-ccc0847f8c97)\nin the Inner Loop with Testcontainers!\n\nA `MicrocksContainersEnsemble` presents the same methods as a `MicrocksContainer`.\nYou can create and build an ensemble that way:\n\n```csharp\nMicrocksContainersEnsemble ensemble = new MicrocksContainerEnsemble(network, MicrocksImage)\n    .WithMainArtifacts(\"pastry-orders-asyncapi.yml\");\n\nensemble.StartAsync();\n```\n\nA `MicrocksContainer` is wrapped by an ensemble and is still available to import artifacts and execute test methods.\nYou have to access it using:\n\n```csharp\nMicrocksContainer microcks = ensemble.MicrocksContainer;\nmicrocks.ImportAsMainArtifact(...);\n```\n\nTo activate async features (WebSocket), you can use `WithAsyncFeature()` method.\n\n```csharp\nMicrocksContainersEnsemble ensemble = new MicrocksContainerEnsemble(network, MicrocksImage)\n    .WithMainArtifacts(\"pastry-orders-asyncapi.yml\")\n    .WithAsyncFeature();\n\nensemble.StartAsync();\n```\n\n#### Asynchronous API support\nAsynchronous API feature needs to be explicitly enabled as well.\nIn case you want to use it for mocking purposes,\nyou'll have to specify additional connection details to the broker of your choice.\n\nTo add a note indicating that it is not necessary to call `WithAsyncFeature()` when an additional method exists.\n\nSee an example below with connection to a Kafka broker:\n\n```csharp\nMicrocksContainersEnsemble ensemble = new MicrocksContainerEnsemble(network, MicrocksImage)\n    .WithMainArtifacts(\"pastry-orders-asyncapi.yml\")\n    .WithKafkaConnection(new KafkaConnection($\"kafka:19092\"));\n\nensemble.StartAsync();\n```\n\n##### Using mock endpoints for your dependencies\n\nOnce started, the `ensemble.AsyncMinionContainer` provides methods for retrieving mock endpoint names for the different\nsupported protocols (WebSocket, Kafka, etc. ...).\n\n```csharp\nstring kafkaTopic = ensemble.AsyncMinionContainer\n    .GetKafkaMockTopic(\"Pastry orders API\", \"0.1.0\", \"SUBSCRIBE pastry/orders\");\n```\n\n##### Launching new contract-tests\n\nUsing contract-testing techniques on Asynchronous endpoints may require a different style of interacting with the Microcks\ncontainer. For example, you may need to:\n1. Start the test making Microcks listen to the target async endpoint,\n2. Activate your System Under Tests so that it produces an event,\n3. Finalize the Microcks tests and actually ensure you received one or many well-formed events.\n\nFor that the `MicrocksContainer` now provides a `TestEndpointAsync(TestRequest request)` method that actually returns a `Task\u003cTestResult\u003e`.\nOnce invoked, you may trigger your application events and then `await` the future result to assert like this:\n\n```csharp\n// Start the test, making Microcks listen the endpoint provided in testRequest\nTask\u003cTestResult\u003e testResultFuture = ensemble.MicrocksContainer.TestEndpointAsync(testRequest);\n\n// Here below: activate your app to make it produce events on this endpoint.\n// myapp.InvokeBusinessMethodThatTriggerEvents();\n\n// Now retrieve the final test result and assert.\nTestResult testResult = await testResultFuture;\ntestResult.IsSuccess.Should().BeTrue();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrocks%2Fmicrocks-testcontainers-dotnet/lists"}