Starting with v2026.2.0 `unittest` test discovery does not work for custom `--start-directory` (aka `-s`) in `python.testing.unittestArgs`

[i-ky]

Type: Bug

Behaviour

In a project using unittest and relying on custom --start-directory (see .vscode/settings.json below) test discovery fails with ImportError: Start directory is not importable: '/workspaces/project/subdir'.

{
  "python.testing.pytestEnabled": false,
  "python.testing.unittestArgs": [
    "--start-directory",
    "subdir/"
  ],
  "python.testing.unittestEnabled": true
}

Expected behaviour should be consistent with running

python3 -m unittest discover --start-directory subdir/

Steps to reproduce:

1. Open workspace
2. Navigate to Testing tab on the left
3. Try to discover tests
4. Observe Unittest Discovery Error

I've tried different versions of the extension and the issue was introduced between v2026.0.0 and v2026.2.0, most likely by #25780. After this change the extension seems to unconditionally override --top-level-directory (aka -t) from python.testing.unittestArgs with workspace root via PROJECT_ROOT_PATH environment variable:

vscode-python/python_files/unittestadapter/discovery.py

Lines 144 to 149 in ef1b469

	# Check for PROJECT_ROOT_PATH environment variable (project-based testing).
	# When set, this overrides top_level_dir to root the test tree at the project directory.
	project_root_path = os.environ.get("PROJECT_ROOT_PATH")
	if project_root_path:
	top_level_dir = project_root_path

If the directory to start discovery is not importable from workspace root (the new top level directory) this becomes an issue.
See unittest docs:

In order to be compatible with test discovery, all of the test files must be modules or packages importable from the top-level directory of the project...

I've also noticed that existing extension's unit tests cover only the trivial case of "python.testing.unittestArgs": ["-s", "."]. That's probably why the issue with ["-s", "something/else/"] went unnoticed.

Diagnostic data

Data below is from a project using Linux devcontainer, but the issue is reproducible on macOS host as well. And in a different project too. So I wouldn't pay too much attention to the specific of the environment listed below.

Output for Python in the Output panel (View→Output, change the drop-down the upper-right of the Output panel to Python)

2026-07-09 21:24:59.207 [info] Experiment 'pythonSurveyNotificationcf' is active
2026-07-09 21:24:59.207 [info] Environment discovery is managed by the Python Environments extension (ms-python.vscode-python-envs). Check the "Python Environments" output channel for environment-specific logs.
2026-07-09 21:24:59.389 [info] [test-by-project] Activating project-based testing mode
2026-07-09 21:24:59.389 [info] [test-by-project] Discovering projects for workspace: /workspaces/project
2026-07-09 21:24:59.389 [info] [test-by-project] Found 1 total Python projects from API
2026-07-09 21:24:59.389 [info] [test-by-project] Filtered to 1 projects in workspace
2026-07-09 21:24:59.389 [info] [test-by-project] Creating adapter for: project at file:///workspaces/project
2026-07-09 21:24:59.498 [info] > pyenv which python
2026-07-09 21:24:59.498 [info] cwd: .
2026-07-09 21:24:59.582 [info] [test-by-project] Registered 1 project(s) for /workspaces/project
2026-07-09 21:24:59.582 [info] [test-by-project] Activated 1 project(s) for /workspaces/project
2026-07-09 21:24:59.582 [info] [test-by-project] Subscribed to Python project changes
2026-07-09 21:24:59.583 [info] Active interpreter [/workspaces/project]:  /usr/local/bin/python
2026-07-09 21:25:00.987 [info] Starting Pylance language server.
2026-07-09 21:25:22.236 [info] [test-by-project] Cleaned up 0 test items for workspace: /workspaces/project
2026-07-09 21:25:22.236 [info] [test-by-project] Discovering projects for workspace: /workspaces/project
2026-07-09 21:25:22.236 [info] [test-by-project] Found 1 total Python projects from API
2026-07-09 21:25:22.236 [info] [test-by-project] Filtered to 1 projects in workspace
2026-07-09 21:25:22.236 [info] [test-by-project] Creating adapter for: project at file:///workspaces/project
2026-07-09 21:25:22.236 [info] [test-by-project] Registered 1 project(s) for /workspaces/project
2026-07-09 21:25:22.245 [info] [test-by-project] Starting discovery for 1 project(s) in workspace
2026-07-09 21:25:22.245 [info] [test-by-project] Discovering tests for project: project (Python 3.13)
2026-07-09 21:25:22.248 [info] Environment variables set for unittest discovery: TEST_RUN_PIPE=/tmp/python-test-discovery-2eb38c8fc0f5a9af5368
2026-07-09 21:25:22.248 [info] [test-by-project] Setting PROJECT_ROOT_PATH=/workspaces/project for unittest discovery
2026-07-09 21:25:22.248 [info] Using environment extension for unittest discovery in workspace /workspaces/project
2026-07-09 21:25:22.252 [info] Started unittest discovery subprocess (environment extension) for workspace /workspaces/project
2026-07-09 21:25:22.323 [info] PROJECT_ROOT_PATH is set, using /workspaces/project as top_level_dir for discovery

2026-07-09 21:25:22.325 [error] Unittest test discovery error for workspace:  /workspaces/project 
 Traceback (most recent call last):
  File "/home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/python_files/unittestadapter/discovery.py", line 80, in discover_tests
    suite = loader.discover(start_dir, pattern, top_level_dir)
  File "/usr/local/lib/python3.13/unittest/loader.py", line 308, in discover
    raise ImportError('Start directory is not importable: %r' % start_dir)
ImportError: Start directory is not importable: '/workspaces/project/subdir'

