Developer Setup

Install, Build, and Test the Extension

Developers can install the Visual Studio Code Extension for Zowe, which lets users interact with z/OS data sets on a remote mainframe instance, from a VSIX file and run system tests on the extension.

Install in VS Code from source

Build Zowe Explorer as a VSIX file and install it in VS Code.

Important! Follow the instructions for creating testProfileData.ts before performing these steps.

Building the extension

From your local copy of this repository, issue the following commands to create the VSIX package file from source:

v2 and below

yarn install
yarn workspace vscode-extension-for-zowe package

v3

pnpm install
pnpm --filter vscode-extension-for-zowe package

After these steps, a .vsix file will be created in the packages/zowe-explorer/dist folder.

Installing the extension in VS Code

After you create a VSIX file, install the extension in VS Code:

Navigate to the Extensions menu in VS Code and click the ... menu on the top-left.
Select "Install from VSIX" and select the .vsix file that was created by the package command.
Restart Visual Studio Code.

The extension is installed.

End-to-end Tests (`next` branch)

Set up and execute end-to-end tests for Zowe Explorer.

Test Profile Data

In order to run the end-to-end tests, you must define a .env file in the packages/zowe-explorer/__tests__/__e2e__ folder with environment variables specifying profile information, credentials and the items to test with. Refer to the contents in .env.example for all environment variables that must be defined:

# Path to the Zowe home folder where configurations are stored (relative to current directory)
ZOWE_TEST_DIR=".zowe"

# Profile variables
ZE_TEST_PROFILE_NAME="<profileName>" # The name of the profile in your Zowe config to use for testing
ZE_TEST_PROFILE_USER="testUser" # The user to leverage during the e2e tests

# USS variables
ZE_TEST_USS_FILTER="/u/users/testUser" # The filter to apply when searching on a USS profile*
ZE_TEST_USS_DIR="test" # The USS directory to use for edit and list testing - should be relative to USS filter*
ZE_TEST_USS_FILE="testFile.txt" # The USS file to edit and save with, relative to USS dir*

# Data Set variables
ZE_TEST_DS_FILTER="TESTUSER.*" # The filter to apply when searching on a Data Sets profile
ZE_TEST_PDS="TESTUSER.C" # The PDS to use for edit and list testing - matched by the defined filter*
ZE_TEST_PDS_MEMBER="TESTC" # The PDS member to use for edit and list testing - relative to the defined PDS*
ZE_TEST_PS="TESTUSER.TESTPS" # The PS to use for editing - matched by the defined filter*

# * means that the item must exist on the test system for it to be considered valid

Once the environment variables are configured in a .env file, cd into the packages/zowe-explorer folder and build the extension using pnpm build. After the build process is complete, run the tests using pnpm test:e2e.

Executing from VS Code

Open the repository folder in VS Code, build the extension, and open the "Run and Debug" panel on the left.
Expand the drop-down at the top of the panel, select "End-to-end Tests," and then click the "Play" ▶ button.

The tests run and the output goes to your VS Code debug console. JUnit reporter logs are also available in the packages/zowe-explorer/results folder.

Behavior-driven Integration Tests (`next` branch)

Prepare your environment and execute behavior-driven integration tests for Zowe Explorer.

For v3 we have added new integration testing that leverages the UI to verify specific actions. Developers can run these tests to ensure that tree items and commands are still behaving as intended.

Test Profile Data

In order to run integration tests successfully, ensure that there are at least 3 profiles present in your Zowe config. The profiles do not have to have valid credentials as test credentials will be used when needed, but the hostnames need to be valid connections at the time the tests are run (in order to pass Zowe Explorer profile validation, specifically when issuing TSO/MVS/SSH commands).

In addition, a default profile needs to be specified for the zosmf profile type.

Executing from VS Code

Open the repository folder in VS Code, build the extension, and open the "Run and Debug" panel on the left.
Expand the drop-down at the top of the panel, select "Behavior-driven Integration Tests," and then click the "Play" ▶ button.

The tests run and the output goes to your VS Code debug console. JUnit reporter logs are also available in the packages/zowe-explorer/results folder.

Theia Regression Tests (v2 and below)

Run regression tests to ensure that the latest release of Zowe Explorer is compatible with the Theia environment.

Set up Theia Workspace

Set up your Theia workspace for development purposes.

