Test: terminal suggestions on bash, zsh, and pwsh

[meganrogge]

Refs #226562, #237976, #235024, #237587, #235081, #237595, #237662, #233442, #234351, #234352, #237596

• macOS @bhavyaus
• macOS @sandy081
• Windows @amunger

Complexity: 5

Authors: @meganrogge, @Tyriar

Roles: Developer, Engineering Manager

Create Issue

---

Background

We’ve made significant improvements to shell completions, enhancing support for bash and zsh and introducing completions for pwsh through the terminal-suggest extension.

By default, we now use the terminal-suggest extension to provide completions across all shells, replacing the need for shell integration scripts. You can configure the providers with the following setting:

"terminal.integrated.suggest.providers": {
  "terminal-suggest": true,
  "pwsh-shell-integration": false
}

Testing

To test terminal completions, ensure that terminal.integrated.suggest.enabled is enabled in your settings.

You can further customize related settings in the Settings UI under terminal.suggest.

Updates and Enhancements

Widget Layout and Styling

We’ve resolved various issues with the layout and styling of the completion widget. Verify that it aligns closely with the editor's suggest widget in appearance and behavior.

Enhanced Keyboard Support

The completion widget now supports the following keyboard shortcuts:

• Toggle Documentation Visibility: Use Ctrl+Space to move information between the details and documentation views.
• Toggle Focus: Use Ctrl+Alt+Space to switch focus between the terminal and the suggest details.
• Developer Mode: Use CtrlCmd+/ to activate terminalSuggestToggleExplainMode, which provides developer-focused information.

Eager Completions

Completions are now provided more proactively, including:

• While typing, even after backspacing.
• After typing trigger characters, such as /.
• On-demand, by manually invoking suggestions using Ctrl+Space.

Types of Completions

The following types of completions are supported:

• Files/Folders
• Commands: Commands available on your $PATH or built-in commands specific to the shell type.
• Arguments/Options: Suggestions for arguments or options related to commands.

Spec-Specific Argument Completions

We’ve added support for specific commands (specs) that include detailed argument suggestions. These commands include:

• code
• code-insiders
• cd
• ls
• rm
• echo
• mkdir
• rmdir
• touch

When typing any of these commands, you should see relevant options, arguments, and file/folder suggestions as expected.

Examples:

• Typing code-insiders --locale e will suggest locale options such as en and es.
• Typing code-insiders -- will display all available options.
• Typing cd will provide folder-only completions.

Resource Completions

File and folder completions are provided as a fallback when no specific options or arguments are available. Verify the following:

• The absolute path is displayed in the detail view.
• Suggestions like ., .., and ~ resolve correctly and appear only when expected.
• Note: ~ (home directory) is currently supported only in PowerShell (pwsh). API adoption for bash and zsh is in progress.

Command Completions

When testing command completions, verify the following:

• Command Details: If a spec exists for the command, the details section should provide relevant information, such as List directory contents for ls. Use Ctrl+Space to toggle the documentation view, which should also display the command's path.
• No Duplicates: Ensure that no duplicate commands appear in the suggestions. Only the first match on the $PATH should be listed.

Platform-Specific Features

• On Windows, configure the included executables in suggest results with the setting terminal.integrated.suggest.windowsExecutableExtensions.

Discoverability and Status Bar

A status bar is now displayed by default to help users discover keybindings for actions like accepting suggestions. Test the following:

• Use the keybindings shown in the status bar to perform actions.
• Disable the status bar and confirm that it is properly hidden.

Font and Line Height

Configure editor.fontFamily, editor.fontSize, and editor.lineHeight values and make sure those apply properly to the suggest widget.