chore: new shared testing features (#1514)

Author: ianbotsf

build.gradle.kts

@@ -61,8 +61,8 @@ allprojects {
         }
     }
 
-    if (testJavaVersion != null) {
-        tasks.withType<Test> {
+    tasks.withType<Test>().configureEach {
+        if (testJavaVersion != null) {
             // JDK8 tests fail with out of memory sometimes, not sure why...
             maxHeapSize = "2g"
             val toolchains = project.extensions.getByType<JavaToolchainService>()
@@ -72,6 +72,13 @@ allprojects {
                 },
             )
         }
+
+        if (testJavaVersion == null || testJavaVersion.asInt() >= 9) {
+            // Required to enable reflective access in testing.
+            // See smithy-kotlin/runtime/testing/jvm/src/aws/smithy/kotlin/runtime/testing/SystemOverrides.kt for more
+            // info.
+            jvmArgs("--add-opens=java.base/java.util=ALL-UNNAMED")
+        }
     }
 
     // Enables running `./gradlew allDeps` to get a comprehensive list of dependencies for every subproject

runtime/testing/common/src/aws/smithy/kotlin/runtime/testing/TestAnnotations.kt

@@ -27,3 +27,12 @@ public expect annotation class AfterAll()
 @Target(AnnotationTarget.FUNCTION)
 @Retention(AnnotationRetention.RUNTIME)
 public expect annotation class IgnoreNative()
+
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.RUNTIME)
+public expect annotation class TestInstance(val value: TestLifecycle)
+
+public expect enum class TestLifecycle {
+    PER_CLASS,
+    PER_METHOD,
+}

runtime/testing/jvm/src/aws/smithy/kotlin/runtime/testing/SystemOverrides.kt

@@ -0,0 +1,93 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.testing
+
+import java.util.*
+
+@PublishedApi
+internal val editableEnvVars: MutableMap<String, String> by lazy {
+    val systemEnv = System.getenv()
+    val classOfMap = systemEnv::class.java
+
+    @Suppress("UNCHECKED_CAST")
+    classOfMap
+        .getDeclaredField("m")
+        .apply { isAccessible = true }
+        .get(systemEnv) as MutableMap<String, String>
+}
+
+@PublishedApi
+internal fun <K, V> MutableMap<K, V>.setAll(newEntries: Map<K, V>) {
+    clear()
+    putAll(newEntries)
+}
+
+/**
+ * Runs the given [block] with modified environment variables. The variables given in [newVars] are merged onto the
+ * existing environment variables, adding values that did not exist previously and updating values which did exist.
+ * After the block completes, environment variables will be restored to their previous values. This method may be nested
+ * multiple times to apply/restore hierarchical overrides.
+ *
+ * **Caution**: This method is not thread-safe as environment variables are global for a JVM instance.
+ *
+ * # How it works
+ *
+ * Normally environment variables cannot be modified within a JVM instance so this function makes use of private
+ * reflection to gain access to the underlying mutable map used by [System.getenv]. At runtime, this requires
+ * `--add-opens=java.base/java.util=ALL-UNNAMED` to be passed to the `java` executable on JDK 9+. For instance:
+ *
+ * ```sh
+ * java \
+ *   -jar my-testing-jar \
+ *   -classpath testing-jvm.X.Y.Z.jar,... \
+ *   --add-opens=java.base/java.util=ALL-UNNAMED
+ * ```
+ *
+ * In **smithy-kotlin** and **aws-sdk-kotlin** this is handled in the root scripts by adding a JVM arg to all JVM test
+ * JARs (whether they rely on this module or not).
+ *
+ * @param newVars The new environment variables to merge onto the existing environment variables
+ * @param block The block to execute with updated environment variables
+ */
+public suspend inline fun <T> withEnvVars(
+    newVars: Map<String, String>,
+    crossinline block: suspend () -> T,
+): T {
+    val originalVars = System.getenv()
+    editableEnvVars.setAll(originalVars + newVars)
+    return try {
+        block()
+    } finally {
+        editableEnvVars.setAll(originalVars)
+    }
+}
+
+/**
+ * Runs the given [block] with modified JVM system properties. The properties given in [newProps] are merged onto the
+ * existing system properties, adding values that did not exist previously and updating values which did exist. After
+ * the block completes, system properties will be restored to their previous values. This method may be nested multiple
+ * times to apply/restore hierarchical overrides.
+ *
+ * **Caution**: This method is not thread-safe as system properties are global for a JVM instance.
+ *
+ * @param newProps The new system properties to merge onto the existing system properties.
+ * @param block The block to execute with updated system properties
+ */
+public suspend inline fun <T> withSystemProperties(
+    newProps: Map<String, String>,
+    crossinline block: suspend () -> T,
+): T {
+    val originalProps = System.getProperties()
+    val replacementProps = Properties().apply {
+        putAll(originalProps)
+        putAll(newProps)
+    }
+    System.setProperties(replacementProps)
+    return try {
+        block()
+    } finally {
+        System.setProperties(originalProps)
+    }
+}

runtime/testing/jvm/src/aws/smithy/kotlin/runtime/testing/TestAnnotationsJVM.kt

@@ -4,6 +4,7 @@
  */
 
 package aws.smithy.kotlin.runtime.testing
+import org.junit.jupiter.api.TestInstance
 import org.junit.jupiter.api.condition.DisabledOnOs
 import org.junit.jupiter.api.condition.OS
 
@@ -17,3 +18,7 @@ public actual typealias AfterAll = org.junit.jupiter.api.AfterAll
 @Retention(AnnotationRetention.RUNTIME)
 @Target(AnnotationTarget.FUNCTION)
 public actual annotation class IgnoreNative { /* no-op on JVM */ }
+
+public actual typealias TestInstance = TestInstance
+
+public actual typealias TestLifecycle = TestInstance.Lifecycle

runtime/testing/native/src/aws/smithy/kotlin/runtime/testing/TestAnnotationsNative.kt

@@ -10,3 +10,12 @@ public actual typealias BeforeAll = kotlin.test.BeforeClass
 public actual typealias AfterAll = kotlin.test.AfterClass
 
 public actual typealias IgnoreNative = kotlin.test.Ignore
+
+// Effectively ignored on K/N. This is fine because we only use this to enable non-static @BeforeAll/@AfterAll methods
+// on JVM.
+public actual annotation class TestInstance(actual val value: TestLifecycle)
+
+public actual enum class TestLifecycle {
+    PER_CLASS,
+    PER_METHOD,
+}