Merge pull request #28809 from akka/wip-28808-persistence-init-patriknw

Persistence initialization utility #28808

akka-docs/src/main/paradox/typed/persistence-testing.md

@@ -188,4 +188,25 @@ For tests that involve more than one Cluster node you have to use another journa
 While it's possible to use the @ref:[Persistence Plugin Proxy](../persistence-plugins.md#persistence-plugin-proxy)
 it's often better and more realistic to use a real database.
 
-See [akka-samples issue #128](https://github.com/akka/akka-samples/issues/128).    
+See [akka-samples issue #128](https://github.com/akka/akka-samples/issues/128).
+
+### Plugin initialization
+
+Some Persistence plugins create tables automatically, but has the limitation that it can't be done concurrently
+from several ActorSystems. That can be a problem if the test creates a Cluster and all nodes tries to initialize
+the plugins at the same time. To coordinate initialization you can use the `PersistenceInit` utility.
+
+`PersistenceInit` is part of `akka-persistence-testkit` and you need to add the dependency to your project:
+
+@@dependency[sbt,Maven,Gradle] {
+  group="com.typesafe.akka"
+  artifact="akka-persistence-testkit_$scala.binary_version$"
+  version="$akka.version$"
+}
+
+Scala
+:  @@snip [PersistenceInitSpec.scala](/akka-docs/src/test/scala/docs/persistence/testkit/PersistenceInitSpec.scala) { #imports #init }
+
+Java
+:  @@snip [PersistenceInitTest.java](/akka-docs/src/test/java/jdocs/persistence/testkit/PersistenceInitTest.java) { #imports #init }
+  

akka-docs/src/test/java/jdocs/persistence/testkit/PersistenceInitTest.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.persistence.testkit;
+
+import akka.actor.testkit.typed.javadsl.TestKitJunitResource;
+
+import com.typesafe.config.ConfigFactory;
+import jdocs.AbstractJavaTest;
+import org.junit.ClassRule;
+import org.junit.Test;
+
+import java.util.UUID;
+
+// #imports
+import akka.persistence.testkit.javadsl.PersistenceInit;
+import akka.Done;
+
+import java.time.Duration;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.TimeUnit;
+
+// #imports
+
+public class PersistenceInitTest extends AbstractJavaTest {
+  @ClassRule
+  public static final TestKitJunitResource testKit =
+      new TestKitJunitResource(
+          ConfigFactory.parseString(
+                  "akka.persistence.journal.plugin = \"akka.persistence.journal.inmem\" \n"
+                      + "akka.persistence.journal.inmem.test-serialization = on \n"
+                      + "akka.persistence.snapshot-store.plugin = \"akka.persistence.snapshot-store.local\" \n"
+                      + "akka.persistence.snapshot-store.local.dir = \"target/snapshot-"
+                      + UUID.randomUUID().toString()
+                      + "\" \n")
+              .withFallback(ConfigFactory.defaultApplication()));
+
+  @Test
+  public void testInit() throws Exception {
+    // #init
+    Duration timeout = Duration.ofSeconds(5);
+    CompletionStage<Done> done =
+        PersistenceInit.initializeDefaultPlugins(testKit.system(), timeout);
+    done.toCompletableFuture().get(timeout.getSeconds(), TimeUnit.SECONDS);
+    // #init
+  }
+}

akka-docs/src/test/scala/docs/persistence/testkit/PersistenceInitSpec.scala

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.persistence.testkit
+
+import akka.Done
+import akka.actor.testkit.typed.scaladsl.ScalaTestWithActorTestKit
+import org.scalatest.wordspec.AnyWordSpecLike
+
+//#imports
+import akka.persistence.testkit.scaladsl.PersistenceInit
+
+import scala.concurrent.Await
+import scala.concurrent.Future
+import scala.concurrent.duration._
+
+//#imports
+
+class PersistenceInitSpec
+    extends ScalaTestWithActorTestKit(
+      """
+  akka.persistence.journal.plugin = "akka.persistence.journal.inmem"
+  akka.persistence.snapshot-store.plugin = "akka.persistence.snapshot-store.local"
+  akka.persistence.snapshot-store.local.dir = "target/snapshot-${UUID.randomUUID().toString}"
+  """)
+    with AnyWordSpecLike {
+
+  "PersistenceInit" should {
+    "initialize plugins" in {
+      //#init
+      val timeout = 5.seconds
+      val done: Future[Done] = PersistenceInit.initializeDefaultPlugins(system, timeout)
+      Await.result(done, timeout)
+      //#init
+    }
+  }
+}