Improve testing tools Javadocs (#388)

Author: slinkydeveloper

.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()

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()}.
+ *
+ * <p>Use {@link RestateRunnerBuilder#buildManualRunner()} to build an instance of this class.
+ *
+ * <p>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 {

sdk-testing/src/main/java/dev/restate/sdk/testing/RestateRunner.java

@@ -15,26 +15,29 @@
  * Restate runner for JUnit 5. Example:
  *
  * <pre>{@code
- * {@literal @}RegisterExtension
+ * @RegisterExtension
  * private final static RestateRunner restateRunner = RestateRunnerBuilder.create()
  *         .withService(new MyService())
  *         .buildRunner();
  * }</pre>
  *
- * <p>The runner will deploy the services locally, execute Restate as container using
- * testcontainers, and register the services.
+ * <p>The runner will deploy the services locally, execute Restate as container using <a
+ * href="https://java.testcontainers.org/">Testcontainers</a>, and register the services.
  *
  * <p>This extension is scoped per test class, meaning that the restate runner will be shared among
  * test methods.
  *
  * <p>Use the annotations {@link RestateClient}, {@link RestateURL} and {@link RestateAdminClient}
- * to interact with the deployed runtime:
+ * to interact with the deployed server:
  *
  * <pre>{@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);
  * }
  * }</pre>
  */

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 <O> RestateRunnerBuilder bind(ServiceDefinition<O> 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());
   }

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)

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);
   }
 }