From 820d821fe4bb147428f902f6091be65ac8a6cab5 Mon Sep 17 00:00:00 2001 From: slinkydeveloper Date: Wed, 6 Nov 2024 14:44:09 +0100 Subject: [PATCH] Improve testing tools Javadocs --- .github/workflows/tests.yml | 3 ++- .../sdk/testing/ManualRestateRunner.java | 16 +++++++++++++++- .../restate/sdk/testing/RestateRunner.java | 19 +++++++++++-------- .../sdk/testing/RestateRunnerBuilder.java | 12 +++++++++++- .../dev/restate/sdk/testing/RestateURL.java | 3 +-- .../dev/restate/sdk/testing/CounterTest.java | 2 +- 6 files changed, 41 insertions(+), 14 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index fc11a00b..c4035893 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -31,7 +31,8 @@ jobs: uses: gradle/actions/wrapper-validation@v3 - name: Build with Gradle - run: ./gradlew build + # Javadoc 11 won't work with our Javadocs, they need 21 + run: ./gradlew build -x javadoc - name: Upload test results if: always() diff --git a/sdk-testing/src/main/java/dev/restate/sdk/testing/ManualRestateRunner.java b/sdk-testing/src/main/java/dev/restate/sdk/testing/ManualRestateRunner.java index 5f4726e5..a2637d9b 100644 --- a/sdk-testing/src/main/java/dev/restate/sdk/testing/ManualRestateRunner.java +++ b/sdk-testing/src/main/java/dev/restate/sdk/testing/ManualRestateRunner.java @@ -30,7 +30,15 @@ import org.testcontainers.images.builder.Transferable; import org.testcontainers.utility.DockerImageName; -/** Manual runner for Restate. We recommend using {@link RestateRunner} with JUnit 5. */ +/** + * Manual runner for the Restate test infra, starting the Restate server container together with the + * provided services and automatically registering them. To start the infra use {@link #run()} and + * to stop it use {@link #stop()}. + * + *

Use {@link RestateRunnerBuilder#buildManualRunner()} to build an instance of this class. + * + *

If you use JUnit 5, we suggest using {@link RestateRunner} instead. + */ public class ManualRestateRunner implements AutoCloseable, ExtensionContext.Store.CloseableResource { @@ -75,6 +83,12 @@ public class ManualRestateRunner } /** Run restate, run the embedded service endpoint server, and register the services. */ + public void start() {} + + /** + * @deprecated Use {@link #start()} instead. + */ + @Deprecated(forRemoval = true) public void run() { // Start listening the local server try { diff --git a/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunner.java b/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunner.java index 10f7c3c3..e9d08213 100644 --- a/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunner.java +++ b/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunner.java @@ -15,26 +15,29 @@ * Restate runner for JUnit 5. Example: * * 

{@code
- * {@literal @}RegisterExtension
+ * @RegisterExtension
  * private final static RestateRunner restateRunner = RestateRunnerBuilder.create()
  *         .withService(new MyService())
  *         .buildRunner();
  * }
* - *

The runner will deploy the services locally, execute Restate as container using - * testcontainers, and register the services. + *

The runner will deploy the services locally, execute Restate as container using Testcontainers, and register the services. * *

This extension is scoped per test class, meaning that the restate runner will be shared among * test methods. * *

Use the annotations {@link RestateClient}, {@link RestateURL} and {@link RestateAdminClient} - * to interact with the deployed runtime: + * to interact with the deployed server: * * 

{@code
- * {@literal @}Test
- * void testGreet({@literal @}RestateGrpcChannel ManagedChannel channel) {
- *     CounterGrpc.CounterBlockingStub client = CounterGrpc.newBlockingStub(channel);
- *     // Use client
+ * @Test
+ * void initialCountIsZero(@RestateClient Client client) {
+ *     var client = CounterClient.fromClient(ingressClient, "my-counter");
+ *
+ *     // Use client as usual
+ *     long response = client.get();
+ *     assertThat(response).isEqualTo(0L);
  * }
  * }
*/ diff --git a/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunnerBuilder.java b/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunnerBuilder.java index 12d0b5fe..126943b4 100644 --- a/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunnerBuilder.java +++ b/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunnerBuilder.java @@ -13,7 +13,11 @@ import java.util.HashMap; import java.util.Map; -/** Builder for {@link RestateRunner}. See {@link RestateRunner} for more details. */ +/** + * Builder for {@link RestateRunner}. + * + * @see RestateRunner + */ public class RestateRunnerBuilder { private static final String DEFAULT_RESTATE_CONTAINER = "docker.io/restatedev/restate"; @@ -73,6 +77,9 @@ public RestateRunnerBuilder bind(ServiceDefinition serviceDefinition, O o return this; } + /** + * @return a {@link ManualRestateRunner} to start and stop the test infra manually. + */ public ManualRestateRunner buildManualRunner() { return new ManualRestateRunner( this.endpointBuilder.build(), @@ -81,6 +88,9 @@ public ManualRestateRunner buildManualRunner() { this.configFile); } + /** + * @return a {@link RestateRunner} to be used as JUnit 5 Extension. + */ public RestateRunner buildRunner() { return new RestateRunner(this.buildManualRunner()); } diff --git a/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateURL.java b/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateURL.java index c7d93d5b..60e7f8e6 100644 --- a/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateURL.java +++ b/sdk-testing/src/main/java/dev/restate/sdk/testing/RestateURL.java @@ -15,8 +15,7 @@ import java.net.URL; /** - * Inject Restate's URL (either {@link String} or {@link URL}) to interact with the deployed - * runtime. + * Inject Restate's URL (either {@link String} or {@link URL}) to interact with the deployed server. */ @Target(value = ElementType.PARAMETER) @Retention(RetentionPolicy.RUNTIME) diff --git a/sdk-testing/src/test/java/dev/restate/sdk/testing/CounterTest.java b/sdk-testing/src/test/java/dev/restate/sdk/testing/CounterTest.java index 4ba4e058..42acd73b 100644 --- a/sdk-testing/src/test/java/dev/restate/sdk/testing/CounterTest.java +++ b/sdk-testing/src/test/java/dev/restate/sdk/testing/CounterTest.java @@ -29,8 +29,8 @@ class CounterTest { @Timeout(value = 10) void testGreet(@RestateClient Client ingressClient) { var client = CounterClient.fromClient(ingressClient, "my-counter"); - long response = client.get(); + long response = client.get(); assertThat(response).isEqualTo(0L); } }