updates

Author: eleanorjboyd

.github/instructions/testing_feature_area.instructions.md

@@ -185,6 +185,22 @@ Project-based testing enables multi-project workspace support where each Python
     - For unittest: `discovery.py` uses `PROJECT_ROOT_PATH` as `top_level_dir` and `cwd_override` to root the test tree at the project directory.
 6. **Test tree**: Each project gets its own root node in the Test Explorer, with test IDs scoped by project ID using the `@@vsc@@` separator (defined in `projectUtils.ts`).
 
+### Nested project handling: pytest vs unittest
+
+**pytest** supports the `--ignore` flag to exclude paths during test collection. When nested projects are detected, parent projects automatically receive `--ignore` flags for child project paths. This ensures each test appears under exactly one project in the test tree.
+
+**unittest** does not support path exclusion during `discover()`. Therefore, tests in nested project directories may appear under multiple project roots (both the parent and the child project). This is **expected behavior** for unittest:
+
+-   Each project discovers and displays all tests it finds within its directory structure
+-   There is no deduplication or collision detection
+-   Users may see the same test file under multiple project roots if their project structure has nesting
+
+This approach was chosen because:
+
+1. unittest's `TestLoader.discover()` has no built-in path exclusion mechanism
+2. Implementing custom exclusion would add significant complexity with minimal benefit
+3. The existing approach is transparent and predictable - each project shows what it finds
+
 ### Logging prefix
 
 All project-based testing logs use the `[test-by-project]` prefix for easy filtering in the output channel.
@@ -193,15 +209,19 @@ All project-based testing logs use the `[test-by-project]` prefix for easy filte
 
 -   Python side:
     -   `python_files/vscode_pytest/__init__.py` — `get_test_root_path()` function and `PROJECT_ROOT_PATH` environment variable for pytest.
-    -   `python_files/unittestadapter/discovery.py` — `discover_tests()` with `cwd_override` parameter and `PROJECT_ROOT_PATH` handling for unittest.
--   TypeScript: `testProjectRegistry.ts`, `projectAdapter.ts`, `projectUtils.ts`, and the discovery adapters.
+    -   `python_files/unittestadapter/discovery.py` — `discover_tests()` with `cwd_override` parameter and `PROJECT_ROOT_PATH` handling for unittest discovery.
+    -   `python_files/unittestadapter/execution.py` — `run_tests()` with `cwd_override` parameter and `PROJECT_ROOT_PATH` handling for unittest execution.
+-   TypeScript: `testProjectRegistry.ts`, `projectAdapter.ts`, `projectUtils.ts`, and the discovery/execution adapters.
 
 ### Tests
 
 -   `src/test/testing/testController/common/testProjectRegistry.unit.test.ts` — TestProjectRegistry tests
 -   `src/test/testing/testController/common/projectUtils.unit.test.ts` — Project utility function tests
 -   `python_files/tests/pytestadapter/test_discovery.py` — pytest PROJECT_ROOT_PATH tests (see `test_project_root_path_env_var()` and `test_symlink_with_project_root_path()`)
--   `python_files/tests/unittestadapter/test_discovery.py` — unittest `cwd_override` / PROJECT_ROOT_PATH tests
+-   `python_files/tests/unittestadapter/test_discovery.py` — unittest `cwd_override` / PROJECT_ROOT_PATH discovery tests
+-   `python_files/tests/unittestadapter/test_execution.py` — unittest `cwd_override` / PROJECT_ROOT_PATH execution tests
+-   `src/test/testing/testController/unittest/testDiscoveryAdapter.unit.test.ts` — unittest discovery adapter PROJECT_ROOT_PATH tests
+-   `src/test/testing/testController/unittest/testExecutionAdapter.unit.test.ts` — unittest execution adapter PROJECT_ROOT_PATH tests
 
 ## Coverage support (how it works)
 

python_files/tests/unittestadapter/test_execution.py

@@ -341,3 +341,134 @@ def test_basic_run_django():
             assert id_result["outcome"] == "failure"
         else:
             assert id_result["outcome"] == "success"
