Use fastapi run for FastAPI debug configs, with file and project variants

src/extension/common/utils/localize.ts

@@ -111,10 +111,17 @@ export namespace DebugConfigStrings {
             label: l10n.t('FastAPI'),
             description: l10n.t('Launch and debug a FastAPI web application'),
         };
-        export const enterAppPathOrNamePath = {
+        export const snippetFile = {
+            name: l10n.t('Python Debugger: FastAPI File'),
+        };
+        export const selectConfigurationWithFile = {
+            label: l10n.t('FastAPI File'),
+            description: l10n.t('Launch and debug a FastAPI web application using the current file'),
+        };
+        export const enterAppPath = {
             title: l10n.t('Debug FastAPI'),
-            prompt: l10n.t("Enter the path to the application, e.g. 'main.py' or 'main'"),
-            invalid: l10n.t('Enter a valid name'),
+            prompt: l10n.t('Enter the path to your FastAPI app (e.g. main.py or backend/app/main.py).'),
+            invalid: l10n.t('Enter a valid path'),
         };
     }
     export namespace flask {

src/extension/debugger/configuration/debugConfigurationService.ts

@@ -8,7 +8,10 @@ import { IMultiStepInputFactory, InputStep, IQuickPickParameters, MultiStepInput
 import { AttachRequestArguments, DebugConfigurationArguments, LaunchRequestArguments } from '../../types';
 import { DebugConfigurationState, DebugConfigurationType, IDebugConfigurationService } from '../types';
 import { buildDjangoLaunchDebugConfiguration } from './providers/djangoLaunch';
-import { buildFastAPILaunchDebugConfiguration } from './providers/fastapiLaunch';
+import {
+    buildFastAPILaunchDebugConfiguration,
+    buildFastAPIWithFileLaunchDebugConfiguration,
+} from './providers/fastapiLaunch';
 import { buildFileLaunchDebugConfiguration } from './providers/fileLaunch';
 import { buildFlaskLaunchDebugConfiguration } from './providers/flaskLaunch';
 import { buildModuleLaunchConfiguration } from './providers/moduleLaunch';
@@ -158,6 +161,11 @@ export class PythonDebugConfigurationService implements IDebugConfigurationServi
                 type: DebugConfigurationType.launchFastAPI,
                 description: DebugConfigStrings.fastapi.selectConfiguration.description,
             },
+            {
+                label: DebugConfigStrings.fastapi.selectConfigurationWithFile.label,
+                type: DebugConfigurationType.launchFastAPIWithFile,
+                description: DebugConfigStrings.fastapi.selectConfigurationWithFile.description,
+            },
             {
                 label: DebugConfigStrings.flask.selectConfiguration.label,
                 type: DebugConfigurationType.launchFlask,
@@ -178,6 +186,10 @@ export class PythonDebugConfigurationService implements IDebugConfigurationServi
         >();
         debugConfigurations.set(DebugConfigurationType.launchDjango, buildDjangoLaunchDebugConfiguration);
         debugConfigurations.set(DebugConfigurationType.launchFastAPI, buildFastAPILaunchDebugConfiguration);
+        debugConfigurations.set(
+            DebugConfigurationType.launchFastAPIWithFile,
+            buildFastAPIWithFileLaunchDebugConfiguration,
+        );
         debugConfigurations.set(DebugConfigurationType.launchFile, buildFileLaunchDebugConfiguration);
         debugConfigurations.set(DebugConfigurationType.launchFileWithArgs, buildFileWithArgsLaunchDebugConfiguration);
         debugConfigurations.set(DebugConfigurationType.launchFlask, buildFlaskLaunchDebugConfiguration);

src/extension/debugger/configuration/dynamicdebugConfigurationService.ts

@@ -8,8 +8,7 @@ import * as path from 'path';
 import { CancellationToken, DebugConfiguration, WorkspaceFolder } from 'vscode';
 import { IDynamicDebugConfigurationService } from '../types';
 import { DebuggerTypeName } from '../../constants';
-import { replaceAll } from '../../common/stringUtils';
-import { getDjangoPaths, getFastApiPaths, getFlaskPaths } from './utils/configuration';
+import { getDjangoPaths, getFastApiPaths, getFlaskPaths, tryResolveFastApiArgs } from './utils/configuration';
 import { sendTelemetryEvent } from '../../telemetry';
 import { EventName } from '../../telemetry/constants';
 
@@ -63,15 +62,22 @@ export class DynamicPythonDebugConfigurationService implements IDynamicDebugConf
         }
 
         const fastApiPaths = await getFastApiPaths(folder);
-        let fastApiPath = fastApiPaths?.length ? fastApiPaths[0].fsPath : null;
-        if (fastApiPath) {
-            fastApiPath = replaceAll(path.relative(folder.uri.fsPath, fastApiPath), path.sep, '.').replace('.py', '');
+        if (fastApiPaths?.length) {
+            const fastApiArgs = tryResolveFastApiArgs(folder, fastApiPaths) ?? ['run'];
             providers.push({
                 name: 'Python Debugger: FastAPI',
                 type: DebuggerTypeName,
                 request: 'launch',
-                module: 'uvicorn',
-                args: [`${fastApiPath}:app`, '--reload'],
+                module: 'fastapi',
+                args: fastApiArgs,
+                jinja: true,
+            });
+            providers.push({
+                name: 'Python Debugger: FastAPI File',
+                type: DebuggerTypeName,
+                request: 'launch',
+                module: 'fastapi',
+                args: ['run', '${file}'],
                 jinja: true,
             });
         }

src/extension/debugger/configuration/providers/fastapiLaunch.ts

@@ -4,65 +4,82 @@
 'use strict';
 
 import * as path from 'path';
-import * as fs from 'fs-extra';
-import { WorkspaceFolder } from 'vscode';
 import { MultiStepInput } from '../../../common/multiStepInput';
 import { DebugConfigStrings } from '../../../common/utils/localize';
 import { sendTelemetryEvent } from '../../../telemetry';
 import { EventName } from '../../../telemetry/constants';
 import { DebuggerTypeName } from '../../../constants';
 import { LaunchRequestArguments } from '../../../types';
 import { DebugConfigurationState, DebugConfigurationType } from '../../types';
+import { getFastApiPaths, tryResolveFastApiArgs } from '../utils/configuration';
+
+async function promptForAppPath(
+    input: MultiStepInput<DebugConfigurationState>,
+    value?: string,
+): Promise<string | undefined> {
+    const entered = await input.showInputBox({
+        title: DebugConfigStrings.fastapi.enterAppPath.title,
+        prompt: DebugConfigStrings.fastapi.enterAppPath.prompt,
+        value: value ?? '',
+        validate: (v) =>
+            Promise.resolve(v && v.trim().length > 0 ? undefined : DebugConfigStrings.fastapi.enterAppPath.invalid),
+    });
+    return entered?.trim();
+}
 
 export async function buildFastAPILaunchDebugConfiguration(
     input: MultiStepInput<DebugConfigurationState>,
     state: DebugConfigurationState,
 ): Promise<void> {
-    const application = await getApplicationPath(state.folder);
-    let manuallyEnteredAValue: boolean | undefined;
+    const fastApiPaths = await getFastApiPaths(state.folder);
+    const autoArgs = state.folder ? tryResolveFastApiArgs(state.folder, fastApiPaths) : undefined;
+
+    let args: string[];
+    let manuallyEnteredAValue = false;
+    if (autoArgs) {
+        args = autoArgs;
+    } else {
+        const workspaceRoot = state.folder?.uri.fsPath;
+        const prefill =
+            workspaceRoot && fastApiPaths.length > 0 ? path.relative(workspaceRoot, fastApiPaths[0].fsPath) : undefined;
+        const entered = await promptForAppPath(input, prefill);
+        if (!entered) {
+            return;
+        }
+        args = ['run', entered];
+        manuallyEnteredAValue = true;
+    }
+
     const config: Partial<LaunchRequestArguments> = {
         name: DebugConfigStrings.fastapi.snippet.name,
         type: DebuggerTypeName,
         request: 'launch',
-        module: 'uvicorn',
-        args: ['main:app', '--reload'],
+        module: 'fastapi',
+        args,
         jinja: true,
     };
-
-    if (!application) {
-        const selectedPath = await input.showInputBox({
-            title: DebugConfigStrings.fastapi.enterAppPathOrNamePath.title,
-            value: 'main.py',
-            prompt: DebugConfigStrings.fastapi.enterAppPathOrNamePath.prompt,
-            validate: (value) =>
-                Promise.resolve(
-                    value && value.trim().length > 0
-                        ? undefined
-                        : DebugConfigStrings.fastapi.enterAppPathOrNamePath.invalid,
-                ),
-        });
-        if (selectedPath) {
-            manuallyEnteredAValue = true;
-            config.args = [`${path.basename(selectedPath, '.py').replace('/', '.')}:app`, '--reload'];
-        } else {
-            return;
-        }
-    }
-
     sendTelemetryEvent(EventName.DEBUGGER_CONFIGURATION_PROMPTS, undefined, {
         configurationType: DebugConfigurationType.launchFastAPI,
-        autoDetectedFastAPIMainPyPath: !!application,
+        autoDetectedFastAPIMainPyPath: !!autoArgs,
         manuallyEnteredAValue,
     });
     Object.assign(state.config, config);
 }
-export async function getApplicationPath(folder: WorkspaceFolder | undefined): Promise<string | undefined> {
-    if (!folder) {
-        return undefined;
-    }
-    const defaultLocationOfManagePy = path.join(folder.uri.fsPath, 'main.py');
-    if (await fs.pathExists(defaultLocationOfManagePy)) {
-        return 'main.py';
-    }
-    return undefined;
+
+export async function buildFastAPIWithFileLaunchDebugConfiguration(
+    _input: MultiStepInput<DebugConfigurationState>,
+    state: DebugConfigurationState,
+): Promise<void> {
+    const config: Partial<LaunchRequestArguments> = {
+        name: DebugConfigStrings.fastapi.snippetFile.name,
+        type: DebuggerTypeName,
+        request: 'launch',
+        module: 'fastapi',
+        args: ['run', '${file}'],
+        jinja: true,
+    };
+    sendTelemetryEvent(EventName.DEBUGGER_CONFIGURATION_PROMPTS, undefined, {
+        configurationType: DebugConfigurationType.launchFastAPIWithFile,
+    });
+    Object.assign(state.config, config);
 }

src/extension/debugger/configuration/utils/configuration.ts

@@ -7,6 +7,7 @@
 'use strict';
 
 import * as fs from 'fs-extra';
+import * as path from 'path';
 import { MultiStepInput } from '../../../common/multiStepInput';
 import { sendTelemetryEvent } from '../../../telemetry';
 import { EventName } from '../../../telemetry/constants';
@@ -81,6 +82,14 @@ export async function getFastApiPaths(folder: WorkspaceFolder | undefined) {
     return fastApiPaths;
 }
 
+export function tryResolveFastApiArgs(folder: WorkspaceFolder, paths: readonly Uri[]): string[] | undefined {
+    if (paths.length !== 1) {
+        return undefined;
+    }
+    const relative = path.relative(folder.uri.fsPath, paths[0].fsPath);
+    return ['run', relative];
+}
+
 export async function getFlaskPaths(folder: WorkspaceFolder | undefined) {
     if (!folder) {
         return [];

src/extension/debugger/types.ts

@@ -34,6 +34,7 @@ export enum DebugConfigurationType {
     remoteAttach = 'remoteAttach',
     launchDjango = 'launchDjango',
     launchFastAPI = 'launchFastAPI',
+    launchFastAPIWithFile = 'launchFastAPIWithFile',
     launchFlask = 'launchFlask',
     launchModule = 'launchModule',
     launchPyramid = 'launchPyramid',

src/test/unittest/configuration/dynamicdebugConfigurationService.unit.test.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+'use strict';
+
+import { expect } from 'chai';
+import * as path from 'path';
+import * as sinon from 'sinon';
+import { Uri, WorkspaceFolder } from 'vscode';
+import { DebuggerTypeName } from '../../../extension/constants';
+import { DynamicPythonDebugConfigurationService } from '../../../extension/debugger/configuration/dynamicdebugConfigurationService';
+import * as configurationUtils from '../../../extension/debugger/configuration/utils/configuration';
+
+suite('Debugging - Dynamic Debug Configuration Service', () => {
+    const folder: WorkspaceFolder = { uri: Uri.file('/work'), name: 'ws', index: 0 };
+    let service: DynamicPythonDebugConfigurationService;
+    let getFastApiPathsStub: sinon.SinonStub;
+
+    setup(() => {
+        service = new DynamicPythonDebugConfigurationService();
+        sinon.stub(configurationUtils, 'getDjangoPaths').resolves([]);
+        sinon.stub(configurationUtils, 'getFlaskPaths').resolves([]);
+        getFastApiPathsStub = sinon.stub(configurationUtils, 'getFastApiPaths');
+    });
+
+    teardown(() => {
+        sinon.restore();
+    });
+
+    const fastApiProviders = async () => {
+        const result = await service.provideDebugConfigurations(folder);
+        return (result ?? []).filter((c) => c.name?.includes('FastAPI'));
+    };
+
+    const fileVariantConfig = {
+        name: 'Python Debugger: FastAPI File',
+        type: DebuggerTypeName,
+        request: 'launch',
+        module: 'fastapi',
+        args: ['run', '${file}'],
+        jinja: true,
+    };
+
+    test('No FastAPI detected → no FastAPI configs offered', async () => {
+        getFastApiPathsStub.resolves([]);
+
+        const fastApi = await fastApiProviders();
+        expect(fastApi).to.have.length(0);
+    });
+
+    test('Single match at workspace root → project config uses resolved path, file variant uses ${file}', async () => {
+        getFastApiPathsStub.resolves([Uri.file('/work/main.py')]);
+
+        const fastApi = await fastApiProviders();
+        expect(fastApi).to.have.length(2);
+        expect(fastApi[0]).to.deep.equal({
+            name: 'Python Debugger: FastAPI',
+            type: DebuggerTypeName,
+            request: 'launch',
+            module: 'fastapi',
+            args: ['run', 'main.py'],
+            jinja: true,
+        });
+        expect(fastApi[1]).to.deep.equal(fileVariantConfig);
+    });
+
+    test('Single match in subdirectory → project config passes path explicitly', async () => {
+        getFastApiPathsStub.resolves([Uri.file('/work/backend/app/main.py')]);
+
+        const fastApi = await fastApiProviders();
+        expect(fastApi).to.have.length(2);
+        expect(fastApi[0]).to.deep.equal({
+            name: 'Python Debugger: FastAPI',
+            type: DebuggerTypeName,
+            request: 'launch',
+            module: 'fastapi',
+            args: ['run', path.join('backend', 'app', 'main.py')],
+            jinja: true,
+        });
+        expect(fastApi[1]).to.deep.equal(fileVariantConfig);
+    });
+
+    test('Multiple matches → project config falls back to plain `fastapi run`', async () => {
+        getFastApiPathsStub.resolves([Uri.file('/work/svc-a/main.py'), Uri.file('/work/svc-b/main.py')]);
+
+        const fastApi = await fastApiProviders();
+        expect(fastApi).to.have.length(2);
+        expect(fastApi[0]).to.deep.equal({
+            name: 'Python Debugger: FastAPI',
+            type: DebuggerTypeName,
+            request: 'launch',
+            module: 'fastapi',
+            args: ['run'],
+            jinja: true,
+        });
+        expect(fastApi[1]).to.deep.equal(fileVariantConfig);
+    });
+});