@@ -35,7 +35,7 @@ This document describes the Vortex tooling package - a collection of PHP helper
3535│ │ ├── UnitTestCase.php # Base test case
3636│ │ ├── ExitException.php # Exit exception for testing
3737│ │ ├── ExitMockTest.php # Exit mocking tests
38- │ │ ├── EnvTest .php # Environment tests
38+ │ │ ├── DotenvTest .php # Environment tests
3939│ │ └── SelfTest.php # Self-tests for core functions
4040│ └── Traits/
4141│ └── MockTrait.php # Mock infrastructure (passthru, quit, request)
@@ -108,6 +108,96 @@ The package uses **three types of tests**:
1081082 . ** Self Tests** (` tests/Self/ ` ) - Test the mock infrastructure itself
1091093 . ** Fixture Scripts** (` tests/Fixtures/ ` ) - External scripts for integration testing
110110
111+ ### Test Development Best Practices
112+
113+ ** Environment Variable Management** :
114+ - Use ` $this->envSet('VAR', 'value') ` for setting single variables
115+ - Use ` $this->envSetMultiple(['VAR1' => 'value1', 'VAR2' => 'value2']) ` for multiple variables
116+ - Use ` $this->envUnset('VAR') ` for unsetting single variables
117+ - Use ` $this->envUnsetMultiple(['VAR1', 'VAR2']) ` for unsetting multiple variables
118+ - Use ` $this->envUnsetPrefix('PREFIX_') ` for unsetting all variables with a prefix
119+ - NEVER use ` putenv() ` directly - always use EnvTrait methods for automatic cleanup
120+
121+ ** Documentation** :
122+ - Data provider method names should start with ` dataProvider ` prefix (e.g., ` dataProviderHttpMethods ` , not ` providerHttpMethods ` )
123+ - Block comments (PHPDoc /** ... * /) are ONLY allowed on test classes, NOT on methods
124+ - Do NOT add block comments to test methods, data provider methods, or helper methods
125+ - Inline comments (// ...) are acceptable for explaining logic within method bodies
126+ - Keep test method names descriptive enough that block comments aren't needed
127+
128+ ** Allowed Comments** :
129+ ``` php
130+ // ✅ CORRECT - Block comment on class only
131+ /**
132+ * Tests for webhook notification script.
133+ */
134+ #[RunTestsInSeparateProcesses]
135+ class NotifyWebhookTest extends UnitTestCase {
136+
137+ // ✅ CORRECT - No block comment on methods, only inline comments
138+ public function testSuccessfulNotification(): void {
139+ // Mock HTTP request
140+ $this->mockRequest('https://example.com', [], ['status' => 200]);
141+ // ... test code ...
142+ }
143+
144+ // ✅ CORRECT - No block comment on data provider
145+ public static function dataProviderHttpMethods(): array {
146+ return ['POST' => ['POST'], 'GET' => ['GET']];
147+ }
148+ }
149+
150+ // ❌ INCORRECT - Block comments on methods
151+ /**
152+ * Test successful notification. // <-- Remove this
153+ * /
154+ public function testSuccessfulNotification(): void {
155+ // ...
156+ }
157+ ```
158+
159+ **Example**:
160+ ```php
161+ protected function setUp(): void {
162+ parent::setUp();
163+ require_once __DIR__ . ' /../../src/helpers.php' ;
164+
165+ // ✅ CORRECT - Use envSetMultiple for multiple variables
166+ $this- >envSetMultiple([
167+ 'VORTEX_NOTIFY_PROJECT' => 'test-project',
168+ 'VORTEX_NOTIFY_LABEL' => 'main',
169+ 'VORTEX_NOTIFY_URL' => 'https://example.com',
170+ ]);
171+ }
172+
173+ public function testCustomConfiguration(): void {
174+ // ✅ CORRECT - Use envSet for single variable
175+ $this->envSet('VORTEX_NOTIFY_CUSTOM', 'value');
176+
177+ // ... test code ...
178+ }
179+
180+ public function testFallbackVariables(): void {
181+ // ✅ CORRECT - Use envUnsetMultiple for unsetting multiple variables
182+ $this->envUnsetMultiple([
183+ 'VORTEX_NOTIFY_SPECIFIC',
184+ 'VORTEX_NOTIFY_ANOTHER',
185+ ]);
186+
187+ // ✅ CORRECT - Set fallback variable
188+ $this->envSet('VORTEX_NOTIFY_GENERIC', 'fallback-value');
189+
190+ // ... test code ...
191+ }
192+
193+ public static function dataProviderHttpMethods(): array {
194+ return [
195+ 'POST' => ['POST'],
196+ 'GET' => ['GET'],
197+ ];
198+ }
199+ ```
200+
111201### Mock System (MockTrait.php)
112202
113203The package provides a comprehensive mocking system for testing scripts that use:
0 commit comments