{"id":18875794,"url":"https://github.com/wiremock/wiremock-grpc-extension","last_synced_at":"2025-04-14T17:31:39.541Z","repository":{"id":196107599,"uuid":"694300421","full_name":"wiremock/wiremock-grpc-extension","owner":"wiremock","description":"WireMock Extension: gRPC mocking","archived":false,"fork":false,"pushed_at":"2024-11-06T20:12:01.000Z","size":300,"stargazers_count":15,"open_issues_count":18,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-06T21:23:25.960Z","etag":null,"topics":["api","grpc","grpc-gateway","grpc-server","hacktoberfest","wiremock","wiremock-extension"],"latest_commit_sha":null,"homepage":"https://wiremock.org/docs/grpc/","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/wiremock.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-20T18:09:53.000Z","updated_at":"2024-10-28T09:19:05.000Z","dependencies_parsed_at":"2023-12-12T09:24:59.445Z","dependency_job_id":"45751961-e29e-4ca9-a89c-9cccaef05f4e","html_url":"https://github.com/wiremock/wiremock-grpc-extension","commit_stats":null,"previous_names":["wiremock/wiremock-grpc-extension"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremock%2Fwiremock-grpc-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremock%2Fwiremock-grpc-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremock%2Fwiremock-grpc-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiremock%2Fwiremock-grpc-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wiremock","download_url":"https://codeload.github.com/wiremock/wiremock-grpc-extension/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223639348,"owners_count":17177816,"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","grpc","grpc-gateway","grpc-server","hacktoberfest","wiremock","wiremock-extension"],"created_at":"2024-11-08T06:09:10.033Z","updated_at":"2025-04-14T17:31:39.534Z","avatar_url":"https://github.com/wiremock.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ndescription: \u003e\n  WireMock extension for gRPC.\nog_image: solutions/grpc/wiremock_grpc_opengraph.png\nhero: solutions/grpc/header.png\n---\n\n# Mocking gRPC services\n\nThe [WireMock extension for gRPC](https://github.com/wiremock/wiremock-grpc-extension), compatible with WireMock 3.2.0+, supports mocking of gRPC services.\n\nTo set up the extension for use, you:\n\n- add the extension JAR dependency to your project.\n- create a root directory for WireMock e.g. `src/test/resources/wiremock` with a subdirectory under it, named `grpc`.\n- copy the descriptor files (*.dsc, *.desc) generated by `protoc` from your `.proto` files into the `grpc` subdirectory.\n\nFor details, see [Setup](setup) below.\n\nAt runtime, the extension:\n\n- scans for descriptor files (generated from the service's `.proto` files) in the `grpc` subdirectory of WireMock's root.\n- using the descriptor file, it converts incoming messages to JSON before passing them to WireMock's core stubbing system, which allows the existing JSON matchers to be used when matching requests.\n- converts JSON responses back into proto messages so that all of WireMock's response definition features including templating can be used.\n\n\u003cimg src=\"/images/solutions/grpc/intro_schema.png\" alt=\"WireMock and gRPC schema\" style=\"width: 100%; height: auto; margin-top: 1em;\"/\u003e\n\nThe extension also adds a Java DSL that works with the Java classes generated by `protoc`, while also providing a more gRPC idiomatic way of defining stubs.\n\n## Java usage\n\n### Setup\n\nAdd the extension JAR dependency to your project:\n\nGradle:\n\n  ```gradle\n  implementation 'org.wiremock:wiremock-grpc-extension:{{ versions.grpc_extension_version }}'\n  ```\n\nMaven:\n\n  ```xml\n  \u003cdependency\u003e\n      \u003cgroupId\u003eorg.wiremock\u003c/groupId\u003e\n      \u003cartifactId\u003ewiremock-grpc-extension\u003c/artifactId\u003e\n      \u003cversion\u003e{{ versions.grpc_extension_version }}\u003c/version\u003e\n  \u003c/dependency\u003e\n  ```\n\nCreate a root directory for WireMock, typically `src/test/resources/wiremock`, and create a subdirectory in it named `grpc`.\n\nCopy the descriptor files generated by `protoc` from your `.proto` files into the `grpc` subdirectory.\n\nInitialise WireMock server with the extension enabled and the root directory set to the path created in the previous steps:\n\n```java\n// Same config object also for the JUnit 4 rule or JUnit 5 extension\nWireMockServer wm = new WireMockServer(wireMockConfig()\n        .dynamicPort()\n        .withRootDirectory(\"src/test/resources/wiremock\")\n        .extensions(new GrpcExtensionFactory())\n));\n```\n\nInitialise a service class for the gRPC service you want to mock (this must be defined in the `.proto` file you compiled to a descriptor):\n\n```java\nWireMockGrpcService mockGreetingService =\n    new WireMockGrpcService(\n        new WireMock(wm.getPort()),\n        \"com.example.grpc.GreetingService\"\n    );\n```\n\n### Stubbing via JSON matching + responses\n\nTo specify request criteria and response data using JSON:\n\n```java\nmockGreetingService.stubFor(\n    method(\"greeting\")\n        .withRequestMessage(equalToJson(\"{ \\\"name\\\":  \\\"Tom\\\" }\"))\n        .willReturn(json(\"{ \"greeting\": \"Hi Tom from JSON\" }\")));\n```\n\nOr, with a templated response:\n\n{% raw %}\n\n```java\nmockGreetingService.stubFor(\n    method(\"greeting\")\n        .withRequestMessage(equalToJson(\"{ \\\"name\\\":  \\\"${json-unit.any-string}\\\" }\"))\n        .willReturn(\n            jsonTemplate(\n                \"{ \\\"greeting\\\": \\\"Hello {{jsonPath request.body '$.name'}}\\\" }\")));\n```\n\n{% endraw %}\n\n### Stubbing via Java message objects\n\nMatching and stubbing in the Java DSL can also be specified using the Java classes generated by `protoc`:\n\n```java\nmockGreetingService.stubFor(\n    method(\"greeting\")\n        .withRequestMessage(equalToMessage(HelloRequest.newBuilder().setName(\"Tom\")))\n        .willReturn(message(HelloResponse.newBuilder().setGreeting(\"OK\"))));\n```\n\n### Non-OK responses\n\nYou can return gRPC error codes instead of an OK response:\n\n```java\nmockGreetingService.stubFor(\n    method(\"greeting\")\n        .withRequestMessage(equalToMessage(\n            HelloRequest.newBuilder().setName(\"Prereq failure\")\n        ))\n        .willReturn(Status.FAILED_PRECONDITION, \"Failed on some prerequisite\"));\n```\n\n## More examples\n\nFor a more complete set of examples, see the [Java demo project](https://github.com/wiremock/wiremock-grpc-demos/tree/main/java).\n\n\n## Standalone usage\n\n### Setup\n\nDownload the \u003ca id=\"wiremock-standalone-download\" href=\"https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/{{ versions.wiremock_version }}/wiremock-standalone-{{ versions.wiremock_version }}.jar\"\u003estandalone JAR\u003c/a\u003e at version 3.2.0 or above\nand the \u003ca id=\"wiremock-standalone-download\" href=\"https://repo1.maven.org/maven2/org/wiremock/wiremock-grpc-extension-standalone/{{ versions.grpc_extension_version }}/wiremock-grpc-extension-standalone-{{ versions.grpc_extension_version }}.jar\"\u003egRPC extension JAR\u003c/a\u003e into your working directory.\n\nCreate a WireMock data directory with two subdirectories; one for stub mappings, and another for descriptor files:\n\n```bash\nmkdir -p wiremock wiremock/mappings wiremock/grpc\n```\n\nCompile your proto files into descriptors:\n\n```bash\nprotoc --descriptor_set_out wiremock/grpc/services.dsc ExampleServices.proto\n```\n\nRun WireMock, with both directories you just created on the classpath:\n\n```bash\njava -cp wiremock-standalone-{{ versions.wiremock_version }}.jar:wiremock-grpc-extension-standalone-{{ versions.grpc_extension_version }}.jar \\\n  wiremock.Run \\\n  --root-dir wiremock\n```\n\n### Stubbing\n\ngRPC stubs are defined using WireMock's standard JSON format. Requests should always be matched with a `POST` method and a URL path of `/\u003cfully-qualified service name\u003e/\u003cmethod name\u003e`.\n\n```json\n{\n  \"request\" : {\n    \"urlPath\" : \"/com.example.grpc.GreetingService/greeting\",\n    \"method\" : \"POST\",\n    \"bodyPatterns\" : [{\n      \"equalToJson\" : \"{ \\\"name\\\":  \\\"Tom\\\" }\"\n    }]\n  },\n  \"response\" : {\n    \"status\" : 200,\n    \"body\" : \"{\\n  \\\"greeting\\\": \\\"Hi Tom\\\"\\n}\",\n    \"headers\" : {\n      \"grpc-status-name\" : \"OK\"\n    }\n  }\n}\n```\n\n## Reloading gRPC descriptor files\n\nIf you plan to update your gRPC descriptor files at runtime, you can inform WireMock to reload all file descriptors via a POST to the admin API endpoint `/__admin/ext/grpc/reset`.\n\n## More Demos\n\nFor more see the [standalone demo project](https://github.com/wiremock/wiremock-grpc-demos/tree/main/standalone).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiremock%2Fwiremock-grpc-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiremock%2Fwiremock-grpc-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiremock%2Fwiremock-grpc-extension/lists"}