+
+
+def test_project_root_path_with_cwd_override(mock_send_run_data) -> None:  # noqa: ARG001
+    """Test unittest execution with cwd_override parameter.
+
+    This simulates project-based testing where the cwd in the payload should be
+    the project root (cwd_override) rather than the start_dir.
+
+    When cwd_override is provided:
+    - The cwd in the response should match cwd_override
+    - Test execution should still work correctly with start_dir
+    """
+    # Use unittest_folder as our "project" directory
+    project_path = TEST_DATA_PATH / "unittest_folder"
+    start_dir = os.fsdecode(project_path)
+    pattern = "test_add*"
+    test_ids = [
+        "test_add.TestAddFunction.test_add_positive_numbers",
+    ]
+
+    os.environ["TEST_RUN_PIPE"] = "fake"
+
+    # Call run_tests with cwd_override to simulate PROJECT_ROOT_PATH
+    actual = run_tests(
+        start_dir,
+        test_ids,
+        pattern,
+        None,
+        1,
+        None,
+        cwd_override=start_dir,
+    )
+
+    assert actual["status"] == "success"
+    # cwd in response should match the cwd_override (project root)
+    assert actual["cwd"] == os.fsdecode(project_path), (
+        f"Expected cwd '{os.fsdecode(project_path)}', got '{actual['cwd']}'"
+    )
+    assert actual["result"] is not None
+    assert test_ids[0] in actual["result"]
+    assert actual["result"][test_ids[0]]["outcome"] == "success"
+
+
+def test_project_root_path_with_different_cwd_and_start_dir() -> None:
+    """Test unittest execution where cwd_override differs from start_dir.
+
+    This simulates the scenario where:
+    - start_dir points to a subfolder where tests are located
+    - cwd_override (PROJECT_ROOT_PATH) points to the project root
+
+    The cwd in the response should be the project root, while execution
+    still runs from the start_dir.
+    """
+    # Use utils_nested_cases as our test case
+    project_path = TEST_DATA_PATH / "utils_nested_cases"
+    start_dir = os.fsdecode(project_path)
+    pattern = "*"
+    test_ids = [
+        "file_one.CaseTwoFileOne.test_one",
+    ]
+
+    os.environ["TEST_RUN_PIPE"] = "fake"
+
+    # Call run_tests with cwd_override set to project root
+    actual = run_tests(
+        start_dir,
+        test_ids,
+        pattern,
+        None,
+        1,
+        None,
+        cwd_override=os.fsdecode(project_path),
+    )
+
+    assert actual["status"] == "success"
+    # cwd should be the project root (cwd_override)
+    assert actual["cwd"] == os.fsdecode(project_path), (
+        f"Expected cwd '{os.fsdecode(project_path)}', got '{actual['cwd']}'"
+    )
+    assert actual["result"] is not None
+    assert test_ids[0] in actual["result"]
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="Symlinks require elevated privileges on Windows",
+)
+def test_symlink_with_project_root_path(mock_send_run_data) -> None:  # noqa: ARG001
+    """Test unittest execution with both symlink and cwd_override set.
+
+    This tests the combination of:
+    1. A symlinked test directory
+    2. cwd_override (PROJECT_ROOT_PATH) set to the symlink path
+
+    This simulates project-based testing where the project root is a symlink,
+    ensuring execution payloads correctly use the symlink path.
+    """
+    with helpers.create_symlink(TEST_DATA_PATH, "unittest_folder", "symlink_unittest_exec") as (
+        _source,
+        destination,
+    ):
+        assert destination.is_symlink()
+
+        # Run execution with:
+        # - start_dir pointing to the symlink destination
+        # - cwd_override set to the symlink destination (simulating PROJECT_ROOT_PATH)
+        start_dir = os.fsdecode(destination)
+        pattern = "test_add*"
+        test_ids = [
+            "test_add.TestAddFunction.test_add_positive_numbers",
+        ]
+
+        os.environ["TEST_RUN_PIPE"] = "fake"
+
+        actual = run_tests(
+            start_dir,
+            test_ids,
+            pattern,
+            None,
+            1,
+            None,
+            cwd_override=start_dir,
+        )
+
+        assert actual["status"] == "success", (
+            f"Status is not 'success', error is: {actual.get('error')}"
+        )
+        # cwd should be the symlink path (cwd_override)
+        assert actual["cwd"] == os.fsdecode(destination), (
+            f"CWD does not match symlink path: expected {os.fsdecode(destination)}, got {actual['cwd']}"
+        )

python_files/unittestadapter/execution.py

@@ -36,6 +36,9 @@
 ErrorType = Union[Tuple[Type[BaseException], BaseException, TracebackType], Tuple[None, None, None]]
 test_run_pipe = ""
 START_DIR = ""
+# PROJECT_ROOT_PATH: Used for project-based testing to override cwd in payload
+# When set, this should be used as the cwd in all execution payloads
+PROJECT_ROOT_PATH = None  # type: Optional[str]
 
 
 class TestOutcomeEnum(str, enum.Enum):
@@ -191,8 +194,22 @@ def run_tests(
     verbosity: int,
     failfast: Optional[bool],  # noqa: FBT001
     locals_: Optional[bool] = None,  # noqa: FBT001
+    cwd_override: Optional[str] = None,
 ) -> ExecutionPayloadDict:
