test: create test harness with locked environment (#59)

* test: create test harness with locked environment

Setup single-process integration testing with a utility module. Designed
so multiple tests can be run without the need for separate processes.
In practice, this means new tests will not need a new file. It allows
for easily repeating checks across similar functions e.g. `dotenv()` and
`from_filename(".env")`.

The heart of the utility module is the `TestEnv` struct which enables
controlled setup of a temporary testing environment. When using the
`test_in_env` functions, access to the process' environment is
effectively locked using a mutex, reset, and then the `TestEnv` is
created.

Also included:

- a set of default keys and values
- valid and invalid default envfile contents
- assertions with contextual output when tests fail

* test: fix format! args for rust 1.56.1

* test: handle NotUnicode in harness asserts

* test: add more comments to harness functions

dotenv/Cargo.toml

@@ -29,6 +29,7 @@ clap = { version = "3.2", optional = true }
 
 [dev-dependencies]
 tempfile = "3.3.0"
+once_cell = "1.16.0"
 
 [features]
 cli = ["clap"]

dotenv/tests/integration/main.rs

@@ -0,0 +1 @@
+mod util;

dotenv/tests/integration/util/mod.rs

@@ -0,0 +1,69 @@
+#![allow(dead_code)]
+
+mod testenv;
+
+use std::env::{self, VarError};
+
+pub use testenv::*;
+
+/// Default key used in envfile
+pub const TEST_KEY: &str = "TESTKEY";
+/// Default value used in envfile
+pub const TEST_VALUE: &str = "test_val";
+
+/// Default existing key set before test is run
+pub const TEST_EXISTING_KEY: &str = "TEST_EXISTING_KEY";
+/// Default existing value set before test is run
+pub const TEST_EXISTING_VALUE: &str = "from_env";
+/// Default overriding value in envfile
+pub const TEST_OVERRIDING_VALUE: &str = "from_file";
+
+#[inline(always)]
+pub fn create_default_envfile() -> String {
+    format!(
+        "{}={}\\n{}={}",
+        TEST_KEY, TEST_VALUE, TEST_EXISTING_KEY, TEST_OVERRIDING_VALUE
+    )
+}
+
+/// missing equals
+#[inline(always)]
+pub fn create_invalid_envfile() -> String {
+    format!(
+        "{}{}\\n{}{}",
+        TEST_KEY, TEST_VALUE, TEST_EXISTING_KEY, TEST_OVERRIDING_VALUE
+    )
+}
+
+/// Assert that an environment variable is set and has the expected value.
+pub fn assert_env_var(key: &str, expected: &str) {
+    match env::var(key) {
+        Ok(actual) => assert_eq!(
+            expected, actual,
+            "\n\nFor Environment Variable `{}`:\n  EXPECTED: `{}`\n    ACTUAL: `{}`\n",
+            key, expected, actual
+        ),
+        Err(VarError::NotPresent) => panic!("env var `{}` not found", key),
+        Err(VarError::NotUnicode(val)) => panic!(
+            "env var `{}` currently has invalid unicode: `{}`",
+            key,
+            val.to_string_lossy()
+        ),
+    }
+}
+
+/// Assert that an environment variable is not currently set.
+pub fn assert_env_var_unset(key: &str) {
+    match env::var(key) {
+        Ok(actual) => panic!(
+            "env var `{}` should not be set, currently it is: `{}`",
+            key, actual
+        ),
+        Err(VarError::NotUnicode(val)) => panic!(
+            "env var `{}` should not be set, currently has invalid unicode: `{}`",
+            key,
+            val.to_string_lossy()
+        ),
+        _ => (),
+    }
+}