Testing a Visual Studio Code extension in Che
Visual Studio Code (Visual Studio Code) extensions work in a workspace. Visual Studio Code extensions can run in the Che-Theia editor container, or in their own isolated and preconfigured containers with their prerequisites.
This section describes how to test a Visual Studio Code extension in Che with workspaces and how to review the compatibility of Visual Studio Code extensions to check whether a specific API is available.
The extension-hosting sidecar container and the use of the extension in a devfile are optional. |
Testing a Visual Studio Code extension using GitHub gist
Each workspace can have its own set of plug-ins. The list of plug-ins and the list of projects to clone are defined in the devfile.yaml
file.
For example, to enable an AsciiDoc plug-in from the Eclipse Che dashboard, add the following snippet to the devfile:
components:
- id: joaopinto/vscode-asciidoctor/latest
type: chePlugin
To add a plug-in that is not in the default plug-in registry, build a custom plug-in registry. See Customizing the registries, or, alternatively, use GitHub and the gist service.
-
A running instance of Che. To install an instance of Che, see Installing Che.
-
A GitHub account.
-
Go to the gist webpage and create a
README.md
file with the following description:Try Bracket Pair Colorizer extension in Eclipse Che
and content:Example Visual Studio Code extension
. (Bracket Pair Colorizer is a popular Visual Studio Code extension.) -
Click the Create secret gist button.
-
Clone the gist repository by using the URL from the navigation bar of the browser:
$ git clone https://gist.github.com/<your-github-username>/<gist-id>
Example of the output of thegit clone
commandgit clone https://gist.github.com/benoitf/85c60c8c439177ac50141d527729b9d9 (1) Cloning into '85c60c8c439177ac50141d527729b9d9'... remote: Enumerating objects: 3, done. remote: Counting objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (3/3), done.
1 Each gist has a unique ID. -
Change the directory:
$ cd <gist-directory-name> (1)
1 Directory name matching the gist ID. -
Download the plug-in from the Visual Studio Code marketplace or from its GitHub page, and store the plug-in file in the cloned directory.
-
Create a
plugin.yaml
file in the cloned directory to add the definition of this plug-in.Example of theplugin.yaml
file referencing the.vsix
binary file extensionapiVersion: v2 publisher: CoenraadS name: bracket-pair-colorizer version: 1.0.61 type: Visual Studio Code extension displayName: Bracket Pair Colorizer title: Bracket Pair Colorizer description: Bracket Pair Colorizer icon: https://raw.githubusercontent.com/redhat-developer/codeready-workspaces/crw-2-rhel-8/dependencies/che-plugin-registry/resources/images/default.svg?sanitize=true repository: https://github.com/CoenraadS/BracketPair category: Language firstPublicationDate: '2020-07-30' spec: (1) extensions: - "{{REPOSITORY}}/CoenraadS.bracket-pair-colorizer-1.0.61.vsix" (2) latestUpdateDate: "2020-07-30"
1 This extension requires a basic Node.js runtime, so it is not necessary to add a custom runtime image in plugin.yaml
.2 {{REPOSITORY}}
is a macro for a pre-commit hook. -
Define a memory limit and volumes:
spec: containers: - image: "quay.io/eclipse/che-sidecar-java:8-0cfbacb" name: vscode-java memoryLimit: "1500Mi" volumes: - mountPath: "/home/theia/.m2" name: m2
-
Create a
devfile.yaml
that references theplugin.yaml
file:apiVersion: 1.0.0 metadata: generateName: java-maven- projects: - name: console-java-simple source: type: git location: "https://github.com/che-samples/console-java-simple.git" branch: java1.11 components: - type: chePlugin id: redhat/java11/latest - type: chePlugin (1) reference: "{{REPOSITORY}}/plugin.yaml" - type: dockerimage alias: maven image: quay.io/eclipse/che-java11-maven:nightly memoryLimit: 512Mi mountSources: true volumes: - name: m2 containerPath: /home/user/.m2 commands: - name: maven build actions: - type: exec component: maven command: "mvn clean install" workdir: ${CHE_PROJECTS_ROOT}/console-java-simple - name: maven build and run actions: - type: exec component: maven command: "mvn clean install && java -jar ./target/*.jar" workdir: ${CHE_PROJECTS_ROOT}/console-java-simple
1 Any other devfile definition is also accepted. The important information in this devfile are the lines defining this external component. It means that an external reference defines the plug-in and not an ID, which pointing to a definition in the default plug-in registry. -
Verify there are 4 files in the current Git directory:
$ ls -la .git CoenraadS.bracket-pair-colorizer-1.0.61.vsix README.md devfile.yaml plugin.yaml
-
Before committing the files, add a pre-commit hook to update the
{{REPOSITORY}}
variable to the public external raw gist link:-
Create a
.git/hooks/pre-commit
file with this content:#!/bin/sh # get modified files FILES=$(git diff --cached --name-only --diff-filter=ACMR "*.yaml" | sed 's| |\\ |g') # exit fast if no files found [ -z "$FILES" ] && exit 0 # grab remote origin origin=$(git config --get remote.origin.url) url="${origin}/raw" # iterate on files and add the good prefix pattern for FILE in ${FILES}; do sed -e "s#{{REPOSITORY}}#${url}#g" "${FILE}" > "${FILE}.back" mv "${FILE}.back" "${FILE}" done # Add back to staging echo "$FILES" | xargs git add exit 0
The hook replaces the
{{REPOSITORY}}
macro and adds the external raw link to the gist. -
Make the script executable:
$ chmod u+x .git/hooks/pre-commit
-
-
Commit and push the files:
# Add files $ git add * # Commit $ git commit -m "Initial Commit for the test of our extension" [main 98dd370] Initial Commit for the test of our extension 3 files changed, 61 insertions(+) create mode 100644 CoenraadS.bracket-pair-colorizer-1.0.61.vsix create mode 100644 devfile.yaml create mode 100644 plugin.yaml # and push the files to the main branch $ git push origin
-
Visit the gist website and verify that all links have the correct public URL and do not contain any
{{REPOSITORY}}
variables. To reach the devfile:$ echo "$(git config --get remote.origin.url)/raw/devfile.yaml"
or:
$ echo "https://<che-server>/#$(git config --get remote.origin.url)/raw/devfile.yaml"
Verifying the Visual Studio Code extension API compatibility level
Che-Theia does not fully support the Visual Studio Code extensions API. The vscode-theia-comparator is used to analyze the compatibility between the Che-Theia plug-in API and the Visual Studio Code extension API. This tool runs nightly, and the results are published on the vscode-theia-comparator GitHub page.
-
Personal GitHub access token. See Creating a personal access token for the command line. A GitHub access token is required to increase the GitHub download limit for your IP address.
To run the vscode-theia comparator manually:
-
Clone the vscode-theia-comparator repository, and build it using the
yarn
command. -
Set the
GITHUB_TOKEN
environment variable to your token. -
Execute the
yarn run generate
command to generate a report. -
Open the
out/status.html
file to view the report.