test: add cross-platform package manager lifecycle coverage

.github/workflows/pr-check.yml

@@ -252,6 +252,9 @@ jobs:
     name: Integration Tests
     runs-on: ${{ matrix.os }}
     needs: [smoke-tests]
+    env:
+      CONDA_PLUGINS_AUTO_ACCEPT_TOS: 'true'
+      VSC_PYTHON_PACKAGE_NETWORK_TEST: '1'
     strategy:
       fail-fast: false
       matrix:
@@ -325,6 +328,12 @@ jobs:
       - name: Compile Tests
         run: npm run compile-tests
 
+      - name: Set up Conda
+        uses: conda-incubator/setup-miniconda@fc2d68f6413eb2d87b895e92f8584b5b94a10167 # v3
+        with:
+          activate-environment: ''
+          auto-activate: false
+
       - name: Run Integration Tests (Linux)
         if: runner.os == 'Linux'
         uses: GabrielBB/xvfb-action@86d97bde4a65fe9b290c0b3fb92c2c4ed0e5302d # v1.6
@@ -335,14 +344,6 @@ 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

@@ -253,6 +253,9 @@ jobs:
     name: Integration Tests
     runs-on: ${{ matrix.os }}
     needs: [smoke-tests]
+    env:
+      CONDA_PLUGINS_AUTO_ACCEPT_TOS: 'true'
+      VSC_PYTHON_PACKAGE_NETWORK_TEST: '1'
     strategy:
       fail-fast: false
       matrix:
@@ -326,6 +329,12 @@ jobs:
       - name: Compile Tests
         run: npm run compile-tests
 
+      - name: Set up Conda
+        uses: conda-incubator/setup-miniconda@fc2d68f6413eb2d87b895e92f8584b5b94a10167 # v3
+        with:
+          activate-environment: ''
+          auto-activate: false
+
       - name: Run Integration Tests (Linux)
         if: runner.os == 'Linux'
         uses: GabrielBB/xvfb-action@86d97bde4a65fe9b290c0b3fb92c2c4ed0e5302d # v1.6
@@ -335,11 +344,3 @@ 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"

src/api.ts

