test: cover registered package manager lifecycles (#1704)

## Summary

Adds a package-manager-centric integration baseline that intentionally
precedes and de-risks #1686, so the package-manager command refactor is
exercised against behavior established on `main`.

- drives one stateful install/list/direct-package/uninstall lifecycle
per active profile
- uses unique disposable projects and manager-owned disposable
environments
- exercises the live registered manager instances through a
runtime-gated integration-test bridge
- guards registry completeness so every registered package-manager ID
has an active fixture or explicit deferral
- covers normal Pip execution and Conda when their runtime prerequisites
are available
- records an uncached baseline instead of assuming a newly created
environment is empty
- restores workspace-scoped configuration from `inspect()` snapshots and
performs guarded failure-safe cleanup
- defers Poetry pending a Poetry-owned project/lockfile lifecycle
- defers uv-backed Pip because changing the machine-scoped selection
reliably within one extension host was not stable on `main`, while
available-version lookup would also introduce `uv tool run pip` network
seeding
- pins the disposable integration-test user profile to normal Pip
execution

## Validation

- `npm run compile`
- `npm run compile-tests`
- `npm run lint`
- `npm run unittest`
- targeted `packageManagement.integration.test.js`: 3 passing, 2
prerequisite skips locally
- Pip skipped because quick create selected Python 3.15.0 alpha, whose
bundled Pip metadata is incomplete
  - Conda skipped because Conda is not installed
- reviewer specialist: clean, no Critical or Important findings

The active Pip and Conda fixtures require package-index/network access
when their runtime prerequisites are present.

Fixes #1701

---------

Copilot-Session: 6b2fe9b5-38ea-442f-b07a-b6c71134d480
Copilot-Session: 3fd1a810-6840-4ac9-ac33-c8a9fda4bfc4

Author: edvilme

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

@@ -606,3 +606,4 @@ envConfig.inspect
 - **Never skip tests to hide infrastructure problems**: If tests require native binaries (like `pet`), the CI workflow must build/download them. Skipping tests when infrastructure is missing gives false confidence. Build from source (like vscode-python does) rather than skipping. Tests should fail clearly when something is wrong (2)
 - **No retries for masking flakiness**: Mocha `retries` should not be used to mask test flakiness. If a test is flaky, fix the root cause. Retries hide real issues and slow down CI (1)
 - **pet binary is required for environment manager registration**: The smoke/E2E/integration tests require the `pet` binary from `microsoft/python-environment-tools` to be built and placed in `python-env-tools/bin/`. Without it, `waitForApiReady()` will timeout because managers never register. CI must build pet from source using `cargo build --release --package pet` (2)
+- **Check exact project registration with `getPythonProjects()`**: `getPythonProject(uri)` can return a containing parent project, so it cannot prove that a nested project was registered or unregistered (1)

.github/workflows/pr-check.yml

@@ -335,6 +335,14 @@ jobs:
         if: runner.os != 'Linux'
         run: npm run integration-test
 
+      - name: Run Package Manager Network Integration Tests
+        if: runner.os == 'Linux' && matrix.python-version == '3.12'
+        uses: GabrielBB/xvfb-action@86d97bde4a65fe9b290c0b3fb92c2c4ed0e5302d # v1.6
+        env:
+          VSC_PYTHON_PACKAGE_NETWORK_TEST: '1'
+        with:
+          run: npm run integration-test -- --grep "Package Manager"
+
   integration-tests-multiroot:
     name: Integration Tests (Multi-Root)
     runs-on: ${{ matrix.os }}

.github/workflows/push-check.yml

@@ -335,3 +335,11 @@ jobs:
       - name: Run Integration Tests (non-Linux)
         if: runner.os != 'Linux'
         run: npm run integration-test
+
+      - name: Run Package Manager Network Integration Tests
+        if: runner.os == 'Linux' && matrix.python-version == '3.12'
+        uses: GabrielBB/xvfb-action@86d97bde4a65fe9b290c0b3fb92c2c4ed0e5302d # v1.6
+        env:
+          VSC_PYTHON_PACKAGE_NETWORK_TEST: '1'
+        with:
+          run: npm run integration-test -- --grep "Package Manager"

api/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to the `@vscode/python-environments` API package are documen
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0]
+
+### Added
+
+- Added `PackageManagementInteractionOptions` with an optional `runHeadless?: boolean` property, mixed into `PackageManagementOptions`. When `true`, package management operations run without any user prompts or interaction — steps that would normally require input, such as selecting packages to install when none are specified, are skipped instead of prompting — for automated or headless scenarios such as integration tests.
+- Added `RemoveEnvironmentOptions` with an optional `runHeadless?: boolean` property to remove environments without a confirmation prompt in automated or headless scenarios.
+
 ## [1.1.0]
 
 ### Added