Follow these steps:

Ensure that you install the following components:
- Mozilla Firefox
- Google Chrome
- Mozilla Geckodriver (and add it to your PATH)
- ChromeDriver (and add it to your PATH)
- Selenium WebDriver (install as a global package)
Build a VSIX file that contains your changes.
Build and run the Theia browser example, using Setting up your Theia workspace.
- Ensure that your latest VSIX file is in the plugins folder.
- Ensure that Theia is running while you execute the tests!
(Optional) To verify your setup, open a web browser and navigate to http://localhost:3000

You should see Zowe Explorer deployed in Theia.

Run Regression Tests

Compile your project by running yarn run compile in your command-line interface.
Run the Theia test by issuing the following command:

yarn run test:theia

The output from the tests appears in your VSCode debug console.

Run Tests with Firefox UI Visibility Components

Disable headless mode to see changes in Firefox while your tests are in progress.

Note: Tests run in headless mode by default.

Navigate to the __tests__/__theia__/ folder.
Comment out the line firefoxOptions.headless(); in the tests.
Compile the extension.
Run the regression test.

The tests run and the Firefox browser is launched.

Localization

All localized strings must be string literals, you cannot include variables or use template literals within the argument you provide to the localize function.

Adding Strings

Create a new key for your string. Existing keys follow the convention of including the functions/properties the string is nested in and a short one/two word description of the string.
There are two places to localize strings: in the package.json file and in the typescript files in the src directory.
- If you want to add a new string to the package.json file, replace the string with your key enclosed by the percent sign as such % key % i.e. "This is a string" becomes "%exampleProperty.exDescription%". Then go to the package.nls.json file found in the root directory of the repository and include your newly created key and string inside as a json key/value pair.
- If you want to add a new string to a typescript file, you will need to include the following library in your file (if not already included). import * as nls from 'vscode-nls';
  - You will also need to include the following code:
```
// Set up localization
nls.config({ messageFormat: nls.MessageFormat.bundle, bundleFormat: nls.BundleFormat.standalone })();
const localize: nls.LocalizeFunc = nls.loadMessageBundle();
```
  - Next wrap your string with the localize function in this format localize('key', 'string') i.e. localize('addEntry','Successfully called add entry.')
After adding/updating/removing any string, run yarn workspace vscode-extension-for-zowe package. This will update the sample directory under the i18n folder with the newly added strings. Upload these files to Zanata or email a maintainer to do so.

Adding a New Language

Navigate to the i18n folder found in the root directory of the repository. Duplicate the sample folder and rename the new folder to the ISO-639-3 code for the language found here.
Once the language has been translated, go to the Zowe VS Code Extension project in Zanata, select the most up to date version, select the translated language, and for each file, press the arrow to the left of the filename and select download translated .json.
Replace the files in the folder you created with these newly downloaded files of the same name.
Next, open gulpfile.js found in the root directory of the repository. Add the following information: { folderName: 'ISO-639-3-Code', id: 'vscode-locale-id' } to the languages array. For example, for Chinese add: { folderName: 'zho', id: 'zh-cn' }. You can find the vscode locale id here.
Make sure you have the vscode language pack of this new language installed and to see the localized result, first run the yarn workspace vscode-extension-for-zowe package command in terminal. Then press F1, run the Configure Display Language command, and select the locale id of your translated language.

How to Donate Translations

Click here and follow instructions under the Sign Up heading to sign up to Zanata.
Send an email to one of the maintainers with the email heading as ZANATA TRANSLATOR REQUEST and include the following information in the body of the email.
1. Zanata username
2. Language(s) you wish to translate
3. Affiliation with Zowe
You should receive a response within 3 business days and be added to the Zanata Zowe VS Code Extension project. Click here for more information about how to use Zanata to translate.

Localization (v3/next)

All localized strings must be string literals, you can include variables by using {0}, {1}, etc, and defining the variables later

Adding a New Language

Navigate to the l10n folder found in /packages/zowe-explorer.
In the folder create a file named package.nls.<my-language>.json.
In this file you can define translated versions of the original package.nls.json file to the language you wish to contribute.

For more information about l10n and contributing visit this readme: https://github.com/microsoft/vscode-l10n/tree/main?tab=readme-ov-file#packagenlsjson

Adding Strings

