Better explain the env_case test

EliahKagan · EliahKagan · commit 74d9c08bc4b8 · 2023-09-11T23:11:45.000-04:00
This expands and adds comments in
test_it_avoids_upcasing_unrelated_environment_variable_names and
its supporting fixture env_case.py so it is clear exactly what is
being tested and how/why the test works to test it.
diff --git a/test/fixtures/env_case.py b/test/fixtures/env_case.py
@@ -1,13 +1,18 @@
+# Steps 3 and 4 for test_it_avoids_upcasing_unrelated_environment_variable_names.
+
 import subprocess
 import sys
 
+# Step 3a: Import the module, in case that upcases the environment variable name.
 import git
 
 
 _, working_dir, env_var_name = sys.argv
 
-# Importing git should be enough, but this really makes sure Git.execute is called.
+# Step 3b: Use Git.execute explicitly, in case that upcases the environment variable.
+#          (Importing git should be enough, but this ensures Git.execute is called.)
 repo = git.Repo(working_dir)  # Hold the reference.
 git.Git(repo.working_dir).execute(["git", "version"])
 
+# Step 4: Create the non-Python grandchild that accesses the variable case-sensitively.
 print(subprocess.check_output(["set", env_var_name], shell=True, text=True))
diff --git a/test/test_git.py b/test/test_git.py
@@ -98,15 +98,25 @@ def test_it_avoids_upcasing_unrelated_environment_variable_names(self):
         old_name = "28f425ca_d5d8_4257_b013_8d63166c8158"
         if old_name == old_name.upper():
             raise RuntimeError("test bug or strange locale: old_name invariant under upcasing")
-        os.putenv(old_name, "1")  # It has to be done this lower-level way to set it lower-case.
 
+        # Step 1: Set the environment variable in this parent process. Because os.putenv is a thin
+        #         wrapper around a system API, os.environ never sees the variable in this parent
+        #         process, so the name is not upcased even on Windows.
+        os.putenv(old_name, "1")
+
+        # Step 2: Create the child process that inherits the environment variable. It will see it
+        #         in os.environ with an upcased name, but if it is not mutated through os.environ
+        #         then it will pass it on to its own child processes with the original name. The
+        #         child process will use GitPython, and we are testing that it passes the variable
+        #         with the exact original name to its own child processes.
         cmdline = [
             sys.executable,
             fixture_path("env_case.py"),
             self.rorepo.working_dir,
             old_name,
         ]
-        pair_text = subprocess.check_output(cmdline, shell=False, text=True)
+        pair_text = subprocess.check_output(cmdline, shell=False, text=True)  # Steps 3 and 4.
+
         new_name = pair_text.split("=")[0]
         self.assertEqual(new_name, old_name)
 
