@salesforce/salesforcedx-vscode-test-tools

Test automation framework for Salesforce Extensions for VS Code.

Introduction

This package provides a comprehensive test automation framework for working with Salesforce Extensions for VS Code. It is extracted from the Salesforce Extensions for VS Code automation tests.

Installation

npm install --save-dev @salesforce/salesforcedx-vscode-test-tools

Usage

import { log, setUpScratchOrg, openFolder } from '@salesforce/salesforcedx-vscode-test-tools';

// Use the imported functions directly
log('Hello, world!');

Framework Structure

The framework is organized into the following modules:

Core: Basic types, constants, and common utility functions
System Operations: File system, CLI commands, git operations, and settings
Salesforce Components: Authorization, deployment, Apex, LWC, and Visualforce utilities
Testing: Extension management, test utilities, and predicates
UI Interaction: Command prompts, notifications, editor, terminal, and workbench interactions

Documentation

The full API documentation is available at https://forcedotcom.github.io/salesforcedx-vscode-test-tools.

Generating Documentation Locally

To generate the documentation locally:

# Install dependencies
npm install

# Generate documentation
npm run docs

# Open documentation in your browser
open docs/index.html

For real-time updates while editing documentation:

npm run docs:watch

Development

Commitizen

This project uses Commitizen for standardized commit messages following the Conventional Commits format.

To create a new commit:

npm run commit

This will guide you through an interactive process to create a properly formatted commit message. The commit message format is enforced using husky hooks.

Scripts

npm run compile - Compile TypeScript code
npm run lint - Run ESLint
npm run clean - Remove build artifacts
npm run test - Run tests
npm run docs - Generate API documentation
npm run docs:watch - Generate API documentation with watch mode

License

BSD-3-Clause

RedHat VS Code Extension Tester

This project is based on ExTester, available at https://github.com/redhat-developer/vscode-extension-tester

Getting Started

If you are interested in contributing, please take a look at the CONTRIBUTING guide.

This repository is published and used as an npm module, currently imported by salesforcedx-vscode. You can follow the same repository to see how this is utilized.

Environment Variables

The following environment variables can be used to configure the automation tests. These are managed by the EnvironmentSettings class.

Environment Variable	Description	Default Value
`VSCODE_VERSION`	VSCode version to use in tests	`'latest'`
`SPEC_FILES`	Test spec filename(s) to run, will be prefixed with 'lib/specs/'	`[]`
`VSIX_TO_INSTALL`	Path to directory containing VSIX files to install	`undefined`
`DEV_HUB_ALIAS_NAME`	Alias for the DevHub org	`'vscodeOrg'`
`DEV_HUB_USER_NAME`	Username for the DevHub org	-
`SFDX_AUTH_URL`	URL for authenticating with Salesforce DX	`undefined`
`EXTENSION_PATH`	Path to extensions directory	`{cwd}/../../salesforcedx-vscode/extensions`
`SALESFORCEDX_VSCODE_EXTENSIONS_PATH`	Alternative path to extensions (takes precedence over EXTENSION_PATH)	-
`THROTTLE_FACTOR`	Number to multiply timeouts by (used to slow down test execution)	`1`
`JAVA_HOME`	Path to Java installation	`undefined`
`USE_EXISTING_PROJECT_PATH`	Path to an existing project to use instead of creating a new one	`undefined`
`E2E_LOG_LEVEL`	Log level for test execution (one of the valid log levels: 'error', 'warn', 'info', 'debug', 'trace')	`'info'`

Usage Notes

SPEC_FILES: If specified, only the named test spec files will be run instead of all tests
EXTENSION_PATH: If your folder structure does not match the standard folder structure shown in the Getting Started section, EXTENSION_PATH will need to be set to the correct relative path to 'salesforcedx-vscode/extensions'
SFDX_AUTH_URL: To obtain this URL, run sf org display -o <myDevHub> --verbose --json in your terminal and extract the value from the sfdxAuthUrl property
USE_EXISTING_PROJECT_PATH: If specified, must point to a valid existing project directory. The test framework will use this project instead of creating a new one
THROTTLE_FACTOR: Useful for debugging tests by slowing down UI interactions. For example, setting to 2 will make tests run at half speed

Example Usage

# Run a specific test file
SPEC_FILES=soql.e2e.js npm test

# Run tests with custom DevHub alias
DEV_HUB_ALIAS_NAME=myDevHub DEV_HUB_USER_NAME=myuser@example.com npm test

# Run tests with slower execution speed (for debugging)
THROTTLE_FACTOR=2 npm test

# Run tests with increased logging
E2E_LOG_LEVEL=debug npm test

Test Configuration

This framework allows customizing the test environment through the TestConfig interface. You can specify the following options:

Workspace Path

By default, the framework creates a salesforcedx-vscode folder in your project directory to store VS Code and test artifacts. You can customize this location through:

Environment variable: WORKSPACE_PATH
Command line argument: --workspace-path or -w
Programmatically through the TestConfig interface

Example configuration through environment variables:

WORKSPACE_PATH=/tmp/my-test-workspace npm test

Example using command line arguments:

npm test -- --workspace-path /tmp/my-test-workspace

Example programmatic usage:

import { TestSetupAndRunner, TestConfig } from '@salesforce/salesforcedx-vscode-test-tools';

const testConfig: Partial<TestConfig> = {
  workspacePath: '/tmp/my-test-workspace'
};

const testRunner = new TestSetupAndRunner(testConfig);
await testRunner.setup();
const result = await testRunner.runTests();

Extensions Path

By default, extensions are installed in the extensions subfolder of the workspace path. You can override this with:

Environment variable: EXTENSION_PATH or SALESFORCEDX_VSCODE_EXTENSIONS_PATH
Programmatically through the TestConfig interface

If only workspacePath is specified, the extensionsPath will automatically be set to ${workspacePath}/extensions.

VSIX Installation Directory

You can specify a dedicated directory containing VSIX files to be installed during test setup. This separates the source of VSIX files from the extensions folder where they get installed.

This can be configured through:

Environment variable: VSIX_TO_INSTALL
Programmatically through the TestConfig interface

# Set a custom VSIX installation directory
VSIX_TO_INSTALL=/path/to/vsix-directory npm test

Example programmatic usage:

import { TestSetupAndRunner, TestConfig } from '@salesforce/salesforcedx-vscode-test-tools';

const testConfig: Partial<TestConfig> = {
  vsixToInstallDir: '/path/to/vsix-directory'
};

const testRunner = new TestSetupAndRunner(testConfig);
await testRunner.setup();
const result = await testRunner.runTests();

If both the TestConfig and environment variable are set, the TestConfig value takes precedence.