test fixes and learning more

Author: eleanorjboyd

.github/instructions/generic.instructions.md

@@ -6,31 +6,35 @@ Provide project context and coding guidelines that AI should follow when generat
 
 ## Localization
 
--   Localize all user-facing messages using VS Code’s `l10n` API.
--   Internal log messages do not require localization.
+- Localize all user-facing messages using VS Code’s `l10n` API.
+- Internal log messages do not require localization.
 
 ## Logging
 
--   Use the extension’s logging utilities (`traceLog`, `traceVerbose`) for internal logs.
--   Do not use `console.log` or `console.warn` for logging.
+- Use the extension’s logging utilities (`traceLog`, `traceVerbose`) for internal logs.
+- Do not use `console.log` or `console.warn` for logging.
 
 ## Settings Precedence
 
--   Always consider VS Code settings precedence:
+- Always consider VS Code settings precedence:
     1. Workspace folder
     2. Workspace
     3. User/global
--   Remove or update settings from the highest precedence scope first.
+- Remove or update settings from the highest precedence scope first.
 
 ## Error Handling & User Notifications
 
--   Avoid showing the same error message multiple times in a session; track state with a module-level variable.
--   Use clear, actionable error messages and offer relevant buttons (e.g., "Open settings", "Close").
+- Avoid showing the same error message multiple times in a session; track state with a module-level variable.
+- Use clear, actionable error messages and offer relevant buttons (e.g., "Open settings", "Close").
 
 ## Documentation
 
--   Add clear docstrings to public functions, describing their purpose, parameters, and behavior.
+- Add clear docstrings to public functions, describing their purpose, parameters, and behavior.
+
+## Cross-Platform Path Handling
+
+**CRITICAL**: This extension runs on Windows, macOS, and Linux. NEVER hardcode POSIX-style paths.
 
 ## Learnings
 
--   When using `getConfiguration().inspect()`, always pass a scope/Uri to `getConfiguration(section, scope)` — otherwise `workspaceFolderValue` will be `undefined` because VS Code doesn't know which folder to inspect (1)
+- When using `getConfiguration().inspect()`, always pass a scope/Uri to `getConfiguration(section, scope)` — otherwise `workspaceFolderValue` will be `undefined` because VS Code doesn't know which folder to inspect (1)

.github/instructions/testing-workflow.instructions.md

@@ -33,6 +33,23 @@ This guide covers the full testing lifecycle:
 - Test failures or compilation errors
 - Coverage reports or test output analysis
 
+## 🚨 CRITICAL: Common Mistakes (Read First!)
+
+These mistakes have occurred REPEATEDLY. Check this list BEFORE writing any test code:
+
+| Mistake                                        | Fix                                                                |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| Hardcoded POSIX paths like `'/test/workspace'` | Use `'.'` for relative paths, `Uri.file(x).fsPath` for comparisons |
+| Stubbing `workspace.getConfiguration` directly | Stub the wrapper `workspaceApis.getConfiguration` instead          |
+| Stubbing `workspace.workspaceFolders` property | Stub wrapper function `workspaceApis.getWorkspaceFolders()`        |
+| Comparing `fsPath` to raw string               | Compare `fsPath` to `Uri.file(expected).fsPath`                    |
+
+**Pre-flight checklist before completing test work:**
+
+- [ ] All paths use `Uri.file().fsPath` (no hardcoded `/path/to/x`)
+- [ ] All VS Code API stubs use wrapper modules, not `vscode.*` directly
+- [ ] Tests pass on both Windows and POSIX
+
 ## Test Types
 
 When implementing tests as an AI agent, choose between two main types:
@@ -579,4 +596,5 @@ envConfig.inspect
 - Create shared mock helpers (e.g., `createMockLogOutputChannel()`) instead of duplicating mock setup across multiple test files (1)
 - Always compile tests (`npm run compile-tests`) before running them after adding new test cases - test counts will be wrong if running against stale compiled output (1)
 - Never create "documentation tests" that just `assert.ok(true)` — if mocking limitations prevent testing, either test a different layer that IS mockable, or skip the test entirely with a clear explanation (1)
-- When stubbing vscode APIs in tests via wrapper modules (e.g., `workspaceApis`), the production code must also use those wrappers — sinon cannot stub properties directly on the vscode namespace like `workspace.workspaceFolders`, so both production and test code must reference the same stubbable wrapper functions (1)
+- **REPEATED**: When stubbing vscode APIs in tests via wrapper modules (e.g., `workspaceApis`), the production code must also use those wrappers — sinon cannot stub properties directly on the vscode namespace like `workspace.workspaceFolders`, so both production and test code must reference the same stubbable wrapper functions (3)
+- **REPEATED**: Use OS-agnostic path handling in tests: use `'.'` for relative paths in configs (NOT `/test/workspace`), compare `fsPath` to `Uri.file(expected).fsPath` (NOT raw strings). This breaks on Windows every time! (5)

src/test/features/interpreterSelection.unit.test.ts

@@ -122,7 +122,7 @@ suite('Interpreter Selection - Priority Chain', () => {
             sandbox.stub(workspaceApis, 'getConfiguration').returns(
                 createMockConfig([
                     {
-                        path: '/test/workspace',
+                        path: '.',
                         envManager: 'ms-python.python:venv',
                         packageManager: 'ms-python.python:pip',
                     },
@@ -301,7 +301,7 @@ suite('Interpreter Selection - Priority Chain', () => {
             );
             assert.strictEqual(
                 result.environment.environmentPath?.fsPath,
-                userPyenvPath,
+                Uri.file(userPyenvPath).fsPath,
                 'environmentPath should use user configured path',
             );
         });
@@ -1117,10 +1117,11 @@ suite('Interpreter Selection - Settings over Cache Priority', () => {
 
     test('should use pythonProjects manager even when defaultEnvManager is set', async () => {
         // This test verifies pythonProjects[] has highest priority (Priority 1 over Priority 2)
+        // Use '.' as relative path - path.resolve(workspaceFolder, '.') equals workspaceFolder
         sandbox.stub(workspaceApis, 'getConfiguration').returns(
             createMockConfig([
                 {
-                    path: '/test/workspace',
+                    path: '.',
                     envManager: 'ms-python.python:venv', // Project says venv
                     packageManager: 'ms-python.python:pip',
                 },
@@ -1357,16 +1358,15 @@ suite('Interpreter Selection - Multi-Root Workspace', () => {
         ]);
 
         // Different pythonProjects settings for each folder
+        // Use '.' as relative path - path.resolve(workspaceFolder, '.') equals workspaceFolder
         sandbox.stub(workspaceApis, 'getConfiguration').callsFake((_section?: string, scope?: unknown) => {
             const scopeUri = scope as Uri | undefined;
             if (scopeUri?.fsPath === folder1Uri.fsPath) {
-                return createMockConfig([
-                    { path: '/workspace/folder1', envManager: 'ms-python.python:venv' },
-                ]) as WorkspaceConfiguration;
+                return createMockConfig([{ path: '.', envManager: 'ms-python.python:venv' }]) as WorkspaceConfiguration;
             }
             if (scopeUri?.fsPath === folder2Uri.fsPath) {
                 return createMockConfig([
-                    { path: '/workspace/folder2', envManager: 'ms-python.python:system' },
+                    { path: '.', envManager: 'ms-python.python:system' },
                 ]) as WorkspaceConfiguration;
             }
             return createMockConfig([]) as WorkspaceConfiguration;