-    cwd = os.path.abspath(start_dir)  # noqa: PTH100
+    """Run unittests and return the execution payload.
+
+    Args:
+        start_dir: Directory where test discovery starts
+        test_ids: List of test IDs to run
+        pattern: Pattern to match test files
+        top_level_dir: Top-level directory for test tree hierarchy
+        verbosity: Verbosity level for test output
+        failfast: Stop on first failure
+        locals_: Show local variables in tracebacks
+        cwd_override: Optional override for the cwd in the response payload
+                     (used for project-based testing to set project root)
+    """
+    cwd = os.path.abspath(cwd_override or start_dir)  # noqa: PTH100
     if "/" in start_dir:  #  is a subdir
         parent_dir = os.path.dirname(start_dir)  # noqa: PTH120
         sys.path.insert(0, parent_dir)
@@ -259,7 +276,8 @@ def run_tests(
 
 def send_run_data(raw_data, test_run_pipe):
     status = raw_data["outcome"]
-    cwd = os.path.abspath(START_DIR)  # noqa: PTH100
+    # Use PROJECT_ROOT_PATH if set (project-based testing), otherwise use START_DIR
+    cwd = os.path.abspath(PROJECT_ROOT_PATH or START_DIR)  # noqa: PTH100
     test_id = raw_data["subtest"] or raw_data["test"]
     test_dict = {}
     test_dict[test_id] = raw_data
@@ -348,7 +366,19 @@ def send_run_data(raw_data, test_run_pipe):
         args = argv[index + 1 :] or []
         django_execution_runner(manage_py_path, test_ids, args)
     else:
+        # Check for PROJECT_ROOT_PATH environment variable (project-based testing).
+        # When set, this overrides the cwd in the payload to match the project root.
+        project_root_path = os.environ.get("PROJECT_ROOT_PATH")
+        if project_root_path:
+            # Update the module-level variable for send_run_data to use
+            # pylint: disable=global-statement
+            globals()["PROJECT_ROOT_PATH"] = project_root_path
+            print(
+                f"PROJECT_ROOT_PATH is set, using {project_root_path} as cwd for execution payload"
+            )
+
         # Perform regular unittest execution.
+        # Pass project_root_path as cwd_override so the payload's cwd matches the project root.
         payload = run_tests(
             start_dir,
             test_ids,
@@ -357,6 +387,7 @@ def send_run_data(raw_data, test_run_pipe):
             verbosity,
             failfast,
             locals_,
+            cwd_override=project_root_path,
         )
 
     if is_coverage_run:

src/client/testing/testController/common/types.ts

@@ -183,6 +183,7 @@ export interface ITestExecutionAdapter {
         executionFactory: IPythonExecutionFactory,
         debugLauncher?: ITestDebugLauncher,
         interpreter?: PythonEnvironment,
+        project?: ProjectAdapter,
     ): Promise<void>;
 }
 

src/client/testing/testController/pytest/pytestExecutionAdapter.ts

@@ -21,6 +21,7 @@ import * as utils from '../common/utils';
 import { IEnvironmentVariablesProvider } from '../../../common/variables/types';
 import { PythonEnvironment } from '../../../pythonEnvironments/info';
 import { getEnvironment, runInBackground, useEnvExtension } from '../../../envExt/api.internal';
