Merge pull request #352 from smallrye/improvement/test-subscribers-as…

…-public-api

Move test subscribers to the public API

context-propagation/src/test/java/io/smallrye/mutiny/context/MultiContextPropagationTest.java

@@ -12,8 +12,8 @@
 
 import io.smallrye.mutiny.Multi;
 import io.smallrye.mutiny.Uni;
+import io.smallrye.mutiny.helpers.test.AssertSubscriber;
 import io.smallrye.mutiny.infrastructure.Infrastructure;
-import io.smallrye.mutiny.test.AssertSubscriber;
 
 public class MultiContextPropagationTest {
 

documentation/src/main/docs/faq.adoc

@@ -794,4 +794,30 @@ include::../../../src/test/java/snippets/PlugTest.java[tags=custom-operator]
 ====
 Custom operators are an advanced feature: when possible please use the existing operators and use helpers such as `stage` to write readable code.
 In the case of custom `Multi` operators it is wise to test them against the _Reactive Streams TCK_.
-====
+====
+
+== How can I write unit / integration tests?
+
+Mutiny provides subscribers for `Uni` and `Multi` offering helpful assertion methods.
+You can use them to test pipelines.
+
+Here is an example to test a `Uni`:
+
+[source,java,indent=0]
+----
+include::../../../src/test/java/snippets/TestSubscribersTest.java[tags=uni]
+----
+
+Testing a `Multi` pipeline is similar:
+
+[source,java,indent=0]
+----
+include::../../../src/test/java/snippets/TestSubscribersTest.java[tags=multi]
+----
+
+The assertions do not just focus on _good_ outcomes, you can also test failures as in:
+
+[source,java,indent=0]
+----
+include::../../../src/test/java/snippets/TestSubscribersTest.java[tags=failing]
+----

documentation/src/test/java/snippets/BroadcastProcessorTest.java

@@ -2,7 +2,7 @@
 
 import io.smallrye.mutiny.Multi;
 import io.smallrye.mutiny.operators.multi.processors.BroadcastProcessor;
-import io.smallrye.mutiny.test.AssertSubscriber;
+import io.smallrye.mutiny.helpers.test.AssertSubscriber;
 import org.junit.jupiter.api.Test;
 
 public class BroadcastProcessorTest {

documentation/src/test/java/snippets/PaginationTest.java

@@ -2,7 +2,7 @@
 
 import io.smallrye.mutiny.Multi;
 import io.smallrye.mutiny.Uni;
-import io.smallrye.mutiny.test.AssertSubscriber;
+import io.smallrye.mutiny.helpers.test.AssertSubscriber;
 import org.junit.jupiter.api.Test;
 
 import java.util.Arrays;

documentation/src/test/java/snippets/TestSubscribersTest.java

@@ -0,0 +1,50 @@
+package snippets;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.helpers.test.AssertSubscriber;
+import org.junit.jupiter.api.Test;
+
+import io.smallrye.mutiny.Uni;
+import io.smallrye.mutiny.helpers.test.UniAssertSubscriber;
+
+import java.io.IOException;
+
+public class TestSubscribersTest {
+
+    @Test
+    void uni() {
+        // tag::uni[]
+        Uni<Integer> uni = Uni.createFrom().item(63);
+
+        UniAssertSubscriber<Integer> subscriber = uni
+                .subscribe().withSubscriber(UniAssertSubscriber.create());
+
+        subscriber.assertCompleted().assertItem(63);
+        // end::uni[]
+    }
+
+    @Test
+    void multi() {
+        // tag::multi[]
+        Multi<Integer> multi = Multi.createFrom().range(1, 5)
+                .onItem().transform(n -> n * 10);
+
+        AssertSubscriber<Integer> subscriber = multi.subscribe().withSubscriber(AssertSubscriber.create(10));
+
+        subscriber.assertCompleted()
+                .assertItems(10, 20, 30, 40);
+        // end::multi[]
+    }
+
+    @Test
+    void failing() {
+        // tag::failing[]
+        Multi<Object> multi = Multi.createFrom().failure(() -> new IOException("Boom"));
+
+        AssertSubscriber<Object> subscriber = multi
+                .subscribe().withSubscriber(AssertSubscriber.create(10));
+
+        subscriber.assertFailedWith(IOException.class, "Boom");
+        // end::failing[]
+    }
+}

documentation/src/test/java/snippets/UnicastProcessorTest.java

@@ -6,7 +6,7 @@
 
 import io.smallrye.mutiny.Multi;
 import io.smallrye.mutiny.operators.multi.processors.UnicastProcessor;
-import io.smallrye.mutiny.test.AssertSubscriber;
+import io.smallrye.mutiny.helpers.test.AssertSubscriber;
 
 public class UnicastProcessorTest {
 

test-utils/src/main/java/io/smallrye/mutiny/test/AbstractSubscriber.java → implementation/src/main/java/io/smallrye/mutiny/helpers/test/AbstractSubscriber.java

@@ -1,19 +1,38 @@
-package io.smallrye.mutiny.test;
+package io.smallrye.mutiny.helpers.test;
 
 import java.util.concurrent.atomic.AtomicReference;
 
 import org.reactivestreams.Subscriber;
 import org.reactivestreams.Subscription;
 
+/**
+ * A convenient base class for a subscriber and subscription to extend in tests and that manages the subscription and
+ * requests.
+ * <p>
+ *
+ * Implementations shall override {@link AbstractSubscriber#onNext(Object)},
+ * {@link AbstractSubscriber#onError(Throwable)} and/or {@link AbstractSubscriber#onComplete()} to add test-specific
+ * custom logic.
+ *
+ * @param <T> the type of the items
+ */
 @SuppressWarnings("SubscriberImplementation")
 public class AbstractSubscriber<T> implements Subscriber<T>, Subscription {
 
     private final long upfrontRequest;
 
+    /**
+     * Creates a new {@link AbstractSubscriber} with 0 upfront requests.
+     */
     public AbstractSubscriber() {
         upfrontRequest = 0;
     }
 
+    /**
+     * Creates a new {@link AbstractSubscriber} with {@code req} upfront requests.
+     *
+     * @param req the number of upfront requests
+     */
     public AbstractSubscriber(long req) {
         upfrontRequest = req;
     }