From 3015f197f1a0e52c8607a938f996524729c264f0 Mon Sep 17 00:00:00 2001 From: Arnout Engelen Date: Thu, 23 May 2019 14:05:06 +0200 Subject: [PATCH] Typed testing docs: imports and scalatest dependency (#26890) --- .../javadsl/AsyncTestingExampleTest.java | 12 ++++- .../scaladsl/AsyncTestingExampleSpec.scala | 8 ++++ akka-docs/src/main/paradox/typed/testing.md | 47 ++++++++++++------- build.sbt | 1 + 4 files changed, 50 insertions(+), 18 deletions(-) diff --git a/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java b/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java index 689bf51053..ca0fff534f 100644 --- a/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java +++ b/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java @@ -9,11 +9,15 @@ import akka.actor.typed.ActorRef; import akka.actor.typed.Behavior; import akka.actor.typed.javadsl.AskPattern; import akka.actor.typed.javadsl.Behaviors; +// #test-header import akka.actor.testkit.typed.javadsl.ActorTestKit; + +// #test-header import akka.actor.testkit.typed.javadsl.TestProbe; import org.junit.AfterClass; import org.junit.Test; import org.scalatest.junit.JUnitSuite; + import scala.util.Success; import scala.util.Try; @@ -26,7 +30,11 @@ import java.util.Objects; import static org.junit.Assert.assertEquals; // #test-header -public class AsyncTestingExampleTest extends JUnitSuite { +public class AsyncTestingExampleTest + // #test-header + extends JUnitSuite +// #test-header +{ static final ActorTestKit testKit = ActorTestKit.create(); // #test-header @@ -183,4 +191,6 @@ public class AsyncTestingExampleTest extends JUnitSuite { public void systemNameShouldComeFromTestClass() { assertEquals(testKit.system().name(), "AsyncTestingExampleTest"); } + // #test-header } +// #test-header diff --git a/akka-actor-testkit-typed/src/test/scala/docs/akka/actor/testkit/typed/scaladsl/AsyncTestingExampleSpec.scala b/akka-actor-testkit-typed/src/test/scala/docs/akka/actor/testkit/typed/scaladsl/AsyncTestingExampleSpec.scala index a780c7daa4..1b8ecdd78f 100644 --- a/akka-actor-testkit-typed/src/test/scala/docs/akka/actor/testkit/typed/scaladsl/AsyncTestingExampleSpec.scala +++ b/akka-actor-testkit-typed/src/test/scala/docs/akka/actor/testkit/typed/scaladsl/AsyncTestingExampleSpec.scala @@ -5,14 +5,20 @@ package docs.akka.actor.testkit.typed.scaladsl import akka.actor.Scheduler +//#test-header import akka.actor.testkit.typed.scaladsl.ActorTestKit + +//#test-header import akka.actor.typed._ import akka.actor.typed.scaladsl.AskPattern._ import akka.actor.typed.scaladsl.Behaviors import akka.util.Timeout +//#test-header import org.scalatest.BeforeAndAfterAll import org.scalatest.Matchers import org.scalatest.WordSpec + +//#test-header import scala.concurrent.duration._ import scala.concurrent.Future @@ -124,4 +130,6 @@ class AsyncTestingExampleSpec extends WordSpec with BeforeAndAfterAll with Match //#test-shutdown override def afterAll(): Unit = testKit.shutdownTestKit() //#test-shutdown +//#test-header } +//#test-header diff --git a/akka-docs/src/main/paradox/typed/testing.md b/akka-docs/src/main/paradox/typed/testing.md index 466bfc0188..729fb7de1c 100644 --- a/akka-docs/src/main/paradox/typed/testing.md +++ b/akka-docs/src/main/paradox/typed/testing.md @@ -11,14 +11,27 @@ To use Akka TestKit Typed, add the module to your project: scope=test } +@@@div { .group-scala } + +We recommend using Akka TestKit Typed with ScalaTest: + +@@dependency[sbt,Maven,Gradle] { + group=org.scalatest + artifact=scalatest_$scala.binary_version$ + version=$scalatest.version$ + scope=test +} + +@@@ + ## Introduction -Testing can either be done asynchronously using a real `ActorSystem` or synchronously on the testing thread using the `BehaviourTestKit`. +Testing can either be done asynchronously using a real @apidoc[akka.actor.typed.ActorSystem] or synchronously on the testing thread using the @apidoc[BehaviorTestKit]. -For testing logic in a `Behavior` in isolation synchronous testing is preferred. For testing interactions between multiple +For testing logic in a @apidoc[Behavior] in isolation synchronous testing is preferred. For testing interactions between multiple actors a more realistic asynchronous test is preferred. -Certain `Behavior`s will be hard to test synchronously e.g. if they spawn Future's and you rely on a callback to complete +Certain @apidoc[Behavior]s will be hard to test synchronously e.g. if they spawn Future's and you rely on a callback to complete before observing the effect you want to test. Further support for controlling the scheduler and execution context used will be added. @@ -64,8 +77,8 @@ Scala Java : @@snip [SyncTestingExampleTest.java](/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/SyncTestingExampleTest.java) { #child } -All of the tests make use of the `BehaviorTestkit` to avoid the need for a real `ActorContext`. Some of the tests -make use of the `TestInbox` which allows the creation of an `ActorRef` that can be used for synchronous testing, similar to the +All of the tests make use of the @apidoc[BehaviorTestKit] to avoid the need for a real `ActorContext`. Some of the tests +make use of the @apidoc[TestInbox] which allows the creation of an @apidoc[akka.actor.typed.ActorRef] that can be used for synchronous testing, similar to the `TestProbe` used for asynchronous testing. @@ -89,7 +102,7 @@ Java ### Sending messages -For testing sending a message a `TestInbox` is created that provides an `ActorRef` and methods to assert against the +For testing sending a message a @apidoc[TestInbox] is created that provides an @apidoc[akka.actor.typed.ActorRef] and methods to assert against the messages that have been sent to it. Scala @@ -98,8 +111,8 @@ Scala Java : @@snip [SyncTestingExampleTest.java](/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/SyncTestingExampleTest.java) { #test-message } -Another use case is sending a message to a child actor you can do this by looking up the 'TestInbox' for -a child actor from the 'BehaviorTestKit': +Another use case is sending a message to a child actor you can do this by looking up the @apidoc[TestInbox] for +a child actor from the @apidoc[BehaviorTestKit]: Scala : @@snip [SyncTestingExampleSpec.scala](/akka-actor-testkit-typed/src/test/scala/docs/akka/actor/testkit/typed/scaladsl/SyncTestingExampleSpec.scala) { #test-child-message } @@ -117,7 +130,7 @@ Java ### Testing other effects -The `BehaviorTestkit` keeps track other effects you can verify, look at the sub-classes of `akka.actor.testkit.typed.Effect` +The @apidoc[BehaviorTestKit] keeps track other effects you can verify, look at the sub-classes of @apidoc[akka.actor.testkit.typed.Effect] * SpawnedAdapter * Stopped @@ -127,7 +140,7 @@ The `BehaviorTestkit` keeps track other effects you can verify, look at the sub- ### Checking for Log Messages -The `BehaviorTestkit` also keeps track of everything that is being logged. Here, you can see an example on how to check +The @apidoc[BehaviorTestKit] also keeps track of everything that is being logged. Here, you can see an example on how to check if the behavior logged certain messages: Scala @@ -137,11 +150,11 @@ Java : @@snip [SyncTestingExampleTest.java](/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/SyncTestingExampleTest.java) { #test-check-logging } -See the other public methods and API documentation on `BehaviorTestkit` for other types of verification. +See the other public methods and API documentation on @apidoc[BehaviorTestKit] for other types of verification. ## Asynchronous testing -Asynchronous testing uses a real `ActorSystem` that allows you to test your Actors in a more realistic environment. +Asynchronous testing uses a real @apidoc[akka.actor.typed.ActorSystem] that allows you to test your Actors in a more realistic environment. The minimal setup consists of the test procedure, which provides the desired stimuli, the actor under test, and an actor receiving replies. Bigger systems replace the actor under test with a network of actors, apply stimuli @@ -158,7 +171,7 @@ Scala Java : @@snip [AsyncTestingExampleTest.java](/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java) { #under-test } -Tests create an instance of `ActorTestKit`. This provides access to: +Tests create an instance of @apidoc[ActorTestKit]. This provides access to: * An ActorSystem * Methods for spawning Actors. These are created under the root guardian @@ -170,7 +183,7 @@ Scala Java : @@snip [AsyncTestingExampleTest.java](/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java) { #test-header } -Your test is responsible for shutting down the `ActorSystem` e.g. using @scala[`BeforeAndAfterAll` when using ScalaTest]@java[`@AfterClass` when using JUnit]. +Your test is responsible for shutting down the @apidoc[akka.actor.typed.ActorSystem] e.g. using @scala[`BeforeAndAfterAll` when using ScalaTest]@java[`@AfterClass` when using JUnit]. Scala : @@snip [AsyncTestingExampleSpec.scala](/akka-actor-testkit-typed/src/test/scala/docs/akka/actor/testkit/typed/scaladsl/AsyncTestingExampleSpec.scala) { #test-shutdown } @@ -210,7 +223,7 @@ Scala Java : @@snip [AsyncTestingExampleTest.java](/akka-actor-testkit-typed/src/test/java/jdocs/akka/actor/testkit/typed/javadsl/AsyncTestingExampleTest.java) { #test-stop-actors } -The `stop` method can only be used for actors that were spawned by the same `ActorTestKit`. Other actors +The `stop` method can only be used for actors that were spawned by the same @apidoc[ActorTestKit]. Other actors will not be stopped by that method. ### Observing mocked behavior @@ -243,7 +256,7 @@ Java @@@ div { .group-java } -If you are using JUnit you can use `akka.actor.testkit.typed.javadsl.TestKitJunitResource` to have the async test kit automatically +If you are using JUnit you can use @apidoc[akka.actor.testkit.typed.javadsl.TestKitJunitResource] to have the async test kit automatically shutdown when the test is complete. Note that the dependency on JUnit is marked as optional from the test kit module, so your project must explicitly include @@ -253,7 +266,7 @@ a dependency on JUnit to use this. @@@ div { .group-scala } -If you are using ScalaTest you can extend `akka.actor.testkit.typed.scaladsl.ScalaTestWithActorTestKit` to +If you are using ScalaTest you can extend @apidoc[akka.actor.testkit.typed.scaladsl.ScalaTestWithActorTestKit] to have the async test kit automatically shutdown when the test is complete. This is done in `afterAll` from the `BeforeAndAfterAll` trait. If you override that method you should call `super.afterAll` to shutdown the test kit. diff --git a/build.sbt b/build.sbt index 4e3b0cb6e8..c6e093e959 100644 --- a/build.sbt +++ b/build.sbt @@ -211,6 +211,7 @@ lazy val docs = akkaModule("akka-docs") "scala.version" -> scalaVersion.value, "scala.binary_version" -> scalaBinaryVersion.value, "akka.version" -> version.value, + "scalatest.version" -> Dependencies.scalaTestVersion.value, "sigar_loader.version" -> "1.6.6-rev002", "algolia.docsearch.api_key" -> "543bad5ad786495d9ccd445ed34ed082", "algolia.docsearch.index_name" -> "akka_io",