Test: terminal completions on bash/zsh

[meganrogge]

Refs #226562

• macOS @eleanorjboyd (was supposed to do Windows but it wasn't working so @Tyriar is investigating)
• macOS @jrieken
• Linux @legomushroom

Complexity: 5

Authors: @meganrogge, @Tyriar

Roles: Developer, Engineering Manager

Create Issue

---

Background

In prior iterations, terminal completions were added for pwsh via our shell integration script. This iteration, we've added support for bash and zsh (also fish, which is currently blocked by #233799). This was accomplished by adding a built-in terminal-suggest extension, which provides completions via new proposed API.

vscode/src/vscode-dts/vscode.proposed.terminalCompletionProvider.d.ts

Lines 5 to 119 in 226f700

	declare module 'vscode' {
	// https://github.com/microsoft/vscode/issues/226562
	export interface TerminalCompletionProvider<T extends TerminalCompletionItem> {
	id: string;
	/**
	* Provide completions for the given position and document.
	* @param terminal The terminal for which completions are being provided.
	* @param context Information about the terminal's current state.
	* @param token A cancellation token.
	* @return A list of completions.
	*/
	provideTerminalCompletions(terminal: Terminal, context: TerminalCompletionContext, token: CancellationToken): ProviderResult<T[] | TerminalCompletionList<T>>;
	}
	export interface TerminalCompletionItem {
	/**
	* The label of the completion.
	*/
	label: string;
	/**
	* The index of the start of the range to replace.
	*/
	replacementIndex: number;
	/**
	* The length of the range to replace.
	*/
	replacementLength: number;
	/**
	* The completion's detail which appears on the right of the list.
	*/
	detail?: string;
	/**
	* The completion's kind. Note that this will map to an icon.
	*/
	kind?: TerminalCompletionItemKind;
	}
	/**
	* Terminal item kinds.
	*/
	export enum TerminalCompletionItemKind {
	File = 0,
	Folder = 1,
	Flag = 2,
	Method = 3,
	Argument = 4
	}
	export interface TerminalCompletionContext {
	/**
	* The complete terminal command line.
	*/
	commandLine: string;
	/**
	* The index of the
	* cursor in the command line.
	*/
	cursorPosition: number;
	}
	export namespace window {
	/**
	* Register a completion provider for a certain type of terminal.
	*
	* @param provider The completion provider.
	* @returns A {@link Disposable} that unregisters this provider when being disposed.
	*/
	export function registerTerminalCompletionProvider<T extends TerminalCompletionItem>(provider: TerminalCompletionProvider<T>, ...triggerCharacters: string[]): Disposable;
	}
	/**
	* Represents a collection of {@link TerminalCompletionItem completion items} to be presented
	* in the terminal.
	*/
	export class TerminalCompletionList<T extends TerminalCompletionItem = TerminalCompletionItem> {
	/**
	* Resources that should be shown in the completions list for the cwd of the terminal.
	*/
	resourceRequestConfig?: TerminalResourceRequestConfig;
	/**
	* The completion items.
	*/
	items: T[];
	/**
	* Creates a new completion list.
	*
	* @param items The completion items.
	* @param resourceRequestConfig Indicates which resources should be shown as completions for the cwd of the terminal.
	*/
	constructor(items?: T[], resourceRequestConfig?: TerminalResourceRequestConfig);
	}
	export interface TerminalResourceRequestConfig {
	/**
	* Show files as completion items.
	*/
	filesRequested?: boolean;
	/**
	* Show folders as completion items.
	*/
	foldersRequested?: boolean;
	/**
	* If no cwd is provided, no resources will be shown as completions.
	*/

Testing

To test terminal completions, you will need to enable terminal.integrated.suggest.enabled and terminal.integrated.suggest.enableExtensionCompletions.

Note that reconnected terminals do not have their cwd set, which breaks folder/file completion functionality. While testing, to avoid this issue, I suggest disabling persistence with terminal.integrated.enablePersistentSessions: false. This issue is tracked here #234672.

Completions are provided under these circumstances:

• when typing a command
• a trigger character, like / has been added to the terminal
• they're requested manually, via ctrl+space

There are several types of completions:

• files/folders
• commands (on your $PATH or built-in in per shell type)
• arguments/options for commands

We have added three specs for now, with plans to add many more in future iterations. These include:

• code
• code-insiders
• cd

When you type after using any of these specs, you should be provided with options, arguments, and files/folders as expected.

For example:

• Typing code-insiders --locale e should prompt you with just locale options of en and es.
• Typing code-insiders -- should provide you with a list of all options.
• Typing cd and requesting completions should provide you with only folder completions.

File/folder completions are provided as a fallback when there are no specific options/arguments to provide.

[Tyriar]

I plan on doing some testing on Windows tomorrow and investigate why it doesn't work

[legomushroom]

Couldn't make it work on Ubuntu 24.04.1 LTS (Intel), bash, VSCode 1.96.0-insider a40fbb1a 🤷

My settings:

{
    "terminal.integrated.suggest.enabled": true,
    "terminal.integrated.suggest.enableExtensionCompletions": true,
    "terminal.integrated.enablePersistentSessions": false
}

Started vscode with the VSCODE_SUGGEST env variable set to 1.

I also accidently tested on Mac OSx 15.5.1 (Intel Mid 2019), - zsh didn't work at all, and bash was partially working - filesystem path suggestions were there, and program name completions were working at first, but nothing else. Then it started giving filesystem path completions for everything.

[Tyriar]

Investigated the Windows issue and it should be fixed with #235276

[legomushroom]

Added follow up issue for Unix machines here: #235331