2026-07-09 21:25:22.325 [warning] --- [test-by-project] Import error during unittest discovery for project at /workspaces/project. This may be caused by test files in nested project directories that require different dependencies. If these tests are discovered successfully by their own project (with the correct Python environment), this error can be safely ignored. To avoid this, consider excluding nested project paths from parent project discovery. ---
2026-07-09 21:25:22.325 [error] Test Discovery named pipe /tmp/python-test-discovery-2eb38c8fc0f5a9af5368 error: [TypeError: Cannot read properties of null (reading 'path')
	at e (/home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/out/client/extension.js:2:991831)
	at t.TestDiscoveryHandler.processDiscovery (/home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/out/client/extension.js:2:968443)
	at u.resolveDiscovery (/home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/out/client/extension.js:2:965238)
	at /home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/out/client/extension.js:2:958373
	at b.callback (/home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/out/client/extension.js:2:991030)
	at Object.thunk (/home/vscode/.vscode-server/extensions/ms-python.python-2026.4.0-linux-arm64/out/client/extension.js:2:2064800)]
2026-07-09 21:25:22.330 [info] Unittest discovery completed for workspace /workspaces/project
2026-07-09 21:25:22.330 [info] [test-by-project] Project project (Python 3.13) discovery completed
2026-07-09 21:25:22.330 [info] [test-by-project] Discovery complete: 1/1 projects completed

Extension version: 2026.4.0
VS Code version: Code 1.127.0 (4fe60c8b1cdac1c4c174f2fb180d0d758272d713, 2026-06-30T10:52:33+02:00)
OS version: Darwin arm64 25.5.0
Modes:
Remote OS version: Linux arm64 6.12.76-linuxkit

• Python version (& distribution if applicable, e.g. Anaconda): 3.13.14.final.0
• Type of virtual environment used (e.g. conda, venv, virtualenv, etc.): System
• Value of the python.languageServer setting: Default

User Settings

languageServer: "Pylance"

testing
• unittestArgs: "<placeholder>"
• unittestEnabled: true

Installed Extensions

Extension Name	Extension Id	Version
autopep8	ms-	2026.4.0
copilot-chat	Git	0.55.0
debugpy	ms-	2026.6.0
js-debug	ms-	1.117.0
jsts-chat-features	Typ	0.0.4
python	ms-	2026.4.0
ruff	cha	2026.56.0
vscode-eslint	dba	3.0.24
vscode-js-profile-table	ms-	1.0.10
vscode-pylance	ms-	2026.2.1
vscode-python-envs	ms-	1.36.0

System Info

Item	Value
CPUs	Apple M4 Max (14 x 2400)
GPU Status	2d_canvas: enabled GPU0: VENDOR= 0x106b [Google Inc. (Apple)], DEVICE=0x0000 [ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Max, Version 26.5.2 (Build 25F84))], DRIVER_VENDOR=Apple, DRIVER_VERSION=26.5.2 ACTIVE Machine model name: Mac Machine model version: 16.6 direct_rendering_display_compositor: disabled_off_ok gpu_compositing: enabled multiple_raster_threads: enabled_on opengl: enabled_on rasterization: enabled raw_draw: disabled_off_ok skia_graphite: enabled_on trees_in_viz: disabled_off video_decode: enabled video_encode: enabled webgl: enabled webgpu: enabled webnn: disabled_off
Load (avg)	3, 3, 2
Memory (System)	36.00GB (0.28GB free)
Process Argv	. --crash-reporter-id 684fb168-0444-4033-bb04-7818c72bdb86
Screen Reader	no
VM	0%

Item	Value
Remote	Dev Container @ desktop-linux
OS	Linux arm64 6.12.76-linuxkit
CPUs	unknown (14 x 0)
Memory (System)	31.29GB (28.55GB free)
VM	0%

A/B Experiments

vsliv368cf:30146710
pythonvspyt551cf:31249601
binariesv615:30325510
nativeloc1:31344060
dwcopilot:31170013
dwoutputs:31242946
copilot_t_ci:31333650
e5gg6876:31282496
pythonrdcb7:31342333
6518g693:31463988
aj953862:31281341
6abeh943:31336334
envsactivate1:31538736
editstats-enabled:31346257
cloudbuttont:31379625
3efgi100_wstrepl:31403338
839jf696:31457053
ec5jj548:31422691
cp_cls_t_966_ss:31526232
8hhj4413:31478653
ge8j1254_inline_auto_hint_haiku:31490510
38bie571_auto:31478677
cp_cls_c_1081:31454833
conptydll_true:31498968
ia-use-proxy-models-svc:31452481
e9c30283:31461165
test_control1:31471004
46204921:31447328
capi_axe_098a3278:31544981
idci7584:31464702
e3e4d672:31494082
ei9d7968:31496641
nes-extended-on:31455476
chat:31457767
8hig5102:31480529
ah:31461780
89g7j272:31518289
7e187181:31503455
i2gc6536:31499202
52612955:31516516
ghj88844:31499326
ddid_c:31478207
hmra_i5g22:31518061
ie3bb177:31543534
7df3h592:31512476
cp_cls_t_1082:31535311
logging_enabled_new:31498466
db5d2638:31499441
jb_cp_cls_t_632:31543129
748c7209:31512887
32d76977:31512328
ha629193:31508444
cdk-lw-on:31524445
f9bf7985:31543584
a1ije391_t:31540920
hgf2d445:31529595
41836166:31537719
prpt_srch:31518468
jbcp_cls_pctr_t:31531130
61138546:31518536
cp_intellij_t_nes:31533504
gf14b233:31526830
nes-curr-leftover-1500:31538366
h561g132:31533256
session_8:31532895
ihg5j128:31534457
jh7i3328:31546038
7g2b5551:31542111
sandbox-ui-on-2:31543161
nes-nc-nf-2k:31546582