From 96fec0e797978aba61ea68c5fc81d0e02fd44152 Mon Sep 17 00:00:00 2001 From: caesarsage Date: Sun, 31 May 2026 04:27:17 +0100 Subject: [PATCH] docs: add community Python Testcontainers module Signed-off-by: caesarsage --- .../guides/usage/developing-testcontainers.md | 38 +++++++++++ .../references/testcontainers-modules.md | 63 +++++++++++++++++++ 2 files changed, 101 insertions(+) diff --git a/content/documentation/guides/usage/developing-testcontainers.md b/content/documentation/guides/usage/developing-testcontainers.md index 4013f1d9..2c96e664 100644 --- a/content/documentation/guides/usage/developing-testcontainers.md +++ b/content/documentation/guides/usage/developing-testcontainers.md @@ -19,6 +19,8 @@ As of today, we provide support for the following languages: * Golang - via a library distributed via our GitHub, * .NET - starting from .NET 6.0 to latest releases - via a library available on [Nuget](https://www.nuget.org/packages/Microcks.Testcontainers). +In addition, a **community-maintained module for Python** 🐍 is available β€” see the [Community modules](#5-community-modules) section below. + Let’s go 🧊 ## 1. Java support @@ -90,6 +92,42 @@ await container.StartAsync(); See our [microcks-testcontainers-dotnet repository](https://github.com/microcks/microcks-testcontainers-dotnet) for full details and our (incoming) full [demo application](https://github.com/microcks/microcks-testcontainers-dotnet-demo) +## 5. Community modules + +Beyond the officially maintained modules above, the community is actively working on bindings for additional languages. These modules are **not (yet) part of the official Microcks organization**, but they follow the same approach and may be promoted to official modules in the future as they mature. We're sharing them here to highlight the work and gather feedback β€” contributions and early adopters are very welcome! πŸ™Œ + +### Python support 🐍 + +A community-maintained Testcontainers module for Python is available as `microcks_testcontainers`. As it's not yet published on [PyPI](https://pypi.org), you can install it directly from GitHub: + +```bash +pip install git+https://github.com/Caesarsage/microcks-testcontainers-python.git +``` + +Like the other modules, it leverages our [*Uber* distribution](/documentation/explanations/deployment-options/#regular-vs-uber-distribution) and you can simply start Microcks that way: + +```python +from microcks_testcontainers import MicrocksContainer + +container = MicrocksContainer("quay.io/microcks/microcks-uber:1.13.0") +container.start() +``` + +It can also be used as a context manager to automatically manage the container lifecycle: + +```python +from microcks_testcontainers import MicrocksContainer + +with MicrocksContainer().with_main_artifacts(["my-api.yaml"]) as microcks: + endpoint = microcks.get_rest_mock_endpoint("My API", "1.0") + # Use the endpoint in your tests +``` + +Despite being a young project, this module already covers a broad feature set β€” REST/SOAP/GraphQL/gRPC mocking, conformance testing, secrets, OAuth2-secured endpoints and a Microcks *ensemble* with a Postman runtime and an Async Minion for Kafka, MQTT, AMQP, AWS SQS/SNS and Google PubSub. See the [Testcontainers Modules reference](/documentation/references/testcontainers-modules/#community-modules) for the detailed feature coverage and the [microcks-testcontainers-python repository](https://github.com/Caesarsage/microcks-testcontainers-python) for full details, as well as a full [demo application using Flask](https://github.com/Caesarsage/microcks-testcontainers-python-demo-flask) 🐍 + +This module is moving toward becoming an official one, and the best way to help is to **give it a try, ⭐ star the [repository](https://github.com/Caesarsage/microcks-testcontainers-python), open issues and contribute**! Feedback is highly appreciated β€” feel free to reach out on [Discord](/discord-invite/) too. πŸ™Œ + + ## Wrap-up Testcontainers + Microcks is a powerful combo for simplifying the write-up of robust unit or integration tests where the fixtures can be directly deduced from specifications. And the best thing is that this tooling is totally independent of your technology stack! You can use them for NodeJS, Go, Java, Ruby development, or whatever! diff --git a/content/documentation/references/testcontainers-modules.md b/content/documentation/references/testcontainers-modules.md index a6dbc38d..0c086644 100644 --- a/content/documentation/references/testcontainers-modules.md +++ b/content/documentation/references/testcontainers-modules.md @@ -11,6 +11,8 @@ weight: 7 As introduced in our [Developing with Testcontainers](/documentation/guides/usage/developing-testcontainers) guide, you can be embed Microcks into your unit tests with the help of [Testcontainers](https://testcontainers.com) librairies. We provide support for the following languages in dedicated Testcontainers modules: [Java](https://github.com/microcks/microcks-testcontainers-java), [NodeJS / Typescript](https://github.com/microcks/microcks-testcontainers-node), [Golang](https://github.com/microcks/microcks-testcontainers-go) and [.NET](https://github.com/microcks/microcks-testcontainers-dotnet). +In addition, a **community-maintained module for [Python](https://github.com/Caesarsage/microcks-testcontainers-python)** 🐍 is emerging with broad feature coverage. It's not yet part of the official Microcks organization, so it is tracked separately in the [Community modules](#community-modules) section below rather than in the matrices that follow. It may be promoted to an official module in the future as it matures. + We try to setup and manage a unified roadmap between modules but because they are maintained by different contributors, drifts between implementations may happen at some points. Our goal is obviously to make them consistent eventually. This page lists the implementation status of various features by the different modules on July 21st, 2025. It will be updated regularly. @@ -73,3 +75,64 @@ This sections lists the async protocols available on each language binding. | AWS SQS | βœ… | βœ… | βœ… | ❌ | | AWS SNS | βœ… | βœ… | βœ… | ❌ | | Google PubSub | βœ… | βœ… | βœ… | ❌ | + +## Community modules + +The modules listed in the matrices above are maintained within the official Microcks organization. The community is also building bindings for additional languages that are **not (yet) official** but may be promoted in the future as they mature. + +### Python 🐍 + +A community-maintained module is available at [Caesarsage/microcks-testcontainers-python](https://github.com/Caesarsage/microcks-testcontainers-python). It's not yet published on PyPI, but it already provides a remarkably complete feature set β€” including a Microcks ensemble (with Postman and Async Minion containers), secrets, OAuth2-secured endpoint testing and all asynchronous connection types except NATS. + +See the [Community modules](/documentation/guides/usage/developing-testcontainers/#5-community-modules) part of the *Developing with Testcontainers* guide for installation and usage. The feature coverage below was assessed from the module source on May 31st, 2026 β€” as it stabilizes, we intend to fold it into the matrices above. + +**Initialization** + +| Feature | Python | +| ----------------------- | ------ | +| Secret creation | βœ… | +| Snapshot restoration | βœ… | +| Local files (primary) | βœ… | +| Local files (secondary) | βœ… | +| Remote urls (primary) | βœ… | +| Remote urls (secondary) | βœ… | +| Remote urls with Secret | βœ… | +| Enable DEBUG log level | βœ… | + +**Mocking features** + +| Feature | Python | +| ----------------------- | ------ | +| REST endpoints | βœ… | +| Soap endpoints | βœ… | +| GraphQL endpoints | βœ… | +| gRPC endpoints | βœ… | +| Invocation verification | βœ… | +| Get invocation stats | βœ… | + +**Testing features** + +| Feature | Python | +| --------------------- | ------ | +| OpenAPI conformance | βœ… | +| Soap conformance | βœ… | +| GraphQL conformance | βœ… | +| gRPC conformance | βœ… | +| Postman conformance | βœ… | +| AsyncAPI conformance | βœ… | +| Get TestCase messages | βœ… | + +**Asynchronous protocols** + +| Protocol | Python | +| ------------------- | ------ | +| Kafka | βœ… | +| WebSocket | βœ… | +| MQTT | βœ… | +| RabbitMQ (AMQP 0.9) | βœ… | +| NATS | ❌ | +| AWS SQS | βœ… | +| AWS SNS | βœ… | +| Google PubSub | βœ… | + +This module is in active development β€” **trying it out, reporting issues, and starring the [repository](https://github.com/Caesarsage/microcks-testcontainers-python) ⭐** are all great ways to help it reach official-module status. Contributions are very welcome! πŸ™Œ