Added plan.md for EnvTrait refactoring.

Author: AlexSkrypnyk

.vortex/installer/plan.md

@@ -0,0 +1,239 @@
+# Plan: Refactor Unit Tests to Use EnvTrait for Environment Variable Management
+
+## Problem Statement
+
+Some unit tests use `putenv()` directly instead of `EnvTrait` methods. This bypasses automatic environment variable cleanup, causing environment variables to leak between tests and pollute child processes spawned by `#[RunInSeparateProcess]`.
+
+## Root Cause
+
+- Unit tests run in the main PHPUnit process
+- Child processes (spawned by `#[RunInSeparateProcess]`) inherit the parent's environment
+- Tests that use raw `putenv()` don't get automatic cleanup via `EnvTrait`
+- If a test fails before its manual cleanup code runs, env vars leak
+
+## Solution
+
+Add `EnvTrait` to `UnitTestCase` base class so all unit tests automatically get:
+- `envSet($name, $value)` - sets env var and tracks for cleanup
+- `envUnset($name)` - unsets env var
+- Automatic cleanup in `tearDown()` even if test fails
+
+## Implementation Steps
+
+### Step 1: Add EnvTrait to UnitTestCase
+
+**File:** `.vortex/installer/tests/Unit/UnitTestCase.php`
+
+Add the import and trait usage:
+
+```php
+use AlexSkrypnyk\PhpunitHelpers\Traits\EnvTrait;
+
+abstract class UnitTestCase extends UpstreamUnitTestCase {
+  use SerializableClosureTrait;
+  use DirectoryAssertionsTrait;
+  use FileAssertionsTrait;
+  use EnvTrait;  // Add this
+```
+
+### Step 2: Update ConfigTest.php
+
+**File:** `.vortex/installer/tests/Unit/ConfigTest.php`
+
+Replace `putenv()` calls in setUp():
+```php
+// Before
+foreach ($constants as $constant) {
+  unset($_ENV[$constant]);
+  if (getenv($constant) !== FALSE) {
+    putenv($constant);
+  }
+}
+
+// After
+foreach ($constants as $constant) {
+  unset($_ENV[$constant]);
+  static::envUnset($constant);
+}
+```
+
+Replace `putenv()` calls in test methods:
+- `testSetWithEnvironmentVariable()`: Replace `putenv($env_key . '=' . $env_value)` with `static::envSet($env_key, $env_value)` and remove manual cleanup
+- `testSetSkipEnvironment()`: Same as above
+- `testEnvironmentVariablePrecedenceInConstructor()`: Replace `putenv(Config::ROOT . '=/env/root')` etc. with `static::envSet(Config::ROOT, '/env/root')` and remove manual cleanup
+
+### Step 3: Update TuiTest.php
+
+**File:** `.vortex/installer/tests/Unit/TuiTest.php`
+
+Update `testBox()`:
+```php
+// Before
+$original_columns = getenv('COLUMNS');
+try {
+  if ($terminal_width !== NULL) {
+    putenv('COLUMNS=' . $terminal_width);
+  }
+  // ... test code ...
+} finally {
+  // Restore environment.
+  if ($original_columns !== FALSE) {
+    putenv('COLUMNS=' . $original_columns);
+  } else {
+    putenv('COLUMNS');
+  }
+}
+
+// After (no try/finally needed)
+if ($terminal_width !== NULL) {
+  static::envSet('COLUMNS', (string) $terminal_width);
+}
+// ... test code ...
+```
+
+Update `testUtfPadding()`:
+```php
+// Before
+$original_terminal_emulator = getenv('TERMINAL_EMULATOR');
+$original_term_program = getenv('TERM_PROGRAM');
+try {
+  if ($terminal_emulator !== NULL) {
+    putenv('TERMINAL_EMULATOR=' . $terminal_emulator);
+  } else {
+    putenv('TERMINAL_EMULATOR');
+  }
+  // ... similar for TERM_PROGRAM ...
+} finally {
+  // restore logic
+}
+
+// After
+if ($terminal_emulator !== NULL) {
+  static::envSet('TERMINAL_EMULATOR', $terminal_emulator);
+} else {
+  static::envUnset('TERMINAL_EMULATOR');
+}
+if ($term_program !== NULL) {
+  static::envSet('TERM_PROGRAM', $term_program);
+} else {
+  static::envUnset('TERM_PROGRAM');
+}
+// ... test code (no finally block needed) ...
+```
+
+### Step 4: Update EnvTest.php
+
+**File:** `.vortex/installer/tests/Unit/EnvTest.php`
+
+Update `testGet()`:
+```php
+// Before
+putenv(sprintf('%s=%s', $name, $expected));
+$this->assertSame($expected, Env::get($name, $default));
+putenv($name);
+
+// After
+static::envSet($name, $expected);
+$this->assertSame($expected, Env::get($name, $default));
+```
+
+Update `testGetFromDotenv()`:
+```php
+// Before
+putenv(sprintf('%s=%s', $name, $expected));
+// ...
+putenv($name);
+
+// After
+if ($expected !== NULL) {
+  static::envSet($name, $expected);
+} else {
+  static::envUnset($name);
+}
+// ... (no manual cleanup needed)
+```
+
+Update `testPutFromDotenv()`:
+```php
+// Before
+if ($value) {
+  putenv(sprintf('%s=%s', $name, $value));
+  // ...
+}
+
+// After
+if ($value) {
+  static::envSet($name, $value);
+  // ...
+}
+```
+
+Update `testPut()`:
+```php
+// Before
+Env::put($name, $value);
+$this->assertEquals($value, getenv($name));
+putenv($name);
+
+// After
+Env::put($name, $value);
+$this->assertEquals($value, getenv($name));
+// Note: Env::put() uses native putenv(), track it for cleanup
+static::envUnset($name);
+```
+
+Update `testGetFromDotenvReturnsParsedValue()`:
+```php
+// Before
+if (getenv('TEST_VAR') !== FALSE) {
+  putenv('TEST_VAR');
+}
+
+// After
+static::envUnset('TEST_VAR');
+```
+
+### Step 5: Update DownloaderTest.php
+
+**File:** `.vortex/installer/tests/Unit/Downloader/DownloaderTest.php`
+
+Update `testDiscoverLatestReleaseRemoteWithGithubToken()`:
+```php
+// Before
+putenv('GITHUB_TOKEN=test_token_12345');
+// ... test code ...
+putenv('GITHUB_TOKEN');
+
+// After
+static::envSet('GITHUB_TOKEN', 'test_token_12345');
+// ... test code (no manual cleanup needed) ...
+```
+
+Update `testDownloadArchiveWithGithubToken()`:
+```php
+// Before
+putenv('GITHUB_TOKEN=test_token_67890');
+// ... test code ...
+putenv('GITHUB_TOKEN');
+
+// After
+static::envSet('GITHUB_TOKEN', 'test_token_67890');
+// ... test code (no manual cleanup needed) ...
+```
+
+## Verification
+
+After making changes, run all unit tests:
+
+```bash
+cd .vortex/installer
+./vendor/bin/phpunit tests/Unit --no-coverage
+```
+
+All 1037 tests should pass.
+
+## Notes
+
+- The `EnvTrait` automatically tracks all env vars set via `envSet()` and cleans them up in `tearDown()`
+- This cleanup happens even if a test fails, preventing env var leakage
+- The trait also provides `envUnsetPrefix($prefix)` for bulk cleanup (already used in functional tests)