support env variables

Author: martypitt

docs/pages/_meta.ts

@@ -3,5 +3,6 @@ export default {
     "index": "Getting started",
     "writing-tests" : "Writing tests",
     "stubbing" : "Stubbing responses",
+    "environment-variables" : "Environment variables",
     "faq" : "Tips and FAQ's"
 };

docs/pages/environment-variables.mdx

@@ -0,0 +1,68 @@
+---
+title: Environment variables
+---
+import { Callout } from 'nextra/components'
+
+# Configuring environment variables
+
+Orbital supports using [environment variables inside annotations](https://orbitalhq.com/docs/deploying/configuring-orbital#environment-variables-in-annotations),
+which can lead to compilation errors if not provided.
+
+## Global config
+To use default, global config, simply drop an `env.conf` file in the `test-resources` directory:
+
+```
+/
+├── src
+│   └── schema.taxi
+├── test
+│   └── SchemaSpec.kt
+└── test-resources
+    └── env.conf <--- env.conf goes here
+taxi.conf
+```
+
+Orbital uses [HOCON](https://github.com/lightbend/config#examples-of-hocon) format for config files. You can read more about configuring Orbital [here](https://orbitalhq.com/docs/deploying/configuring-orbital)
+
+Here's a sample config file:
+
+```env.conf
+TransactionsTopicName = Transactions
+```
+
+Hocon is very flexible, you can use a variety of styles:
+ * `foo.bar=10`
+ * `foo : 10`
+ * `foo=10, bar=10`
+
+Read more in the [HOCON docs](https://github.com/lightbend/config?tab=readme-ov-file#examples-of-hocon)
+
+## Overriding environment variables per-spec
+
+Environment variables can be overridden within a spec by calling one of these functions:
+
+```kotlin
+    fun environmentVariables(vararg pairs: Pair<String, String>)
+    fun environmentVariables(env: Map<String, String>)
+    fun env(key: String, value: String)
+```
+
+<Callout>Environment variables are set per-spec, and must be set *before* the `describe()` block. Attempting to modify environment variables in a `describe` or `it( .. )` block will result in an error</Callout>
+
+```kotlin
+class OverridingGlobalEnvVariablesSpec : OrbitalSpec({
+    // Override a single env variable
+    env("click-events-topic-name", "clickstream")
+
+    // alternatively, override a bunch:
+    environmentVariables(
+        "MyTopic" to "Foo",
+        "AnotherTopic" to "Bar"
+    )
+    describe("overriding global env config variables") {
+        it("should compile using the overridden env variable") {
+            // test continues
+        }
+    }
+})
+```

docs/pages/index.mdx

@@ -35,6 +35,20 @@ You also need a `settings.gradle.kts` (but can be blank)
 // This file can be left blank
 ```
 
+Here's the directory structure:
+
+```
+├── src
+│   └── schema.taxi
+├── test
+│   └── SchemaSpec.kt
+└── test-resources (Optional)
+    └── env.conf (Optional)
+taxi.conf
+build.gradle.kts
+settings.gradle.kts (Often blank)
+```
+
 Then, to write your first test, create a folder `test` next to your `src` folder.
 By convention, these are named ending in `Spec.kt` or `Test.kt`.
 

docs/theme.config.tsx

@@ -32,7 +32,7 @@ export default {
     docsRepositoryBase: 'https://github.com/orbitalapi/preflight/docs',
     footer: {
         content: (
-            <span>Built by &nbsp;<a className="underline" href="https://orbitalhq.com" target="_blank">Orbital</a>, to make demos suck less.</span>
+            <span>Built by &nbsp;<a className="underline" href="https://orbitalhq.com" target="_blank">Orbital</a>.</span>
         )
     },
     head: () => {

preflight-core/preflight-runtime/src/main/kotlin/com/orbitalhq/preflight/dsl/EnvVariablesLoader.kt

@@ -0,0 +1,22 @@
+package com.orbitalhq.preflight.dsl
+
+import com.typesafe.config.ConfigFactory
+
+/**
+ * Loads global env variables from test-resources/env.conf
+ */
+object EnvVariablesLoader {
+
+    fun loadGlobalEnvVariables(): Map<String, String> {
+        return ConfigFactory.load("env.conf")
+            .root()
+            .unwrapped()
+            .mapValues { (_,value) -> value.toString() }
+    }
+
+    private fun tryLoadFromClasspath(): java.io.InputStream? {
+        return PreflightExtension::class.java.getResourceAsStream("env.conf")
+    }
+
+
+}

preflight-core/preflight-runtime/src/main/kotlin/com/orbitalhq/preflight/dsl/OrbitalSpec.kt

@@ -25,6 +25,10 @@ abstract class OrbitalSpec(body: OrbitalSpec.() -> Unit) : DescribeSpec() {
         this.body()
     }
 
+    fun environmentVariables(vararg pairs: Pair<String, String>) = preflight.environmentVariables(*pairs)
+    fun environmentVariables(env: Map<String, String>) = preflight.environmentVariables(env)
+    fun env(key: String, value: String) = preflight.env(key,value)
+
     /**
      * Provides access to the compiled taxi document.
      * This is lower-level than Orbital's schema object

preflight-core/preflight-runtime/src/main/kotlin/com/orbitalhq/preflight/dsl/PreflightExtension.kt

@@ -68,11 +68,7 @@ class PreflightExtension(val projectRoot: Path = Paths.get("./")) : BeforeSpecLi
 
 
     override suspend fun beforeSpec(spec: Spec) {
-        val loader = TaxiPackageLoader.forDirectoryContainingTaxiFile(projectRoot.absolute().normalize())
-        this.taxiProject = loader.load()
-
-        sourcePackage = loadSourcePackage(this.taxiProject.packageRootPath!!)
-
+        envVariableContainer.markImmutable()
         withClue("Taxi project should compile without errors") {
             val taxiSchema = try {
                 TaxiSchema.from(

preflight-core/preflight-runtime/src/main/kotlin/com/orbitalhq/preflight/dsl/SpecEnvVariables.kt

@@ -0,0 +1,51 @@
+package com.orbitalhq.preflight.dsl
+
+interface EnvVariableContainer {
+    fun environmentVariables(vararg pairs: Pair<String, String>)
+    fun environmentVariables(env: Map<String, String>)
+    fun env(key: String, value: String)
+    fun markImmutable()
+
+    val envVariables:Map<String,String>
+}
+
+class SpecEnvVariables private constructor(globalVariables:Map<String,String>) : EnvVariableContainer  {
+    private val variables = globalVariables.toMutableMap()
+    private var isMutable = true
+    companion object {
+        fun newInstance():SpecEnvVariables {
+            return SpecEnvVariables(EnvVariablesLoader.loadGlobalEnvVariables())
+        }
+    }
+
+    override val envVariables: Map<String, String>
+        get() {
+            return variables.toMap()
+        }
+
+    override fun markImmutable() {
+        this.isMutable = false
+    }
+
+    private fun requireIsMutable() {
+        require(isMutable) { "Modifying env variables after the test has started is not allowed. Configure the env variables before the describe { ... } block"}
+    }
+    /**
+     * Configure environment variables for this specific test spec.
+     * These will override any global defaults with the same key.
+     */
+    override fun environmentVariables(vararg pairs: Pair<String, String>) {
+        requireIsMutable()
+        variables.putAll(pairs)
+    }
+
+    override fun environmentVariables(env: Map<String, String>) {
+        requireIsMutable()
+        variables.putAll(env)
+    }
+
+    override fun env(key: String, value: String) {
+        requireIsMutable()
+        variables[key] = value
+    }
+}