Create a new key for your string. Existing keys follow the convention of including the functions/properties the string is nested in and a short one/two word description of the string.
There are two places to localize strings: in the package.json file and in the typescript files in the src directory.
- If you want to add a new string to the package.json file, replace the string with your key enclosed by the percent sign as such % key % i.e. "This is a string" becomes "%exampleProperty.exDescription%". Then go to the package.nls.json file found in the root directory of the repository and include your newly created key and string inside as a json key/value pair.
- There is different ways to localize l10n in a TypeScript file, but this could be one of the methods for localizing:
```
    vscode.l10n.t({
         message: `My {0} localized string`,
         args: ["First"],
         comments: ["The amount of times a string was localized"]
    });
```
After adding/updating/removing any string, run pnpm --filter vscode-extension-for-zowe vscode:prepublish. This will update the sample directory under the l10n folder with the newly added strings. Upload these files to Zanata or email a maintainer to do so.

How to Donate Translations

Click here and follow instructions under the Sign Up heading to sign up to Zanata.
Send an email to one of the maintainers with the email heading as ZANATA TRANSLATOR REQUEST and include the following information in the body of the email.
1. Zanata username
2. Language(s) you wish to translate
3. Affiliation with Zowe
You should receive a response within 3 business days and be added to the Zanata Zowe VS Code Extension project. Click here for more information about how to use Zanata to translate.

Packaging

Run this command to create packages in the "dist" directory: yarn package

For SDK packages like zowe-explorer-api, a TGZ is produced that can be installed with npm or published to npmjs.org.

For VS Code extensions, a VSIX is produced that can be installed in VS Code or published to the VS Code Marketplace or Open VSX Registry.

Note: The list of files included in the VSIX bundle is defined by an allowlist in the ".vscodeignore" file.

The CI workflows for Zowe Explorer and Zowe Explorer FTP run the yarn package command and archive VSIXs as artifacts that can be downloaded for testing. If you have the GitHub CLI installed, you can define a Bash alias like the following to download the VSIX for a given branch or pull request (for example, zeVsix main or zeVsix 123):

zeVsix() {
  repo="zowe/vscode-extension-for-zowe"
  case $1 in
    '') echo "Error: You must specify a branch name or PR number" >&2 && return 1 ;;
    *[!0-9]*) branch=$1 ;;
    *) branch=$(gh pr view $1 -R $repo --json headRefName --jq ".headRefName") ;;
  esac
  runId=$(gh run list -R $repo -b $branch --limit 1 --status success --workflow "Zowe Explorer CI" --json databaseId --jq ".[0].databaseId")
  GH_DEBUG=1 gh run download $runId -R $repo -n zowe-explorer-vsix
}

zowe/vscode-extension-for-zowe

Welcome

Home

Using Zowe Explorer

Usage in Remote Environments

Roadmaps

Development Process

Testing process

Release Process

Preparing for a release

Backlog Grooming Process

How to handle GitHub issues

How to Extend Zowe Explorer

Conformance Criteria

Early Access

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Developer Setup

Install, Build, and Test the Extension

Contents

Install in VS Code from source

Building the extension

Installing the extension in VS Code

End-to-end Tests (`next` branch)

Test Profile Data

Executing from VS Code

Behavior-driven Integration Tests (`next` branch)

Test Profile Data

Executing from VS Code

Theia Regression Tests (v2 and below)

Set up Theia Workspace

Run Regression Tests

Run Tests with Firefox UI Visibility Components

Localization

Adding Strings

Adding a New Language

How to Donate Translations

Localization (v3/next)

Adding a New Language

Adding Strings

How to Donate Translations

Packaging

Clone this wiki locally

Developer Setup

Install, Build, and Test the Extension

Contents

Install in VS Code from source

Building the extension

Installing the extension in VS Code

End-to-end Tests (next branch)

Test Profile Data

Executing from VS Code

Behavior-driven Integration Tests (next branch)

Test Profile Data

Executing from VS Code

Theia Regression Tests (v2 and below)

Set up Theia Workspace

Run Regression Tests

Run Tests with Firefox UI Visibility Components

Localization

Adding Strings

Adding a New Language

How to Donate Translations

Localization (v3/next)

Adding a New Language

Adding Strings

How to Donate Translations

Packaging

Clone this wiki locally

End-to-end Tests (`next` branch)

Behavior-driven Integration Tests (`next` branch)