feat(test-utils): Stay closer to upstream SystemEnvironmentExtensions

In particular, stick to a configurable `OverrideMode` to be able to
share this with ORT Server which depends on that feature.

Signed-off-by: Sebastian Schuberth <[email protected]>

Author: sschuberth

gradle/libs.versions.toml

@@ -129,6 +129,7 @@ jsonSchemaValidator = { module = "com.networknt:json-schema-validator", version.
 kotest-assertions-core = { module = "io.kotest:kotest-assertions-core", version.ref = "kotest" }
 kotest-assertions-json = { module = "io.kotest:kotest-assertions-json", version.ref = "kotest" }
 kotest-assertions-table = { module = "io.kotest:kotest-assertions-table", version.ref = "kotest" }
+kotest-extensions = { module = "io.kotest:kotest-extensions", version.ref = "kotest" }
 kotest-extensions-junitXml = { module = "io.kotest:kotest-extensions-junitxml", version.ref = "kotest" }
 kotest-framework-datatest = { module = "io.kotest:kotest-framework-datatest", version.ref = "kotest" }
 kotest-framework-engine = { module = "io.kotest:kotest-framework-engine", version.ref = "kotest" }

utils/test/build.gradle.kts

@@ -27,6 +27,7 @@ dependencies {
     api(projects.plugins.versionControlSystems.gitVersionControlSystem)
 
     api(libs.kotest.assertions.core)
+    api(libs.kotest.extensions)
     api(libs.logbackClassic) {
         because("Transitively export this to consumers so they do not have to declare a logger implementation.")
     }

utils/test/src/main/kotlin/SystemEnvironmentExtensions.kt

@@ -23,8 +23,49 @@
 
 package org.ossreviewtoolkit.utils.test
 
+import io.kotest.extensions.system.OverrideMode
+import io.kotest.extensions.system.OverrideMode.SetOrError
+
 import java.lang.reflect.Field
 
+/**
+ * Modifies System Environment with chosen key and value
+ *
+ * This is a helper function for code that uses Environment Variables. It changes the specific [key] from [System.getenv]
+ * with the specified [value], only during the execution of [block].
+ *
+ * To do this, this function uses a trick that makes the System Environment editable, and changes [key]. Any previous
+ * environment (anything not overridden) will also be in the environment. If the chosen key is in the environment,
+ * it will be changed according to [mode]. If the chosen key is not in the environment, it will be included.
+ *
+ * After the execution of [block], the environment is set to what it was before.
+ *
+ * **ATTENTION**: This code is susceptible to race conditions. If you attempt to change the environment while it was
+ * already changed, the result is inconsistent, as the System Environment Map is a single map.
+ */
+inline fun <T> withEnvironment(key: String, value: String?, mode: OverrideMode = SetOrError, block: () -> T): T {
+    return withEnvironment(key to value, mode, block)
+}
+
+/**
+ * Modifies System Environment with chosen key and value
+ *
+ * This is a helper function for code that uses Environment Variables. It changes the specific key from [System.getenv]
+ * with the specified value, only during the execution of [block].
+ *
+ * To do this, this function uses a trick that makes the System Environment editable, and changes key. Any previous
+ * environment (anything not overridden) will also be in the environment. If the chosen key is in the environment,
+ * it will be changed according to [mode]. If the chosen key is not in the environment, it will be included.
+ *
+ * After the execution of [block], the environment is set to what it was before.
+ *
+ * **ATTENTION**: This code is susceptible to race conditions. If you attempt to change the environment while it was
+ * already changed, the result is inconsistent, as the System Environment Map is a single map.
+ */
+inline fun <T> withEnvironment(environment: Pair<String, String?>, mode: OverrideMode = SetOrError, block: () -> T): T {
+    return withEnvironment(mapOf(environment), mode, block)
+}
+
 /**
  * Modifies System Environment with chosen keys and values
  *
@@ -33,22 +74,22 @@ import java.lang.reflect.Field
  *
  * To do this, this function uses a trick that makes the System Environment editable, and changes key. Any previous
  * environment (anything not overridden) will also be in the environment. If the chosen key is in the environment,
- * it will be overridden. If the chosen key is not in the environment, it will be included.
+ * it will be changed according to [mode]. If the chosen key is not in the environment, it will be included.
  *
  * After the execution of [block], the environment is set to what it was before.
  *
  * **ATTENTION**: This code is susceptible to race conditions. If you attempt to change the environment while it was
  * already changed, the result is inconsistent, as the System Environment Map is a single map.
  */
-inline fun <T> withEnvironment(environment: Map<String, String?>, block: () -> T): T {
+inline fun <T> withEnvironment(environment: Map<String, String?>, mode: OverrideMode = SetOrError, block: () -> T): T {
     val isWindows = "windows" in System.getProperty("os.name").orEmpty().lowercase()
     val originalEnvironment = if (isWindows) {
         System.getenv().toSortedMap(String.CASE_INSENSITIVE_ORDER)
     } else {
         System.getenv().toMap()
     }
 
-    setEnvironmentMap(setOrOverride(originalEnvironment, environment))
+    setEnvironmentMap(mode.override(originalEnvironment, environment))
 
     try {
         return block()
@@ -103,6 +144,3 @@ private fun MutableMap<String, String>.putReplacingNulls(map: Map<String, String
         if (value == null) remove(key) else put(key, value)
     }
 }
-
-fun setOrOverride(originalValues: Map<String, String>, newValues: Map<String, String?>) =
-    originalValues.toMutableMap().apply { putReplacingNulls(newValues) }