Test Setup

The Extension Tester offers both CLI and API to perform all the setup actions. That way you can simply integrate it into your npm scripts, or just call it from your code if that is more preferable.

Using the CLI

All the CLI actions are available with the command extest which is available to your npm scripts once the package is installed. The default storage folder for all test resources is test-resources in the extension's root. To avoid build problems, make sure to exclude it from your tsconfig and vsce.

Download VS Code

If you wish to manually download VS Code of a given version

Usage: extest get-vscode [options]

Download VSCode for testing

Options:
  -s, --storage <storage>       Use this folder for all test resources
  -c, --code_version <version>  Version of VSCode to download
  -t, --type <type>             Type of VSCode release (stable/insider)
  -h, --help                    output usage information

Download ChromeDriver

Download chrome driver for a given version of VS Code

Usage: extest get-chromedriver [options]

Download ChromeDriver binary

Options:
  -s, --storage <storage>       Use this folder for all test resources
  -c, --code_version <version>  Version of VSCode you want to run with the CromeDriver
  -h, --help                    output usage information

Build and Install Extension from vsix

To manually build and install your extension. This step is not necessary to run the tests, since the framework will run the extension directly from source.

Usage: cli install-vsix [options]

Install extension from vsix file into test instance of VSCode

Options:
  -s, --storage <storage>                      Use this folder for all test resources
  -e, --extensions_dir <extensions_directory>  VSCode will use this directory for managing extensions
  -f, --vsix_file <file>                       path/URL to vsix file containing the extension
  -y, --yarn                                   Use yarn to build the extension via vsce instead of npm (default: false)
  -h, --help                                   output usage information

Perform All Test Setup

To perform all test setup steps in one command

Usage: cli setup-tests [options]

Set up all necessary requirements for tests to run

Options:
  -s, --storage <storage>                      Use this folder for all test resources
  -e, --extensions_dir <extensions_directory>  VSCode will use this directory for managing extensions
  -c, --code_version <version>                 Version of VSCode to download
  -t, --type <type>                            Type of VSCode release (stable/insider)
  -y, --yarn                                   Use yarn to build the extension via vsce instead of npm (default: false)
  -h, --help                                   output usage information

Run Tests

To run test files

Usage: cli run-tests [options] <testFiles>

Run the test files specified by a glob pattern

Options:
  -s, --storage <storage>                      Use this folder for all test resources
  -e, --extensions_dir <extensions_directory>  VSCode will use this directory for managing extensions
  -c, --code_version <version>                 Version of VSCode to be used
  -t, --type <type>                            Type of VSCode release (stable/insider)
  -o, --code_settings <settings.json>          Path to custom settings for VS Code json file
  -u, --uninstall_extension                    Uninstall the extension after the test run (default: false)
  -m, --mocha_config                           Path to Mocha configuration file
  -h, --help                                   output usage information

Set up and Run Tests

Perform all test setup and run tests in a single command

Usage: cli setup-and-run [options] <testFiles>

Perform all setup and run tests specified by glob pattern

Options:
  -s, --storage <storage>                      Use this folder for all test resources
  -e, --extensions_dir <extensions_directory>  VSCode will use this directory for managing extensions
  -c, --code_version <version>                 Version of VSCode to download
  -t, --type <type>                            Type of VSCode release (stable/insider)
  -o, --code_settings <settings.json>          Path to custom settings for VS Code json file
  -y, --yarn                                   Use yarn to build the extension via vsce instead of npm (default: false)
  -u, --uninstall_extension                    Uninstall the extension after the test run (default: false)
  -m, --mocha_config <mocharc.js>              Path to Mocha configuration file
  -h, --help                                   output usage information

Using the API

The same actions are available in the ExTester class as API:

/**
 * Download VSCode of given version and release quality stream
 * @param version version to download, default latest
 * @param quality quality stream, only acceptable values are 'stable' and 'insider', default stable
 */
downloadCode(version?: string, quality?: string): Promise<void>;
/**
 * Install the extension into the test instance of VS Code
 * @param vsixFile path to extension .vsix file. If not set, default vsce path will be used
 * @param useYarn when true run `vsce package` with the `--yarn` flag
 */
installVsix({ vsixFile, useYarn }?: {
    vsixFile?: string;
    useYarn?: boolean;
}): Promise<void>;
/**
 * Download the matching chromedriver for a given VS Code version
 * @param vscodeVersion selected versio nof VSCode, default latest
 * @param vscodeStream VSCode release stream, default stable
 */
downloadChromeDriver(vscodeVersion?: string, vscodeStream?: string): Promise<void>;
/**
 * Performs all necessary setup: getting VSCode + ChromeDriver
 * and packaging/installing extension into the test instance
 *
 * @param vscodeVersion version of VSCode to test against, default latest
 * @param vscodeStream whether to use stable or insiders build, default stable
 * @param useYarn when true run `vsce package` with the `--yarn` flag
 */
setupRequirements(vscodeVersion?: string, vscodeStream?: string, useYarn?: boolean): Promise<void>;
/**
 * Performs requirements setup and runs extension tests
 *
 * @param vscodeVersion version of VSCode to test against, default latest
 * @param vscodeStream whether to use stable or insiders build, default stable
 * @param testFilesPattern glob pattern for test files to run
 * @param settings path to a custom vscode settings json file
 * @param useYarn when true run `vsce package` with the `--yarn` flag
 * @param cleanup true to uninstall the tested extension after the run, false otherwise
 */
setupAndRunTests(vscodeVersion: string | undefined, vscodeStream: string | undefined, testFilesPattern: string, settings?: string, useYarn?: boolean, cleanup?: boolean, config?: string): Promise<void>;
/**
 * Runs the selected test files in VS Code using mocha and webdriver
 * @param testFilesPattern glob pattern for selected test files
 * @param vscodeStream whether to use stable or insiders build, default stable
 * @param settings path to a custom vscode settings json file
 * @param vscodeVersion version of VSCode to test against, default latest
 * @param cleanup true to uninstall the tested extension after the run, false otherwise
 */
runTests(testFilesPattern: string, vscodeVersion?: string, vscodeStream?: string, settings?: string, cleanup?: boolean, config?: string): Promise<void>;