casraf/DefinitelyTyped
1
0
Fork 0
mirror of https://github.com/chenasraf/DefinitelyTyped.git synced 2026-05-18 01:49:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

VS Code 1.59.0 Extension API (#54970)

Browse Source 
* VS Code 1.59.0 Extension API

* Fix CI issues

Co-authored-by: VSCode <vscode@microsoft.com>
This commit is contained in:
Raymond Zhao
2021-08-05 13:04:14 -07:00
committed by GitHub
parent 8ddc5dbf6a
commit 40b3327a57
1 changed files with 545 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

554
types/vscode/index.d.ts vendored
View File

@@ -1,4 +1,4 @@
// Type definitions for Visual Studio Code 1.58
// Type definitions for Visual Studio Code 1.59
// Project: https://github.com/microsoft/vscode
// Definitions by: Visual Studio Code Team, Microsoft <https://github.com/microsoft>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -10,7 +10,7 @@
*--------------------------------------------------------------------------------------------*/
/**
* Type Definition for Visual Studio Code 1.58 Extension API
* Type Definition for Visual Studio Code 1.59 Extension API
* See https://code.visualstudio.com/api for more information
*/
@@ -5668,7 +5668,7 @@ declare module 'vscode' {
/**
* The tooltip text when you hover over this entry.
*/
tooltip: string | undefined;
tooltip: string | MarkdownString | undefined;
/**
* The foreground color for this entry.
@@ -5678,9 +5678,11 @@ declare module 'vscode' {
/**
* The background color for this entry.
*
* *Note*: only `new ThemeColor('statusBarItem.errorBackground')` is
* supported for now. More background colors may be supported in the
* future.
* *Note*: only the following colors are supported:
* * `new ThemeColor('statusBarItem.errorBackground')`
* * `new ThemeColor('statusBarItem.warningBackground')`
*
* More background colors may be supported in the future.
*
* *Note*: when a background color is set, the statusbar may override
* the `color` choice to ensure the entry is readable in all themes.
@@ -7464,7 +7466,7 @@ declare module 'vscode' {
* </script>
* ```
*
* To load a resources from the workspace inside a webview, use the `{@link Webview.asWebviewUri asWebviewUri}` method
* To load a resources from the workspace inside a webview, use the {@link Webview.asWebviewUri `asWebviewUri`} method
* and ensure the resource's directory is listed in {@link WebviewOptions.localResourceRoots `WebviewOptions.localResourceRoots`}.
*
* Keep in mind that even though webviews are sandboxed, they still allow running scripts and loading arbitrary content,
@@ -9259,7 +9261,7 @@ declare module 'vscode' {
* Get {@link TreeItem} representation of the `element`
*
* @param element The element for which {@link TreeItem} representation is asked for.
* @return TreeItem representation of the element
* @return representation of the element
*/
getTreeItem(element: T): TreeItem | Thenable<TreeItem>;
@@ -11560,6 +11562,39 @@ declare module 'vscode' {
readonly executionSummary?: NotebookCellExecutionSummary;
}
/**
* Represents a notebook editor that is attached to a {@link NotebookDocument notebook}.
* Additional properties of the NotebookEditor are available in the proposed
* API, which will be finalized later.
*/
export interface NotebookEditor {
}
/**
* Renderer messaging is used to communicate with a single renderer. It's returned from {@link notebooks.createRendererMessaging}.
*/
export interface NotebookRendererMessaging {
/**
* An event that fires when a message is received from a renderer.
*/
readonly onDidReceiveMessage: Event<{
readonly editor: NotebookEditor;
readonly message: any;
}>;
/**
* Send a message to one or all renderer.
*
* @param message Message to send
* @param editor Editor to target with the message. If not provided, the
* message is sent to all renderers.
* @returns a boolean indicating whether the message was successfully
* delivered to any renderer.
*/
postMessage(message: any, editor?: NotebookEditor): Thenable<boolean>;
}
/**
* Represents a notebook which itself is a sequence of {@link NotebookCell code or markup cells}. Notebook documents are
* created from {@link NotebookData notebook data}.
@@ -12294,6 +12329,18 @@ declare module 'vscode' {
* @return A {@link Disposable} that unregisters this provider when being disposed.
*/
export function registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable;
/**
* Creates a new messaging instance used to communicate with a specific renderer.
*
* * *Note 1:* Extensions can only create renderer that they have defined in their `package.json`-file
* * *Note 2:* A renderer only has access to messaging if `requiresMessaging` is set to `always` or `optional` in
* its `notebookRenderer` contribution.
*
* @param rendererId The renderer ID to communicate with
* @returns A new notebook renderer messaging object.
*/
export function createRendererMessaging(rendererId: string): NotebookRendererMessaging;
}
/**
@@ -12339,7 +12386,7 @@ declare module 'vscode' {
* The icon path for a specific
* {@link SourceControlResourceState source control resource state}.
*/
readonly iconPath?: string | Uri;
readonly iconPath?: string | Uri | ThemeIcon;
}
/**
@@ -13024,6 +13071,13 @@ declare module 'vscode' {
*/
parentSession?: DebugSession;
/**
* Controls whether lifecycle requests like 'restart' are sent to the newly created session or its parent session.
* By default (if the property is false or missing), lifecycle requests are sent to the new session.
* This property is ignored if the session has no parent session.
*/
lifecycleManagedByParent?: boolean;
/**
* Controls whether this session should have a separate debug console or share it
* with the parent session. Has no effect for sessions which do not have a parent session.
@@ -13774,6 +13828,488 @@ declare module 'vscode' {
*/
export function registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable;
}
/**
* Namespace for testing functionality. Tests are published by registering
* {@link TestController} instances, then adding {@link TestItem TestItems}.
* Controllers may also describe how to run tests by creating one or more
* {@link TestRunProfile} instances.
*/
export namespace tests {
/**
* Creates a new test controller.
*
* @param id Identifier for the controller, must be globally unique.
* @param label A human-readable label for the controller.
* @returns An instance of the {@link TestController}.
*/
export function createTestController(id: string, label: string): TestController;
}
/**
* The kind of executions that {@link TestRunProfile TestRunProfiles} control.
*/
export enum TestRunProfileKind {
Run = 1,
Debug = 2,
Coverage = 3,
}
/**
* A TestRunProfile describes one way to execute tests in a {@link TestController}.
*/
export interface TestRunProfile {
/**
* Label shown to the user in the UI.
*
* Note that the label has some significance if the user requests that
* tests be re-run in a certain way. For example, if tests were run
* normally and the user requests to re-run them in debug mode, the editor
* will attempt use a configuration with the same label of the `Debug`
* kind. If there is no such configuration, the default will be used.
*/
label: string;
/**
* Configures what kind of execution this profile controls. If there
* are no profiles for a kind, it will not be available in the UI.
*/
readonly kind: TestRunProfileKind;
/**
* Controls whether this profile is the default action that will
* be taken when its kind is actioned. For example, if the user clicks
* the generic "run all" button, then the default profile for
* {@link TestRunProfileKind.Run} will be executed, although the
* user can configure this.
*/
isDefault: boolean;
/**
* If this method is present, a configuration gear will be present in the
* UI, and this method will be invoked when it's clicked. When called,
* you can take other editor actions, such as showing a quick pick or
* opening a configuration file.
*/
configureHandler?: () => void;
/**
* Handler called to start a test run. When invoked, the function should call
* {@link TestController.createTestRun} at least once, and all test runs
* associated with the request should be created before the function returns
* or the returned promise is resolved.
*
* @param request Request information for the test run.
* @param cancellationToken Token that signals the used asked to abort the
* test run. If cancellation is requested on this token, all {@link TestRun}
* instances associated with the request will be
* automatically cancelled as well.
*/
runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable<void> | void;
/**
* Deletes the run profile.
*/
dispose(): void;
}
/**
* Entry point to discover and execute tests. It contains {@link TestController.items} which
* are used to populate the editor UI, and is associated with
* {@link TestController.createRunProfile run profiles} to allow
* for tests to be executed.
*/
export interface TestController {
/**
* The id of the controller passed in {@link vscode.tests.createTestController}.
* This must be globally unique.
*/
readonly id: string;
/**
* Human-readable label for the test controller.
*/
label: string;
/**
* A collection of "top-level" {@link TestItem} instances, which can in
* turn have their own {@link TestItem.children | children} to form the
* "test tree."
*
* The extension controls when to add tests. For example, extensions should
* add tests for a file when {@link vscode.workspace.onDidOpenTextDocument}
* fires in order for decorations for tests within a file to be visible.
*
* However, the editor may sometimes explicitly request children using the
* {@link resolveHandler} See the documentation on that method for more details.
*/
readonly items: TestItemCollection;
/**
* Creates a profile used for running tests. Extensions must create
* at least one profile in order for tests to be run.
* @param label A human-readable label for this profile.
* @param kind Configures what kind of execution this profile manages.
* @param runHandler Function called to start a test run.
* @param isDefault Whether this is the default action for its kind.
* @returns An instance of a {@link TestRunProfile}, which is automatically
* associated with this controller.
*/
createRunProfile(label: string, kind: TestRunProfileKind, runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable<void> | void, isDefault?: boolean): TestRunProfile;
/**
* A function provided by the extension that the editor may call to request
* children of a test item, if the {@link TestItem.canResolveChildren} is
* `true`. When called, the item should discover children and call
* {@link vscode.tests.createTestItem} as children are discovered.
*
* Generally the extension manages the lifecycle of test items, but under
* certain conditions the editor may request the children of a specific
* item to be loaded. For example, if the user requests to re-run tests
* after reloading the editor, the editor may need to call this method
* to resolve the previously-run tests.
*
* The item in the explorer will automatically be marked as "busy" until
* the function returns or the returned thenable resolves.
*
* @param item An unresolved test item for which children are being
* requested, or `undefined` to resolve the controller's initial {@link items}.
*/
resolveHandler?: (item: TestItem | undefined) => Thenable<void> | void;
/**
* Creates a {@link TestRun}. This should be called by the
* {@link TestRunProfile} when a request is made to execute tests, and may
* also be called if a test run is detected externally. Once created, tests
* that are included in the request will be moved into the queued state.
*
* All runs created using the same `request` instance will be grouped
* together. This is useful if, for example, a single suite of tests is
* run on multiple platforms.
*
* @param request Test run request. Only tests inside the `include` may be
* modified, and tests in its `exclude` are ignored.
* @param name The human-readable name of the run. This can be used to
* disambiguate multiple sets of results in a test run. It is useful if
* tests are run across multiple platforms, for example.
* @param persist Whether the results created by the run should be
* persisted in the editor. This may be false if the results are coming from
* a file already saved externally, such as a coverage information file.
* @returns An instance of the {@link TestRun}. It will be considered "running"
* from the moment this method is invoked until {@link TestRun.end} is called.
*/
createTestRun(request: TestRunRequest, name?: string, persist?: boolean): TestRun;
/**
* Creates a new managed {@link TestItem} instance. It can be added into
* the {@link TestItem.children} of an existing item, or into the
* {@link TestController.items}.
*
* @param id Identifier for the TestItem. The test item's ID must be unique
* in the {@link TestItemCollection} it's added to.
* @param label Human-readable label of the test item.
* @param uri URI this TestItem is associated with. May be a file or directory.
*/
createTestItem(id: string, label: string, uri?: Uri): TestItem;
/**
* Unregisters the test controller, disposing of its associated tests
* and unpersisted results.
*/
dispose(): void;
}
/**
* A TestRunRequest is a precursor to a {@link TestRun}, which in turn is
* created by passing a request to {@link tests.runTests}. The TestRunRequest
* contains information about which tests should be run, which should not be
* run, and how they are run (via the {@link profile}).
*
* In general, TestRunRequests are created by the editor and pass to
* {@link TestRunProfile.runHandler}, however you can also create test
* requests and runs outside of the `runHandler`.
*/
export class TestRunRequest {
/**
* A filter for specific tests to run. If given, the extension should run
* all of the included tests and all their children, excluding any tests
* that appear in {@link TestRunRequest.exclude}. If this property is
* undefined, then the extension should simply run all tests.
*
* The process of running tests should resolve the children of any test
* items who have not yet been resolved.
*/
readonly include?: TestItem[];
/**
* An array of tests the user has marked as excluded from the test included
* in this run; exclusions should apply after inclusions.
*
* May be omitted if no exclusions were requested. Test controllers should
* not run excluded tests or any children of excluded tests.
*/
readonly exclude?: TestItem[];
/**
* The profile used for this request. This will always be defined
* for requests issued from the editor UI, though extensions may
* programmatically create requests not associated with any profile.
*/
readonly profile?: TestRunProfile;
/**
* @param tests Array of specific tests to run, or undefined to run all tests
* @param exclude An array of tests to exclude from the run.
* @param profile The run profile used for this request.
*/
constructor(include?: readonly TestItem[], exclude?: readonly TestItem[], profile?: TestRunProfile);
}
/**
* Options given to {@link TestController.runTests}
*/
export interface TestRun {
/**
* The human-readable name of the run. This can be used to
* disambiguate multiple sets of results in a test run. It is useful if
* tests are run across multiple platforms, for example.
*/
readonly name?: string;
/**
* A cancellation token which will be triggered when the test run is
* canceled from the UI.
*/
readonly token: CancellationToken;
/**
* Whether the test run will be persisted across reloads by the editor.
*/
readonly isPersisted: boolean;
/**
* Indicates a test is queued for later execution.
* @param test Test item to update.
*/
enqueued(test: TestItem): void;
/**
* Indicates a test has started running.
* @param test Test item to update.
*/
started(test: TestItem): void;
/**
* Indicates a test has been skipped.
* @param test Test item to update.
*/
skipped(test: TestItem): void;
/**
* Indicates a test has failed. You should pass one or more
* {@link TestMessage TestMessages} to describe the failure.
* @param test Test item to update.
* @param messages Messages associated with the test failure.
* @param duration How long the test took to execute, in milliseconds.
*/
failed(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void;
/**
* Indicates a test has errored. You should pass one or more
* {@link TestMessage TestMessages} to describe the failure. This differs
* from the "failed" state in that it indicates a test that couldn't be
* executed at all, from a compilation error for example.
* @param test Test item to update.
* @param messages Messages associated with the test failure.
* @param duration How long the test took to execute, in milliseconds.
*/
errored(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void;
/**
* Indicates a test has passed.
* @param test Test item to update.
* @param duration How long the test took to execute, in milliseconds.
*/
passed(test: TestItem, duration?: number): void;
/**
* Appends raw output from the test runner. On the user's request, the
* output will be displayed in a terminal. ANSI escape sequences,
* such as colors and text styles, are supported.
*
* @param output Output text to append.
*/
appendOutput(output: string): void;
/**
* Signals that the end of the test run. Any tests included in the run whose
* states have not been updated will have their state reset.
*/
end(): void;
}
/**
* Collection of test items, found in {@link TestItem.children} and
* {@link TestController.items}.
*/
export interface TestItemCollection {
/**
* Gets the number of items in the collection.
*/
readonly size: number;
/**
* Replaces the items stored by the collection.
* @param items Items to store.
*/
replace(items: readonly TestItem[]): void;
/**
* Iterate over each entry in this collection.
*
* @param callback Function to execute for each entry.
* @param thisArg The `this` context used when invoking the handler function.
*/
forEach(callback: (item: TestItem, collection: TestItemCollection) => unknown, thisArg?: unknown): void;
/**
* Adds the test item to the children. If an item with the same ID already
* exists, it'll be replaced.
* @param items Item to add.
*/
add(item: TestItem): void;
/**
* Removes a single test item from the collection.
* @param itemId Item ID to delete.
*/
delete(itemId: string): void;
/**
* Efficiently gets a test item by ID, if it exists, in the children.
* @param itemId Item ID to get.
* @returns The found item or undefined if it does not exist.
*/
get(itemId: string): TestItem | undefined;
}
/**
* An item shown in the "test explorer" view.
*
* A `TestItem` can represent either a test suite or a test itself, since
* they both have similar capabilities.
*/
export interface TestItem {
/**
* Identifier for the `TestItem`. This is used to correlate
* test results and tests in the document with those in the workspace
* (test explorer). This cannot change for the lifetime of the `TestItem`,
* and must be unique among its parent's direct children.
*/
readonly id: string;
/**
* URI this `TestItem` is associated with. May be a file or directory.
*/
readonly uri?: Uri;
/**
* The children of this test item. For a test suite, this may contain the
* individual test cases or nested suites.
*/
readonly children: TestItemCollection;
/**
* The parent of this item. It's set automatically, and is undefined
* top-level items in the {@link TestController.items} and for items that
* aren't yet included in another item's {@link children}.
*/
readonly parent?: TestItem;
/**
* Indicates whether this test item may have children discovered by resolving.
*
* If true, this item is shown as expandable in the Test Explorer view and
* expanding the item will cause {@link TestController.resolveHandler}
* to be invoked with the item.
*
* Default to `false`.
*/
canResolveChildren: boolean;
/**
* Controls whether the item is shown as "busy" in the Test Explorer view.
* This is useful for showing status while discovering children.
*
* Defaults to `false`.
*/
busy: boolean;
/**
* Display name describing the test case.
*/
label: string;
/**
* Optional description that appears next to the label.
*/
description?: string;
/**
* Location of the test item in its {@link uri}.
*
* This is only meaningful if the `uri` points to a file.
*/
range?: Range;
/**
* Optional error encountered while loading the test.
*
* Note that this is not a test result and should only be used to represent errors in
* test discovery, such as syntax errors.
*/
error?: string | MarkdownString;
}
/**
* Message associated with the test state. Can be linked to a specific
* source range -- useful for assertion failures, for example.
*/
export class TestMessage {
/**
* Human-readable message text to display.
*/
message: string | MarkdownString;
/**
* Expected test output. If given with {@link actualOutput}, a diff view will be shown.
*/
expectedOutput?: string;
/**
* Actual test output. If given with {@link expectedOutput}, a diff view will be shown.
*/
actualOutput?: string;
/**
* Associated file location.
*/
location?: Location;
/**
* Creates a new TestMessage that will present as a diff in the editor.
* @param message Message to display to the user.
* @param expected Expected output.
* @param actual Actual output.
*/
static diff(message: string | MarkdownString, expected: string, actual: string): TestMessage;
/**
* Creates a new TestMessage instance.
* @param message The message to show to the user.
*/
constructor(message: string | MarkdownString);
}
}
/**