Add tempest testing dev guide (#35)

cashapp · Mar 8, 2021 · c725d37 · c725d37
1 parent 143001c
commit c725d37
Show file tree

Hide file tree

Showing 6 changed files with 223 additions and 13 deletions.
diff --git a/docs/guide/testing.md b/docs/guide/testing.md
@@ -1,3 +1,201 @@
-You may test Tempest using [DynamoDBLocal](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html).
+## Tempest Testing
 
-Here is how we setup our testing environment: [InProcessDynamoDbModule.kt](https://github.com/cashapp/misk/blob/master/misk-aws2-dynamodb-testing/src/main/kotlin/misk/aws2/dynamodb/testing/InProcessDynamoDbModule.kt).
+Tempest provides a library for testing DynamoDB clients
+using [DynamoDBLocal](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)
+. It comes with two implementations:
+
+- **JVM:** This is the preferred option, running a `DynamoDBProxyServer` backed by `sqlite4java`,
+  which is available on most platforms.
+- **Docker:** This runs [dynamodb-local](https://hub.docker.com/r/amazon/dynamodb-local) in a Docker
+  container.
+
+Feature matrix:
+
+Feature         |tempest-testing-jvm        |tempest-testing-docker
+----------------|---------------------------|----------------------
+Start up time   |~1s                        |~10s
+Memory usage    |Less                       |More
+Dependency      |sqlite4java native library |Docker
+
+## JUnit 5 Integration
+
+To use `tempest-testing`, first add this library as a test dependency:
+
+For AWS SDK 1.x:
+
+```groovy
+dependencies {
+  testImplementation "app.cash.tempest:tempest-testing-jvm:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest-testing-junit5:{{ versions.tempest }}"
+}
+// Or
+dependencies {
+  testImplementation "app.cash.tempest:tempest-testing-docker:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest-testing-junit5:{{ versions.tempest }}"
+}
+```
+
+For AWS SDK 2.x:
+
+```groovy
+dependencies {
+  testImplementation "app.cash.tempest:tempest2-testing-jvm:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest2-testing-junit5:{{ versions.tempest }}"
+}
+// Or
+dependencies {
+  testImplementation "app.cash.tempest:tempest2-testing-docker:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest2-testing-junit5:{{ versions.tempest }}"
+}
+```
+
+Then in tests annotated `@org.junit.jupiter.api.Test`, you may add `TestDynamoDb` as a test
+[extension](https://junit.org/junit5/docs/current/user-guide/#extensions). This extension spins up a
+DynamoDB server. It shares the server across tests and keeps it running until the process exits. It
+also manages test tables for you, recreating them before each test.
+
+```kotlin
+class MyTest {
+  @RegisterExtension
+  @JvmField
+  val db = TestDynamoDb.Builder(JvmDynamoDbServer.Factory)
+    // Tempest recreates this `@DynamoDBTable` before each test.
+    .addTable(TestTable.create<MusicItem>())
+    .build()
+
+  private val musicTable by lazy { db.logicalDb<MusicDb>().music }
+
+  @Test
+  fun test() {
+    val albumInfo = AlbumInfo(
+      "ALBUM_1",
+      "after hours - EP",
+      "53 Thieves",
+      LocalDate.of(2020, 2, 21),
+      "Contemporary R&B"
+    )
+    // Talk to DynamoDB using Tempest's API.
+    musicTable.albumInfo.save(albumInfo)
+  }
+
+  @Test
+  fun anotherTest() {
+    // Talk to DynamoDB using the AWS SDK.
+    val result = db.dynamoDb.describeTable("table_name")
+  }
+}
+```
+
+To customize test tables, mutate the `CreateTableRequest` in a lambda.
+
+```kotlin
+fun testDb() = TestDynamoDb.Builder(JvmDynamoDbServer.Factory)
+  .addTable(
+    TestTable.create<MusicItem> { createTableRequest ->
+      for (gsi in createTableRequest.globalSecondaryIndexes) {
+        gsi.withProjection(Projection().withProjectionType(ProjectionType.ALL))
+      }
+      createTableRequest
+    }
+  )
+  .build()
+```
+
+To use the Docker implementation, specify it in the builder.
+
+```kotlin
+fun testDb() = TestDynamoDb.Builder(DockerDynamoDbServer.Factory)
+  .addTable(TestTable.create<MusicItem>())
+  .build()
+```
+
+## JUnit 4 Integration
+
+To use `tempest-testing`, first add this library as a test dependency:
+
+For AWS SDK 1.x:
+
+```groovy
+dependencies {
+  testImplementation "app.cash.tempest:tempest-testing-jvm:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest-testing-junit4:{{ versions.tempest }}"
+}
+// Or
+dependencies {
+  testImplementation "app.cash.tempest:tempest-testing-docker:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest-testing-junit4:{{ versions.tempest }}"
+}
+```
+
+For AWS SDK 2.x:
+
+```groovy
+dependencies {
+  testImplementation "app.cash.tempest:tempest2-testing-jvm:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest2-testing-junit4:{{ versions.tempest }}"
+}
+// Or
+dependencies {
+  testImplementation "app.cash.tempest:tempest2-testing-docker:{{ versions.tempest }}"
+  testImplementation "app.cash.tempest:tempest2-testing-junit4:{{ versions.tempest }}"
+}
+```
+
+Then in tests annotated `@org.junit.Test`, you may add `TestDynamoDb` as a
+test [rule](https://junit.org/junit4/javadoc/4.12/org/junit/Rule.html). This rule spins up a
+DynamoDB server. It shares the server across tests and keeps it running until the process exits. It
+also manages test tables for you, recreating them before each test.
+
+```kotlin
+class MyTest {
+  @get:Rule
+  val db = TestDynamoDb.Builder(JvmDynamoDbServer.Factory)
+    // Tempest recreates this `@DynamoDBTable` before each test.
+    .addTable(TestTable.create<MusicItem>())
+    .build()
+
+  private val musicTable by lazy { db.logicalDb<MusicDb>().music }
+
+  @Test
+  fun test() {
+    val albumInfo = AlbumInfo(
+      "ALBUM_1",
+      "after hours - EP",
+      "53 Thieves",
+      LocalDate.of(2020, 2, 21),
+      "Contemporary R&B"
+    )
+    // Talk to DynamoDB using Tempest's API.
+    musicTable.albumInfo.save(albumInfo)
+  }
+
+  @Test
+  fun anotherTest() {
+    // Talk to DynamoDB using the AWS SDK.
+    val result = db.dynamoDb.describeTable("table_name")
+  }
+}
+```
+
+To customize test tables, mutate the `CreateTableRequest` in a lambda.
+
+```kotlin
+fun testDb() = TestDynamoDb.Builder(JvmDynamoDbServer.Factory)
+  .addTable(
+    TestTable.create<MusicItem> { createTableRequest ->
+      for (gsi in createTableRequest.globalSecondaryIndexes) {
+        gsi.withProjection(Projection().withProjectionType(ProjectionType.ALL))
+      }
+      createTableRequest
+    }
+  )
+  .build()
+```
+
+To use the Docker implementation, specify it in the builder.
+
+```kotlin
+fun testDb() = TestDynamoDb.Builder(DockerDynamoDbServer.Factory)
+  .addTable(TestTable.create<MusicItem>())
+  .build()
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,7 +4,7 @@ repo_name: cashapp/tempest
 repo_url: https://github.com/cashapp/tempest
 site_description: "Tempest - Typesafe DynamoDB in Kotlin"
 site_author: Square, Inc.
-copyright: 'Copyright &copy; 2020 Square, Inc.'
+copyright: 'Copyright &copy; 2021 Square, Inc.'
 remote_branch: gh-pages
 
 theme:
@@ -67,8 +67,20 @@ nav:
       - 'DynamoDB Resources': guide/dynamodb_resources.md
 
   - 'Reference':
-      - 'For AWS SDK 1.x': 1.x/tempest/app.cash.tempest/index.md
-      - 'For AWS SDK 2.x': 1.x/tempest2/app.cash.tempest2/index.md
+      - 'For AWS SDK 1.x':
+          - 'tempest': 1.x/tempest/app.cash.tempest/index.md
+          - 'tempest-testing': 1.x/tempest-testing/app.cash.tempest.testing/index.md
+          - 'tempest-testing-jvm': 1.x/tempest-testing-jvm/app.cash.tempest.testing/index.md
+          - 'tempest-testing-docker': 1.x/tempest-testing-docker/app.cash.tempest.testing/index.md
+          - 'tempest-testing-junit5': 1.x/tempest-testing-junit5/app.cash.tempest.testing/index.md
+          - 'tempest-testing-junit4': 1.x/tempest-testing-junit4/app.cash.tempest.testing/index.md
+      - 'For AWS SDK 2.x':
+          - 'tempest2': 1.x/tempest2/app.cash.tempest2/index.md
+          - 'tempest2-testing': 1.x/tempest2-testing/app.cash.tempest2.testing/index.md
+          - 'tempest2-testing-jvm': 1.x/tempest2-testing-jvm/app.cash.tempest2.testing/index.md
+          - 'tempest2-testing-docker': 1.x/tempest2-testing-docker/app.cash.tempest2.testing/index.md
+          - 'tempest2-testing-junit5': 1.x/tempest2-testing-junit5/app.cash.tempest2.testing/index.md
+          - 'tempest2-testing-junit4': 1.x/tempest2-testing-junit4/app.cash.tempest2.testing/index.md
 
   - 'Changelog': changelog.md
   - 'Contributing': contributing.md

diff --git a/tempest-testing-junit4/src/main/kotlin/app/cash/tempest/testing/TestDynamoDb.kt b/tempest-testing-junit4/src/main/kotlin/app/cash/tempest/testing/TestDynamoDb.kt
@@ -23,8 +23,8 @@ import org.junit.rules.ExternalResource
 import java.util.concurrent.ConcurrentHashMap
 
 /**
- * This JUnit rule spins up a DynamoDB server in tests. It keeps the server running until the
- * process exits and shares it across tests.
+ * This JUnit rule spins up a DynamoDB server in tests. It shares the server across tests and
+ * keeps the server running until the process exits.
  */
 class TestDynamoDb private constructor(
   private val client: TestDynamoDbClient,

diff --git a/tempest-testing-junit5/src/main/kotlin/app/cash/tempest/testing/TestDynamoDb.kt b/tempest-testing-junit5/src/main/kotlin/app/cash/tempest/testing/TestDynamoDb.kt
@@ -25,8 +25,8 @@ import org.junit.jupiter.api.extension.ExtensionContext
 import java.util.concurrent.ConcurrentHashMap
 
 /**
- * This JUnit extension spins up a DynamoDB server in tests. It keeps the server running until the
- * process exits and shares it across tests.
+ * This JUnit extension spins up a DynamoDB server in tests. It shares the server across tests and
+ * keeps the server running until the process exits.
  */
 class TestDynamoDb private constructor(
   private val client: TestDynamoDbClient,

diff --git a/tempest2-testing-junit4/src/main/kotlin/app/cash/tempest2/testing/TestDynamoDb.kt b/tempest2-testing-junit4/src/main/kotlin/app/cash/tempest2/testing/TestDynamoDb.kt
@@ -23,8 +23,8 @@ import org.junit.rules.ExternalResource
 import java.util.concurrent.ConcurrentHashMap
 
 /**
- * This JUnit rule spins up a DynamoDB server in tests. It keeps the server running until the
- * process exits and shares it across tests.
+ * This JUnit rule spins up a DynamoDB server in tests. It shares the server across tests and
+ * keeps the server running until the process exits.
  */
 class TestDynamoDb private constructor(
   private val client: TestDynamoDbClient,

diff --git a/tempest2-testing-junit5/src/main/kotlin/app/cash/tempest2/testing/TestDynamoDb.kt b/tempest2-testing-junit5/src/main/kotlin/app/cash/tempest2/testing/TestDynamoDb.kt
@@ -25,8 +25,8 @@ import org.junit.jupiter.api.extension.ExtensionContext
 import java.util.concurrent.ConcurrentHashMap
 
 /**
- * This JUnit extension spins up a DynamoDB server in tests. It keeps the server running until the
- * process exits and shares it across tests.
+ * This JUnit extension spins up a DynamoDB server in tests. It shares the server across tests and
+ * keeps the server running until the process exits.
  */
 class TestDynamoDb private constructor(
   private val client: TestDynamoDbClient,