{"id":20915104,"url":"https://github.com/microcks/microcks-quarkus","last_synced_at":"2025-05-13T10:32:33.130Z","repository":{"id":187210678,"uuid":"676505154","full_name":"microcks/microcks-quarkus","owner":"microcks","description":"Quarkus extension that enables embedding Microcks as a DevService managing mocks for dependencies and contract-testing your API endpoints","archived":false,"fork":false,"pushed_at":"2024-10-18T12:33:47.000Z","size":405,"stargazers_count":16,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-30T05:42:58.058Z","etag":null,"topics":["api","contract-testing","devservices","java","microcks","microservices","mocking","quarkus"],"latest_commit_sha":null,"homepage":"https://microcks.io","language":"Java","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":"2023-08-09T10:57:03.000Z","updated_at":"2024-10-21T03:45:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"82ed9109-6c2c-4b58-9962-98941f88ab2b","html_url":"https://github.com/microcks/microcks-quarkus","commit_stats":{"total_commits":94,"total_committers":5,"mean_commits":18.8,"dds":"0.15957446808510634","last_synced_commit":"38faf0e1ddadba8dd298fe5555b3bec840f8fcf3"},"previous_names":["microcks/microcks-quarkus"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-quarkus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-quarkus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-quarkus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microcks%2Fmicrocks-quarkus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microcks","download_url":"https://codeload.github.com/microcks/microcks-quarkus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225206217,"owners_count":17438064,"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","devservices","java","microcks","microservices","mocking","quarkus"],"created_at":"2024-11-18T16:13:02.101Z","updated_at":"2025-05-13T10:32:33.113Z","avatar_url":"https://github.com/microcks.png","language":"Java","funding_links":["https://github.com/sponsors/microcks","https://opencollective.com/microcks"],"categories":[],"sub_categories":[],"readme":"# Microcks Quarkus\n\nQuarkus extension that enables embedding Microcks as a Dev Service managing mocks for dependencies and contract-testing your API endpoints\n\nWant to see this extension in action? Check out our [sample application](https://github.com/microcks/microcks-quarkus-demo). 🚀\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/microcks/microcks-quarkus/build-verify.yml?logo=github\u0026style=for-the-badge)](https://github.com/microcks/microcks-quarkus/actions)\n[![Version](https://img.shields.io/maven-central/v/io.github.microcks.quarkus/quarkus-microcks?color=blue\u0026style=for-the-badge)]((https://search.maven.org/artifact/io.github.microcks.quarkus/quarkus-microcks-parent))\n[![License](https://img.shields.io/github/license/microcks/microcks-quarkus?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.7`.\n\nCurrent development version is `0.2.8-SNAPSHOT`.\n\n#### Sonarcloud Quality metrics\n\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=code_smells)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=microcks_microcks-quarkus\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=microcks_microcks-quarkus)\n\n#### Fossa license and security scans\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-quarkus.svg?type=shield\u0026issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-quarkus?ref=badge_shield\u0026issueType=license)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-quarkus.svg?type=shield\u0026issueType=security)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-quarkus?ref=badge_shield\u0026issueType=security)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-quarkus.svg?type=small)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmicrocks%2Fmicrocks-quarkus?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\n## How to use it?\n\n### Include it into your project dependencies\n\nIf you're using Maven:\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.microcks.quarkus\u003c/groupId\u003e\n  \u003cartifactId\u003equarkus-microcks\u003c/artifactId\u003e\n  \u003cversion\u003e0.2.6\u003c/version\u003e\n  \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\nDon't forget to specify the `provided` scope as the extension is just for easing your life during development mode and tests 👻\n\n### Configuring the Dev Services\n\nBy default, and if global Dev Services are not disabled, Microcks Dev Service will run on next `mvn quarkus:dev`, launching \na Microcks Testcontainer to handle your mock dependencies.  You can obviously fine-tune the configuration using properties \nin `application.properties`. Microcks related properties have the `quarkus.microcks` prefix.\n\nYou can explicitly disable Microcks Dev Service if you want save some resources at some point:\n\n```properties\nquarkus.microcks.devservices.enabled=false\n```\n\nThe local URL exposed by the Microcks container Http port is automatically stored into the `quarkus.microcks.default.http` property.\nMicrocks container also exposes a gRPC URL for gRPC services, it is store into the `quarkus.microcks.default.grpc` property.\nFor convenient usage of the Quarkus gRPC client or other libraries, we also provide `quarkus.microcks.default.http.host`, \n`quarkus.microcks.default.http.port`, `quarkus.microcks.default.grpc.host` and `quarkus.microcks.default.grpc.port` properties.\n\nExposed URL is visible in the Quarkus startup logs:\n\n```shell\nListening for transport dt_socket at address: 5005\n2023-08-09 12:27:22,649 INFO  [io.git.mic.qua.dep.DevServicesMicrocksProcessor] (build-31) The 'default' microcks container is ready on http://localhost:65719\n__  ____  __  _____   ___  __ ____  ______ \n --/ __ \\/ / / / _ | / _ \\/ //_/ / / / __/ \n -/ /_/ / /_/ / __ |/ , _/ ,\u003c / /_/ /\\ \\   \n--\\___\\_\\____/_/ |_/_/|_/_/|_|\\____/___/   \n2023-08-09 12:27:23,169 INFO  [io.quarkus] (Quarkus Main Thread) order-service 0.1.0-SNAPSHOT on JVM (powered by Quarkus 3.2.3.Final) started in 4.935s. Listening on: http://localhost:8080\n2023-08-09 12:27:23,170 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.\n2023-08-09 12:27:23,170 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, microcks, rest-client-reactive, rest-client-reactive-jackson, resteasy-reactive, resteasy-reactive-jackson, smallrye-context-propagation, vertx]\n```\n\nYou can also access to Microcks UI using the Quarkus DevUI on http://localhost:8080/q/dev-ui:\n\n![Microcks card](./assets/devui-integration-card.png)\n\n![Microcks UI](./assets/devui-integration-microcks.png)\n\n### Import content in Microcks\n\nTo use Microcks mocks or contract-testing features, you first need to import OpenAPI, Postman Collection, GraphQL, gRPC, HAR or\nSoapUI artifacts. Artifacts can be imported as main/primary ones or as secondary ones. \nSee [Multi-artifacts support](https://microcks.io/documentation/using/importers/#multi-artifacts-support) for details. \nImport is done automatically at container startup depending on your configuration.\n\nBy default, Microcks Dev Service automatically discover and load artifacts found in main resources folders (typically `src/main/resources`)\nand test resources folders (typically `src/test/resources`).\nIn order to find the correct artifacts and make difference between primary and secondary ones, the Dev Service relies on naming conventions:\n* All the files named `*-openapi.yml`, `*-openapi.yaml`, `*-openapi.json` will be imported as **primary** artifacts,\n* All the files named `*-asyncapi.yml`, `*-asyncapi.yaml`, `*-asyncapi.json` will be imported as **primary** artifacts,\n* All the files named `*.proto`, `*.graphql`, `*-soapui-project.xml` will also be imported as **primary** artifacts,\n* All the files named `*postman-collection.json`, `*postman_collection.json` will be imported as **secondary** artifacts\n* All the files named `*.har` will be imported as **secondary** artifacts,\n* All the files named `*-metadata.yml`, `*-metadata.yaml` will also be imported as **secondary** artifacts,\n* All the files named `*-examples.yml`, `*-examples.yaml` will also be imported as **secondary** artifacts.\n\nIf you want/need a fine control on what's loaded in container, you may use the `artifact.primaries` and `artifact.secondaries` \nconfiguration properties for that. They are comma-separated lists of paths to your OpenAPI, Postman, GraphQL, gRPC, HAR, or SoapUI artifacts.\n\n```properties\nquarkus.microcks.devservices.artifacts.primaries=target/classes/order-service-openapi.yaml,target/test-classes/third-parties/apipastries-openapi.yaml\nquarkus.microcks.devservices.artifacts.secondaries=target/test-classes/third-parties/apipastries-postman-collection.json\n```\n\nStarting with version `0.2.3`, you can also use the `remote-artifact.primaries` and `remote-artifact.secondaries` configuration\nproperties to specify URLs to load remote artifacts within the Microcks Dev Service:\n\n```properties\nquarkus.microcks.devservices.remote-artifacts.primaries=https://raw.githubusercontent.com/microcks/microcks/master/samples/films.graphql\nquarkus.microcks.devservices.remote-artifacts.secondaries=https://raw.githubusercontent.com/microcks/microcks/master/samples/films-postman.json\n```\n\n### Using mock endpoints for your dependencies\n\nAt development time or during your unit tests setup, you'd probably need to configure mock endpoints provided by Microcks \ncontainers to set up your base API url calls. For that, you have to configure the host exposition port and change URLs in config:\n\n```properties\n# Specify here the Mock URL provided by microcks devservices, referencing the quarkus.microcks.default.http\nquarkus.rest-client.\"org.acme.order.client.PastryAPIClient\".url=${quarkus.microcks.default.http}/rest/API+Pastries/0.0.1\n```\n\n### Launching new contract-tests\n\nIf you want to ensure that your application under test is conform to an OpenAPI contract (or many contracts),\nyou can launch a Microcks contract/conformance test using the local server port you're actually running. Microcks container\nis automatically configured for being able to reach your local application on the configured or default `quarkus.http.test-port`:\n\n```java\n@ConfigProperty(name= \"quarkus.http.test-port\")\nint quarkusHttpPort;\n\n@ConfigProperty(name= \"quarkus.microcks.default.http\")\nString microcksContainerUrl;\n\n@Test\npublic void testOpenAPIContract() throws Exception {\n  // Ask for an Open API conformance to be launched.\n  TestRequest testRequest = new TestRequest.Builder()\n      .serviceId(\"Order Service API:0.1.0\")\n      .runnerType(TestRunnerType.OPEN_API_SCHEMA.name())\n      .testEndpoint(\"http://host.testcontainers.internal:\" + quarkusHttpPort + \"/api\")\n      .build();\n\n  TestResult testResult = MicrocksContainer.testEndpoint(microcksContainerUrl, testRequest);\n  assertTrue(testResult.isSuccess());\n```\n\nThe `TestResult` gives you access to all details regarding success of failure on different test cases.\n\nA comprehensive Quarkus demo application illustrating both usages is available here: [quarkus-order-service](https://github.com/microcks/api-lifecycle/tree/master/shift-left-demo/quarkus-order-service).\n\n### Configure your Microcks image\n\nBy default, Microcks Dev Service will use the `quay.io/microcks/microcks-uber:latest` image that is the latest stable one.\nHowever, you can specify a compatible image of your choice using the following property:\n\n```properties\n# Specify here the Microcks-uber image you want to use.\nquarkus.microcks.devservices.image-name=quay.io/microcks/microcks-uber:nightly\n```\n\n### Advanced features with Async and Postman\n\nStarting with version `0.2.0` the Microcks Dev Service also integrates Async API/Event Driven Architecture features and also\nallow you to implement\n[Different levels of API contract testing](https://medium.com/@lbroudoux/different-levels-of-api-contract-testing-with-microcks-ccc0847f8c97)\nin your Inner Loop!\n\nBased on the artifacts the Dev Service discovered or forced with configuration properties, the Dev Service may start additional containers\n(`microcks-async-minion` and `microcks-postman-runtime`) that you may use for contract-testing. The group of containers has been\ncalled an `ensemble`:\n\n```properties\n# Force the enablement/deactivation of Async API support.\nquarkus.microcks.devservices.ensemble.async-enabled=true\n# Customize the Microcks-uber-async-minion image you want to use.\nquarkus.microcks.devservices.ensemble.async-image-name=quay.io/microcks/microcks-uber-async-minion:nightly\n\n# Force the enablement/deactivation of Postman runtime support.\nquarkus.microcks.devservices.ensemble.postman-enabled=true\n# Customize the Microcks-postman-runtime image you want to use.\nquarkus.microcks.devservices.ensemble.postman-image-name=quay.io/microcks/microcks-postman-runtime:nightly\n```\n\n#### Postman contract-testing\n\nYou can execute a `POSTMAN` test using an ensemble that way:\n\n```java\n// Ask for a Postman Collection conformance to be launched.\nTestRequest testRequest = new TestRequest.Builder()\n      .serviceId(\"Order Service API:0.1.0\")\n      .runnerType(TestRunnerType.POSTMAN.name())\n      .testEndpoint(\"http://host.testcontainers.internal:\" + quarkusHttpPort + \"/api\")\n      .build();\n\nTestResult testResult = MicrocksContainer.testEndpoint(microcksContainerUrl, testRequest);\n```\n\n#### Asynchronous API support\n\nAsynchronous API in the Microcks Dev Service only supports [Apache Kafka](https://kafka.apache.org) at time of writing.\nAdditional bindings may be added in the future ; please tell us what you need!\n\n##### Using mock endpoints for your dependencies\n\nKafka topics for publishing/receiving mock messages are directly created by Microcks on the bound Kafka broker found in the\nrunning Dev Services list. These topics are named from the API name + API version + operation.\n\nFor example: when discovering an AsyncAPI named `Order Events API` with version `0.1.0` and operation `orders-reviewed` Microcks\nwill create and manage a `OrderEventsAPI-0.1.0-orders-reviewed` topic. You can reuse this value into your Kafka/Reactive Messaging\nclient configuration:\n\n```properties\n# Specify here the Mock Topic provided by microcks devservices, following the naming convention.\nmp.messaging.incoming.orders-reviewed.connector=smallrye-kafka\nmp.messaging.incoming.orders-reviewed.topic=OrderEventsAPI-0.1.0-orders-reviewed\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(String microcksContainerUrl, TestRequest request)` method that actually returns a `CompletableFuture`.\nOnce invoked, you may trigger your application events and then `get()` the future result to assert like this:\n\n```java\n// Start the test, making Microcks listen the endpoint provided in testRequest\nCompletableFuture\u003cTestResult\u003e testRequestFuture = MicrocksContainer.testEndpointAsync(microcksContainerUrl, kafkaTest);\n\n// Invoke the application to create an order.\nOrder createdOrder = service.placeOrder(info);\n\n// You may check additional stuff on createdOrder...\n\n// Get the Microcks test result.\nTestResult testResult = testRequestFuture.get();\nassertTrue(testResult.isSuccess());\n```\n\n##### Retrieving DevServices broker information\n\nWhen running your AsyncAPI tests using Quarkus Dev Services for providing brokers, knowing the broker URL that \nis addressable by Microcks is not an easy thing.\n\nTo ease this, you can inject the Kafka broker URL and port using the `@InjectKafkaInternalEndpoint` annotation. \nThis annotation  as well as the `MicrocksTestCompanion` Quarkus test resource are provided by the Microcks Quarkus \nextension within the `quarkus-microcks-test` module:\n\n```java\n[..]\nimport io.github.microcks.quarkus.test.InjectKafkaInternalEndpoint;\nimport io.github.microcks.quarkus.test.MicrocksTestCompanion;\n\n@QuarkusTest\n@QuarkusTestResource(MicrocksTestCompanion.class)\npublic class OrderServiceTests extends BaseTest {\n\n   @Inject\n   OrderService service;\n\n   @InjectKafkaInternalEndpoint\n   String kafkaInternalEndpoint;\n\n   @Test\n   void testEventIsPublishedWhenOrderIsCreated() {\n      // Prepare a Microcks test.\n      TestRequest kafkaTest = new TestRequest.Builder()\n            .serviceId(\"Order Events API:0.1.0\")\n            .filteredOperations(List.of(\"SUBSCRIBE orders-created\"))\n            .runnerType(TestRunnerType.ASYNC_API_SCHEMA.name())\n            .testEndpoint(\"kafka://%s/orders-created\".formatted(kafkaInternalEndpoint))\n            .timeout(5000L)\n            .build();\n      [..]\n   }\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrocks%2Fmicrocks-quarkus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrocks%2Fmicrocks-quarkus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrocks%2Fmicrocks-quarkus/lists"}