+import { ProjectAdapter } from '../common/projectAdapter';
 
 export class PytestTestExecutionAdapter implements ITestExecutionAdapter {
     constructor(
@@ -37,6 +38,7 @@ export class PytestTestExecutionAdapter implements ITestExecutionAdapter {
         executionFactory: IPythonExecutionFactory,
         debugLauncher?: ITestDebugLauncher,
         interpreter?: PythonEnvironment,
+        project?: ProjectAdapter,
     ): Promise<void> {
         const deferredTillServerClose: Deferred<void> = utils.createTestingDeferred();
 
@@ -71,6 +73,7 @@ export class PytestTestExecutionAdapter implements ITestExecutionAdapter {
                 executionFactory,
                 debugLauncher,
                 interpreter,
+                project,
             );
         } finally {
             await deferredTillServerClose.promise;
@@ -87,6 +90,7 @@ export class PytestTestExecutionAdapter implements ITestExecutionAdapter {
         executionFactory: IPythonExecutionFactory,
         debugLauncher?: ITestDebugLauncher,
         interpreter?: PythonEnvironment,
+        project?: ProjectAdapter,
     ): Promise<ExecutionTestPayload> {
         const relativePathToPytest = 'python_files';
         const fullPluginPath = path.join(EXTENSION_ROOT_DIR, relativePathToPytest);
@@ -102,6 +106,13 @@ export class PytestTestExecutionAdapter implements ITestExecutionAdapter {
         const pythonPathCommand = [fullPluginPath, ...pythonPathParts].join(path.delimiter);
         mutableEnv.PYTHONPATH = pythonPathCommand;
         mutableEnv.TEST_RUN_PIPE = resultNamedPipeName;
+
+        // Set PROJECT_ROOT_PATH for project-based testing (tells Python where to root the test tree)
+        if (project) {
+            mutableEnv.PROJECT_ROOT_PATH = project.projectUri.fsPath;
+            traceInfo(`[test-by-project] Setting PROJECT_ROOT_PATH=${project.projectUri.fsPath} for pytest execution`);
+        }
+
         if (profileKind && profileKind === TestRunProfileKind.Coverage) {
             mutableEnv.COVERAGE_ENABLED = 'True';
         }

src/client/testing/testController/unittest/testExecutionAdapter.ts

@@ -27,6 +27,7 @@ import { ITestDebugLauncher, LaunchOptions } from '../../common/types';
 import { UNITTEST_PROVIDER } from '../../common/constants';
 import * as utils from '../common/utils';
 import { getEnvironment, runInBackground, useEnvExtension } from '../../../envExt/api.internal';
+import { ProjectAdapter } from '../common/projectAdapter';
 
 /**
  * Wrapper Class for unittest test execution. This is where we call `runTestCommand`?
@@ -46,6 +47,8 @@ export class UnittestTestExecutionAdapter implements ITestExecutionAdapter {
         runInstance: TestRun,
         executionFactory: IPythonExecutionFactory,
         debugLauncher?: ITestDebugLauncher,
+        _interpreter?: unknown, // Not used - kept for interface compatibility
+        project?: ProjectAdapter,
     ): Promise<void> {
         // deferredTillServerClose awaits named pipe server close
         const deferredTillServerClose: Deferred<void> = utils.createTestingDeferred();
@@ -80,6 +83,7 @@ export class UnittestTestExecutionAdapter implements ITestExecutionAdapter {
                 profileKind,
                 executionFactory,
                 debugLauncher,
+                project,
             );
         } catch (error) {
             traceError(`Error in running unittest tests: ${error}`);
@@ -97,6 +101,7 @@ export class UnittestTestExecutionAdapter implements ITestExecutionAdapter {
         profileKind: boolean | TestRunProfileKind | undefined,
         executionFactory: IPythonExecutionFactory,
         debugLauncher?: ITestDebugLauncher,
+        project?: ProjectAdapter,
     ): Promise<ExecutionTestPayload> {
         const settings = this.configSettings.getSettings(uri);
         const { unittestArgs } = settings.testing;
@@ -111,6 +116,15 @@ export class UnittestTestExecutionAdapter implements ITestExecutionAdapter {
         const pythonPathCommand = [cwd, ...pythonPathParts].join(path.delimiter);
         mutableEnv.PYTHONPATH = pythonPathCommand;
         mutableEnv.TEST_RUN_PIPE = resultNamedPipeName;
+
+        // Set PROJECT_ROOT_PATH for project-based testing (tells Python where to root the test tree)
+        if (project) {
+            mutableEnv.PROJECT_ROOT_PATH = project.projectUri.fsPath;
+            traceInfo(
+                `[test-by-project] Setting PROJECT_ROOT_PATH=${project.projectUri.fsPath} for unittest execution`,
+            );
+        }
+
         if (profileKind && profileKind === TestRunProfileKind.Coverage) {
             mutableEnv.COVERAGE_ENABLED = cwd;
         }

src/client/testing/testController/workspaceTestAdapter.ts

@@ -15,6 +15,7 @@ import { IPythonExecutionFactory } from '../../common/process/types';
 import { ITestDebugLauncher } from '../common/types';
 import { buildErrorNodeOptions } from './common/utils';
 import { PythonEnvironment } from '../../pythonEnvironments/info';
+import { ProjectAdapter } from './common/projectAdapter';
 
 /**
  * This class exposes a test-provider-agnostic way of discovering tests.
@@ -47,6 +48,7 @@ export class WorkspaceTestAdapter {
         profileKind?: boolean | TestRunProfileKind,
         debugLauncher?: ITestDebugLauncher,
         interpreter?: PythonEnvironment,
+        project?: ProjectAdapter,
     ): Promise<void> {
         if (this.executing) {
             traceError('Test execution already in progress, not starting a new one.');
@@ -84,6 +86,7 @@ export class WorkspaceTestAdapter {
                 executionFactory,
                 debugLauncher,
                 interpreter,
+                project,
             );
             deferred.resolve();
         } catch (ex) {