@salesforce/salesforcedx-vscode-test-tools

@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=[e-mail] 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.