@@ -18,6 +18,10 @@ import type {
 import { extensions } from 'vscode';
 
 export type { Pep440Version } from '@renovatebot/pep440';
+export {
+    isPackageVersionLookupNotSupportedError,
+    PackageVersionLookupNotSupportedError,
+} from './common/errors/NotSupportedError';
 
 /*
  * Do not introduce any breaking changes to this API.
@@ -749,8 +753,11 @@ export interface PackageManager {
      * Retrieves the list of available versions for a given package.
      * @param environment - The Python environment context for the lookup.
      * @param packageName - The name of the package to look up.
-     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first),
-     *          or `undefined` if this manager does not support version listing.
+     * Managers that do not support version listing should reject with
+     * {@link PackageVersionLookupNotSupportedError}.
+     *
+     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first).
+     *          `undefined` remains supported for compatibility with existing manager implementations.
      */
     getPackageAvailableVersions?(
         environment: PythonEnvironment,
@@ -1140,12 +1147,12 @@ export interface PythonPackageGetterApi {
      * Get the list of available versions for a package, newest first.
      *
      * Support depends on the package manager backing the environment. Managers that do
-     * not implement version lookup resolve to `undefined`.
+     * not implement version lookup reject with {@link PackageVersionLookupNotSupportedError}.
      *
      * @param environment The Python Environment context for the lookup.
      * @param packageName The name of the package to look up.
-     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first),
-     *          or `undefined` if the package manager does not support version listing.
+     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first).
+     *          `undefined` remains supported for compatibility with existing manager implementations.
      */
     getPackageAvailableVersions(
         environment: PythonEnvironment,

src/common/errors/NotSupportedError.ts

@@ -11,3 +11,32 @@ export class RemoveEnvironmentNotSupported extends BaseError {
         super('NotSupported', message);
     }
 }
+
+/**
+ * Indicates that a package manager cannot list available package versions.
+ */
+export class PackageVersionLookupNotSupportedError extends BaseError {
+    readonly code = 'PackageVersionLookupNotSupported';
+
+    constructor(message: string) {
+        super('NotSupported', message);
+    }
+}
+
+/**
+ * Checks whether an error represents unsupported package version lookup.
+ *
+ * The stable code check supports errors crossing extension bundle boundaries,
+ * where `instanceof` may not use the same class constructor.
+ */
+export function isPackageVersionLookupNotSupportedError(
+    error: unknown,
+): error is PackageVersionLookupNotSupportedError {
+    return (
+        error instanceof PackageVersionLookupNotSupportedError ||
+        (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'PackageVersionLookupNotSupported')
+    );
+}

src/extension.ts

@@ -263,6 +263,16 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                   commands.registerCommand('python-envs.test.getPackageManagerIds', () =>
                       envManagers.packageManagers.map((manager) => manager.id),
                   ),
+                  commands.registerCommand(
+                      'python-envs.test.resolveEnvironmentWithManager',
+                      async (managerId: string, environmentUri: Uri) => {
+                          const manager = envManagers.getEnvironmentManager(managerId);
+                          if (!manager) {
+                              throw new Error(`Environment manager not found: ${managerId}`);
+                          }
+                          return manager.resolve(environmentUri);
+                      },
+                  ),
                   commands.registerCommand(
                       'python-envs.test.getDirectPackageNames',
                       async (environment: PythonEnvironment) => {

src/features/envCommands.ts

@@ -12,6 +12,8 @@ import {
 } from 'vscode';
 import {
     CreateEnvironmentOptions,
+    isPackageVersionLookupNotSupportedError,
+    Pep440Version,
     PythonEnvironment,
     PythonEnvironmentApi,
     PythonProject,
@@ -363,10 +365,17 @@ export async function managePackageVersion(context: unknown, em: EnvironmentMana
         let version: string | undefined;
 
         // Try to fetch available versions for a QuickPick experience
-        const availableVersions = await withProgress(
-            { location: ProgressLocation.Window, title: l10n.t('Fetching available versions for {0}...', pkg.name) },
-            () => packageManager.getPackageAvailableVersions(environment, pkg.name),
-        );
+        let availableVersions: Pep440Version[] | undefined;
+        try {
+            availableVersions = await withProgress(
+                { location: ProgressLocation.Window, title: l10n.t('Fetching available versions for {0}...', pkg.name) },
+                () => packageManager.getPackageAvailableVersions(environment, pkg.name),
+            );
+        } catch (error) {
+            if (!isPackageVersionLookupNotSupportedError(error)) {
+                throw error;
+            }
+        }
 
         if (availableVersions && availableVersions.length > 0) {
             const items = availableVersions.map((v) => ({

src/features/pythonApi.ts

@@ -33,6 +33,7 @@ import {
     ResolveEnvironmentContext,
     SetEnvironmentScope,
 } from '../api';
+import { PackageVersionLookupNotSupportedError } from '../common/errors/NotSupportedError';
 import { traceError, traceInfo } from '../common/logging';
 import { pickEnvironmentManager } from '../common/pickers/managers';
 import { timeout } from '../common/utils/asyncUtils';
@@ -326,7 +327,9 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
         await waitForEnvManagerId([context.envId.managerId]);
         const manager = this.envManagers.getPackageManager(context);
         if (!manager) {
-            return Promise.resolve(undefined);
+            throw new PackageVersionLookupNotSupportedError(
+                `No package manager supports version lookup for: ${context.envId.id}`,
+            );
         }
         return manager.getPackageAvailableVersions(context, packageName);
     }

src/internal.api.ts

@@ -31,7 +31,11 @@ import {
     SetEnvironmentScope,
 } from './api';
 import { ISSUES_URL } from './common/constants';
-import { CreateEnvironmentNotSupported, RemoveEnvironmentNotSupported } from './common/errors/NotSupportedError';
+import {
+    CreateEnvironmentNotSupported,
+    PackageVersionLookupNotSupportedError,
+    RemoveEnvironmentNotSupported,
+} from './common/errors/NotSupportedError';
 import { traceWarn } from './common/logging';
 import { StopWatch } from './common/stopWatch';
 import { EventNames } from './common/telemetry/constants';
@@ -403,7 +407,9 @@ export class InternalPackageManager implements PackageManager {
     ): Promise<Pep440Version[] | undefined> {
         return this.manager.getPackageAvailableVersions
             ? this.manager.getPackageAvailableVersions(environment, packageName)
-            : Promise.resolve(undefined);
+            : Promise.reject(
+                  new PackageVersionLookupNotSupportedError(`Package version lookup not supported by: ${this.id}`),
+              );
     }
 
     getDirectPackageNames(environment: PythonEnvironment): Promise<Set<string> | undefined> {