Multi‐Project Testing in VS Code

The Python extension now supports multi-project workspaces, where each Python project within a workspace gets its own test tree and Python environment. This document explains how multi-project testing works and what you can expect to see in the Test Explorer.

What is multi-project testing?

A multi-project workspace is a VS Code workspace that contains multiple Python projects—each with its own pyproject.toml, virtual environment, or package structure. For example:

my-workspace/
├── backend/           # Django API project
│   ├── pyproject.toml
│   ├── tests/
│   └── .venv/
├── frontend-utils/    # Shared utilities library
│   ├── pyproject.toml
│   ├── tests/
│   └── .venv/
└── ml-pipeline/       # Data science project
    ├── tests/
    └── .venv/

With multi-project testing, each project appears as a separate root in the Test Explorer, using its own Python interpreter and test configuration.

Note: To see additional documentation on Projects see https://github.com/microsoft/vscode-python-environments/wiki/Making-and-Managing-Python-Projects.

How tests appear in Test Explorer

Python Projects panel shows each project with its environment	Test Explorer groups tests by project

Each project root contains its discovered tests, organized by file, class, and function—just like single-project workspaces.

Requirements

Multi-project testing requires:

• Python Environments extension (installed and enabled)
• pytest or unittest as your test framework
• Projects recognized by the Python Environments API (typically having a pyproject.toml)

Note: If the Python Environments extension is unavailable, testing falls back to "legacy mode" where the entire workspace is treated as a single test root.

How it works (high-level)

1. Project discovery: When you open a workspace, the extension queries the Python Environments API to find all Python projects.

2. Environment resolution: Each project uses its own Python environment (virtual environment, conda environment, etc.) as configured.

3. Test discovery: Tests are discovered for each project independently. The extension sets a PROJECT_ROOT_PATH so that test IDs and paths are scoped correctly to each project.

4. Nested project handling: If projects are nested (e.g., a monorepo with sub-packages), pytest automatically excludes nested child projects to avoid duplicate test discovery (with the --ignore flag). See Current limitations for unittest behavior.

What you'll see differently

Single-project workspace	Multi-project workspace
One test tree root	Multiple test tree roots (one per project)
Tests use workspace interpreter	Each project uses its own interpreter

Troubleshooting

Tests aren't appearing for a project

• Verify the project has a pyproject.toml or is otherwise recognized by the Python Environments extension
• Check that pytest or unittest is configured and installed in the project's environment
• Look for [test-by-project] messages in the Python output channel for diagnostic information

Tests appear duplicated

This can happen if a parent project discovers tests from nested child projects.

For pytest: The extension should handle this automatically. If you still see duplicates:

• Ensure your pytest configuration uses appropriate --ignore flags
• Check that nested projects are properly recognized as separate projects

For unittest: Due to how unittest discovers tests, nested projects are not automatically excluded. See Current limitations for more details and workarounds.

Falling back to legacy mode

If you see all tests under a single workspace root instead of per-project roots, the extension may have fallen back to legacy mode because the Python Environments extension isn't installed or enabled. You can add "python.useEnvironmentsExtension" to true to your settings to always have the environment extension enabled.

Current limitations

• unittest does not exclude nested projects: When using unittest with nested projects (projects inside other projects), the parent project may discover and display tests from child projects, leading to duplicate test entries. This is a known limitation of unittest's discovery mechanism. To avoid this, consider structuring your workspace so unittest projects are not nested, or use pytest which handles nested projects automatically.
• Multi-project testing requires the Python Environments extension API to be available.

---

This feature was introduced in the Python extension to better support monorepos, microservices architectures, and complex workspace layouts where multiple Python projects coexist.