api/package-lock.json

@@ -1,7 +1,7 @@
 {
     "name": "@vscode/python-environments",
     "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "author": {
         "name": "Microsoft Corporation"
     },

api/package.json

@@ -329,6 +329,17 @@ export interface QuickCreateConfig {
     readonly detail?: string;
 }
 
+/**
+ * Options controlling environment removal.
+ */
+export interface RemoveEnvironmentOptions {
+    /**
+     * When `true`, removes the environment without prompting for confirmation.
+     * Intended for automated or headless scenarios. Defaults to `false`.
+     */
+    runHeadless?: boolean;
+}
+
 /**
  * Interface representing an environment manager.
  */
@@ -392,7 +403,7 @@ export interface EnvironmentManager {
      * @param environment - The Python environment to remove.
      * @returns A promise that resolves when the environment is removed.
      */
-    remove?(environment: PythonEnvironment): Promise<void>;
+    remove?(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
 
     /**
      * Refreshes the list of Python environments within the specified scope.
@@ -739,49 +750,62 @@ export interface GetPackagesOptions {
 }
 
 /**
- * Options for package management.
+ * Options controlling user interaction during package management operations.
  */
-export type PackageManagementOptions =
-    | {
-          /**
-           * Upgrade the packages if it is already installed.
-           */
-          upgrade?: boolean;
-
-          /**
-           * Show option to skip package installation
-           */
-          showSkipOption?: boolean;
-          /**
-           * The list of packages to install.
-           */
-          install: string[];
-
-          /**
-           * The list of packages to uninstall.
-           */
-          uninstall?: string[];
-      }
-    | {
-          /**
-           * Upgrade the packages if it is already installed.
-           */
-          upgrade?: boolean;
-
-          /**
-           * Show option to skip package installation
-           */
-          showSkipOption?: boolean;
-          /**
-           * The list of packages to install.
-           */
-          install?: string[];
+export interface PackageManagementInteractionOptions {
+    /**
+     * When `true`, the package management operation runs without any user prompts or
+     * interaction and relies solely on the packages provided in the options. Any step
+     * that would normally require user input — such as selecting packages to install
+     * when none are specified — is skipped instead of prompting the user. Intended for
+     * automated or headless scenarios such as integration tests. Defaults to `false`.
+     */
+    runHeadless?: boolean;
+}
 
-          /**
-           * The list of packages to uninstall.
-           */
-          uninstall: string[];
-      };
+export type PackageManagementOptions = PackageManagementInteractionOptions &
+    (
+        | {
+              /**
+               * Upgrade the packages if it is already installed.
+               */
+              upgrade?: boolean;
+
+              /**
+               * Show option to skip package installation or uninstallation.
+               */
+              showSkipOption?: boolean;
+              /**
+               * The list of packages to install.
+               */
+              install: string[];
+
+              /**
+               * The list of packages to uninstall.
+               */
+              uninstall?: string[];
+          }
+        | {
+              /**
+               * Upgrade the packages if it is already installed.
+               */
+              upgrade?: boolean;
+
+              /**
+               * Show option to skip package installation or uninstallation.
+               */
+              showSkipOption?: boolean;
+              /**
+               * The list of packages to install.
+               */
+              install?: string[];
+
+              /**
+               * The list of packages to uninstall.
+               */
+              uninstall: string[];
+          }
+    );
 
 /**
  * Options for creating a Python environment.
@@ -881,9 +905,10 @@ export interface PythonEnvironmentManagementApi {
      * Remove a Python environment.
      *
      * @param environment The Python environment to remove.
+     * @param options Optional parameters controlling environment removal.
      * @returns A promise that resolves when the environment has been removed.
      */
-    removeEnvironment(environment: PythonEnvironment): Promise<void>;
+    removeEnvironment(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
 }
 
 export interface PythonEnvironmentsApi {

examples/sample1/src/api.ts

@@ -345,6 +345,17 @@ export interface QuickCreateConfig {
     readonly detail?: string;
 }
 
+/**
+ * Options controlling environment removal.
+ */
+export interface RemoveEnvironmentOptions {
+    /**
+     * When `true`, removes the environment without prompting for confirmation.
+     * Intended for automated or headless scenarios. Defaults to `false`.
+     */
+    runHeadless?: boolean;
+}
+
 /**
  * Interface representing an environment manager.
  *
@@ -425,7 +436,7 @@ export interface EnvironmentManager {
      * Invoked to delete the given environment. Typical triggers include an explicit user
      * action (such as a "Delete Environment" command) and programmatic removal via the API.
      */
-    remove?(environment: PythonEnvironment): Promise<void>;
+    remove?(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
 
     /**
      * Refreshes the list of Python environments within the specified scope.
@@ -872,47 +883,63 @@ export interface GetPackagesOptions {
     skipCache?: boolean;
 }
 
-export type PackageManagementOptions =
-    | {
-          /**
-           * Upgrade the packages if they are already installed.
-           */
-          upgrade?: boolean;
-
-          /**
-           * Show option to skip package installation or uninstallation.
-           */
-          showSkipOption?: boolean;
-          /**
-           * The list of packages to install.
-           */
-          install: string[];
-
-          /**
-           * The list of packages to uninstall.
-           */
-          uninstall?: string[];
-      }
-    | {
-          /**
-           * Upgrade the packages if they are already installed.
-           */
-          upgrade?: boolean;
-
-          /**
-           * Show option to skip package installation or uninstallation.
-           */
-          showSkipOption?: boolean;
-          /**
-           * The list of packages to install.
-           */
-          install?: string[];
+/**
+ * Options controlling user interaction during package management operations.
+ */
+export interface PackageManagementInteractionOptions {
+    /**
+     * When `true`, the package management operation runs without any user prompts or
+     * interaction and relies solely on the packages provided in the options. Any step
+     * that would normally require user input — such as selecting packages to install
+     * when none are specified — is skipped instead of prompting the user. Intended for
+     * automated or headless scenarios such as integration tests. Defaults to `false`.
+     */
+    runHeadless?: boolean;
+}
 
-          /**
-           * The list of packages to uninstall.
-           */
-          uninstall: string[];
-      };
+export type PackageManagementOptions = PackageManagementInteractionOptions &
+    (
+        | {
+              /**
+               * Upgrade the packages if they are already installed.
+               */
+              upgrade?: boolean;
+
+              /**
+               * Show option to skip package installation or uninstallation.
+               */
+              showSkipOption?: boolean;
+              /**
+               * The list of packages to install.
+               */
+              install: string[];
+
+              /**
+               * The list of packages to uninstall.
+               */
+              uninstall?: string[];
+          }
+        | {
+              /**
+               * Upgrade the packages if they are already installed.
+               */
+              upgrade?: boolean;
+
+              /**
+               * Show option to skip package installation or uninstallation.
+               */
+              showSkipOption?: boolean;
+              /**
+               * The list of packages to install.
+               */
+              install?: string[];
+
+              /**
+               * The list of packages to uninstall.
+               */
+              uninstall: string[];
+          }
+    );
 
 /**
  * Options for creating a Python environment.
@@ -1011,9 +1038,10 @@ export interface PythonEnvironmentManagementApi {
      * Remove a Python environment.
      *
      * @param environment The Python environment to remove.
+     * @param options Optional parameters controlling environment removal.
      * @returns A promise that resolves when the environment has been removed.
      */
-    removeEnvironment(environment: PythonEnvironment): Promise<void>;
+    removeEnvironment(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
 }
 
 export interface PythonEnvironmentsApi {

src/api.ts

@@ -258,6 +258,21 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 },
             );
         }),
+        ...(process.env.VSC_PYTHON_INTEGRATION_TEST === '1'
+            ? [
+                  commands.registerCommand('python-envs.test.getPackageManagerIds', () =>
+                      envManagers.packageManagers.map((manager) => manager.id),
+                  ),
+                  commands.registerCommand(
+                      'python-envs.test.getDirectPackageNames',
+                      async (environment: PythonEnvironment) => {
+                          const manager = envManagers.getPackageManager(environment);
+                          const names = await manager?.getDirectPackageNames?.(environment);
+                          return names ? Array.from(names) : undefined;
+                      },
+                  ),
+              ]
+            : []),
         commands.registerCommand('python-envs.searchSettings', async () => {
             await openSearchSettings();
         }),