From 04cbbf2005f9cfc5e1c896c51d8818d1ac45f05e Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 10:21:47 +0000 Subject: [PATCH 01/19] Added mkdocs.yml and copied README under docs/ --- docs/index.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 16 +++++ 2 files changed, 200 insertions(+) create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e2527d4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,184 @@ +--- +description: > + WireMock extension for gRPC. +og_image: solutions/grpc/wiremock_grpc_opengraph.png +hero: solutions/grpc/header.png +--- + +# Mocking gRPC services + +The [WireMock extension for gRPC](https://github.com/wiremock/wiremock-grpc-extension), compatible with WireMock 3.2.0+, supports mocking of gRPC services. + +To set up the extension for use, you: + +- add the extension JAR dependency to your project. +- create a root directory for WireMock e.g. `src/test/resources/wiremock` with a subdirectory under it, named `grpc`. +- copy the descriptor files generated by `protoc` from your `.proto` files into the `grpc` subdirectory. + +For details, see [Setup](setup) below. + +At runtime, the extension: + +- scans for descriptor files (generated from the service's `.proto` files) in the `grpc` subdirectory of WireMock's root. +- 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. +- converts JSON responses back into proto messages so that all of WireMock's response definition features including templating can be used. + +WireMock and gRPC schema + +The 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. + +## Java usage + +### Setup + +Add the extension JAR dependency to your project: + +=== "Gradle" + + ```gradle + implementation 'org.wiremock:wiremock-grpc-extension:{{ versions.grpc_extension_version }}' + ``` + +=== "Maven" + + ```xml + + org.wiremock + wiremock-grpc-extension + {{ versions.grpc_extension_version }} + + ``` + +Create a root directory for WireMock, typically `src/test/resources/wiremock`, and create a subdirectory in it named `grpc`. + +Copy the descriptor files generated by `protoc` from your `.proto` files into the `grpc` subdirectory. + +Initialise WireMock server with the extension enabled and the root directory set to the path created in the previous steps: + +```java +// Same config object also for the JUnit 4 rule or JUnit 5 extension +WireMockServer wm = new WireMockServer(wireMockConfig() + .dynamicPort() + .withRootDirectory("src/test/resources/wiremock") + .extensions(new GrpcExtensionFactory()) +)); +``` + +Initialise a service class for the gRPC service you want to mock (this must be defined in the `.proto` file you compiled to a descriptor): + +```java +WireMockGrpcService mockGreetingService = + new WireMockGrpcService( + new WireMock(wm.getPort()), + "com.example.grpc.GreetingService" + ); +``` + +### Stubbing via JSON matching + responses + +To specify request criteria and response data using JSON: + +```java +mockGreetingService.stubFor( + method("greeting") + .withRequestMessage(equalToJson("{ \"name\": \"Tom\" }")) + .willReturn(json("{ "greeting": "Hi Tom from JSON" }"))); +``` + +Or, with a templated response: + +{% raw %} + +```java +mockGreetingService.stubFor( + method("greeting") + .withRequestMessage(equalToJson("{ \"name\": \"${json-unit.any-string}\" }")) + .willReturn( + jsonTemplate( + "{ \"greeting\": \"Hello {{jsonPath request.body '$.name'}}\" }"))); +``` + +{% endraw %} + +### Stubbing via Java message objects + +Matching and stubbing in the Java DSL can also be specified using the Java classes generated by `protoc`: + +```java +mockGreetingService.stubFor( + method("greeting") + .withRequestMessage(equalToMessage(HelloRequest.newBuilder().setName("Tom"))) + .willReturn(message(HelloResponse.newBuilder().setGreeting("OK")))); +``` + +### Non-OK responses + +You can return gRPC error codes instead of an OK response: + +```java +mockGreetingService.stubFor( + method("greeting") + .withRequestMessage(equalToMessage( + HelloRequest.newBuilder().setName("Prereq failure") + )) + .willReturn(Status.FAILED_PRECONDITION, "Failed on some prerequisite")); +``` + +## More examples + +For a more complete set of examples, see the [Java demo project](https://github.com/wiremock/wiremock-grpc-demos/tree/main/java). + + +## Standalone usage + +### Setup + +Download the standalone JAR at version 3.2.0 or above +and the gRPC extension JAR into your working directory. + +Create a WireMock data directory with two subdirectories; one for stub mappings, and another for descriptor files: + +```bash +mkdir -p wiremock/mappings wiremock/grpc +``` + +Compile your proto files into descriptors: + +```bash +protoc --descriptor_set_out wiremock/grpc/services.dsc ExampleServices.proto +``` + +Run WireMock, with both directories you just created on the classpath: + +```bash +java -cp wiremock-standalone-{{ versions.wiremock_version }}.jar:wiremock-grpc-extension-standalone-{{ versions.grpc_extension_version }}.jar \ + wiremock.Run \ + --root-dir wiremock-data +``` + +### Stubbing + +gRPC stubs are defined using WireMock's standard JSON format. Requests should always be matched with a `POST` method and a URL path of `//`. + +```json +{ + "request" : { + "urlPath" : "/com.example.grpc.GreetingService/greeting", + "method" : "POST", + "bodyPatterns" : [{ + "equalToJson" : "{ \"name\": \"Tom\" }" + }] + }, + "response" : { + "status" : 200, + "body" : "{\n \"greeting\": \"Hi Tom\"\n}", + "headers" : { + "grpc-status-name" : "OK" + } + } +} +``` + +## More Demos + +For more see the [standalone demo project](https://github.com/wiremock/wiremock-grpc-demos/tree/main/standalone). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..50dff87 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,16 @@ +site_name: WireMock gRPC Extension Documentation +site_description: WireMock gRPC Extension Documentation. + +site_url: https://wiremock.org/docs/grpc-extension/ + +copyright: Copyright © 2024 - WireMock Contributors +docs_dir: docs +repo_url: https://github.com/wiremock/wiremock-grpc-extension +repo_name: WireMock gRPC Extension + +edit_uri: edit/main/ + +use_directory_urls: false + +nav: + - Home: docs/index.md \ No newline at end of file From 77291787c3dc748fe5638ac2b1324d244b4371e0 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 15:40:37 +0000 Subject: [PATCH 02/19] WIP --- mkdocs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 50dff87..4184af3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,3 @@ repo_name: WireMock gRPC Extension edit_uri: edit/main/ use_directory_urls: false - -nav: - - Home: docs/index.md \ No newline at end of file From 42b91fc959b71f1216a80ef735086a16d5513d5c Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 15:41:27 +0000 Subject: [PATCH 03/19] WIP2 --- mkdocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 4184af3..8fb56a7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,3 +11,6 @@ repo_name: WireMock gRPC Extension edit_uri: edit/main/ use_directory_urls: false + +nav: + - index: docs/index.md \ No newline at end of file From 31ba0100527ce8c1792a16810eadc2a894b3a916 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 20:47:34 +0000 Subject: [PATCH 04/19] WIP3 --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 8fb56a7..8dc152a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - index: docs/index.md \ No newline at end of file + - gRPC: docs/index.md \ No newline at end of file From a10b76bc5474ab90c71ca2b0af7f97ed3f80fe3e Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 20:48:20 +0000 Subject: [PATCH 05/19] WIP4 --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 8dc152a..6b45b8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - gRPC: docs/index.md \ No newline at end of file + - gRPC: index.md \ No newline at end of file From d69240ab3540076f3651500e5c5365007ef7f7f1 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:15:37 +0000 Subject: [PATCH 06/19] WIP5 --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6b45b8e..755d4a0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - gRPC: index.md \ No newline at end of file + - Overview: docs/index.md \ No newline at end of file From e87c8da90d195ddac587794c83f5ea62c9b6a84a Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:20:54 +0000 Subject: [PATCH 07/19] WIP6 --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 755d4a0..0b27ce6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: docs/index.md \ No newline at end of file + - Overview: README.md \ No newline at end of file From 3a84d2e3cc02fe75cd242269d67418ecd7d53bb5 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:26:49 +0000 Subject: [PATCH 08/19] WIP7 --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 0b27ce6..0fe80d4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: README.md \ No newline at end of file + - Overview: docs/ \ No newline at end of file From 952647f4cf8097ac0579c7b7d10fd98411a0a4c4 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:31:54 +0000 Subject: [PATCH 09/19] WIP8 --- mkdocs.yml => docs/mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename mkdocs.yml => docs/mkdocs.yml (91%) diff --git a/mkdocs.yml b/docs/mkdocs.yml similarity index 91% rename from mkdocs.yml rename to docs/mkdocs.yml index 0fe80d4..1defbfb 100644 --- a/mkdocs.yml +++ b/docs/mkdocs.yml @@ -4,7 +4,7 @@ site_description: WireMock gRPC Extension Documentation. site_url: https://wiremock.org/docs/grpc-extension/ copyright: Copyright © 2024 - WireMock Contributors -docs_dir: docs +docs_dir: . repo_url: https://github.com/wiremock/wiremock-grpc-extension repo_name: WireMock gRPC Extension @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: docs/ \ No newline at end of file + - Overview: index.md \ No newline at end of file From 172c6cd133d54a4687e72d176eb9702ccaefb046 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:38:53 +0000 Subject: [PATCH 10/19] WIP --- docs/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1defbfb..4af8f6c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: index.md \ No newline at end of file + - Overview: /index.md \ No newline at end of file From d4862085e2ca5665d8af77a2a01069959d5cc726 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:39:44 +0000 Subject: [PATCH 11/19] WIP --- docs/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 4af8f6c..f478167 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: /index.md \ No newline at end of file + - Overview: ./index.md \ No newline at end of file From 624140f21b9b22798c0888347a9af02797415748 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 21:41:08 +0000 Subject: [PATCH 12/19] WIP --- docs/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f478167..c577925 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: ./index.md \ No newline at end of file + - Overview: './' \ No newline at end of file From 3e89a98027e0060cb2f005d7dc9946aca9eb039f Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 22:12:50 +0000 Subject: [PATCH 13/19] WIP --- docs/mkdocs.yml => mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/mkdocs.yml => mkdocs.yml (94%) diff --git a/docs/mkdocs.yml b/mkdocs.yml similarity index 94% rename from docs/mkdocs.yml rename to mkdocs.yml index c577925..6f29e92 100644 --- a/docs/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: './' \ No newline at end of file + - Overview: 'docs/' \ No newline at end of file From fca3bf0ebdce8a76aa2fc5bc0a1d00021acd8b61 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 22:14:20 +0000 Subject: [PATCH 14/19] WIP --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6f29e92..14b5550 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,7 @@ site_description: WireMock gRPC Extension Documentation. site_url: https://wiremock.org/docs/grpc-extension/ copyright: Copyright © 2024 - WireMock Contributors -docs_dir: . +docs_dir: docs repo_url: https://github.com/wiremock/wiremock-grpc-extension repo_name: WireMock gRPC Extension From 99af62f94de9c71ef6fb3550db55b444bdac4ea5 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Thu, 1 Feb 2024 22:15:59 +0000 Subject: [PATCH 15/19] WIP --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 14b5550..6e4cf00 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,4 +13,4 @@ edit_uri: edit/main/ use_directory_urls: false nav: - - Overview: 'docs/' \ No newline at end of file + - Overview: './' \ No newline at end of file From 44ba0779f18f401589e80768d8587272e56fcf16 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Fri, 2 Feb 2024 16:31:07 +0000 Subject: [PATCH 16/19] WIP --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6e4cf00..cf8b346 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,7 @@ docs_dir: docs repo_url: https://github.com/wiremock/wiremock-grpc-extension repo_name: WireMock gRPC Extension -edit_uri: edit/main/ +edit_uri: edit/main/docs/ use_directory_urls: false From 02a69cbd569c0cd591cf9089b24e5fe60433a1e0 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Fri, 2 Feb 2024 16:33:07 +0000 Subject: [PATCH 17/19] WIP --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index cf8b346..c89244c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,7 @@ docs_dir: docs repo_url: https://github.com/wiremock/wiremock-grpc-extension repo_name: WireMock gRPC Extension -edit_uri: edit/main/docs/ +edit_uri: edit/docs-experiments/docs/ use_directory_urls: false From 59dac011a4f8ea63192e72b10b4b4dab54ba4f93 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Fri, 2 Feb 2024 16:36:20 +0000 Subject: [PATCH 18/19] WIP --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index c89244c..17b6294 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,7 @@ docs_dir: docs repo_url: https://github.com/wiremock/wiremock-grpc-extension repo_name: WireMock gRPC Extension -edit_uri: edit/docs-experiments/docs/ +edit_uri: edit/docs-experiments/docs/docs/ use_directory_urls: false From 4d46d292cdc13848a0c5d08b5972f2f202cb1273 Mon Sep 17 00:00:00 2001 From: Tom Akehurst Date: Fri, 2 Feb 2024 16:38:46 +0000 Subject: [PATCH 19/19] WIP --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 17b6294..edec247 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,7 @@ docs_dir: docs repo_url: https://github.com/wiremock/wiremock-grpc-extension repo_name: WireMock gRPC Extension +# Adding docs/ twice is a workaround due to it being stripped out before the plugin calculates the edit_uri edit_uri: edit/docs-experiments/docs/docs/ use_directory_urls: false