Testing a Visual Studio Code extension in Che

Visual Studio Code (VS Code) extensions work in a workspace. VS 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 VS Code extension in Che with workspaces and how to review the compatibility of VS 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 VS 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.

Prerequisites
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

  • A GitHub account.

Procedure
  1. 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 VS Code extension. (Bracket Pair Colorizer is a popular VS Code extension.)

  2. Click the Create secret gist button.

  3. 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 the git clone command
    git 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.
  4. Change the directory:

    $ cd <gist-directory-name> (1)
    1 Directory name matching the gist ID.
  5. Download the plug-in from the VS Code marketplace or from its GitHub page, and store the plug-in file in the cloned directory.

  6. Create a plugin.yaml file in the cloned directory to add the definition of this plug-in.

    Example of the plugin.yaml file referencing the .vsix binary file extension
    apiVersion: v2
    publisher: CoenraadS
    name: bracket-pair-colorizer
    version: 1.0.61
    type: VS Code extension
    displayName: Bracket Pair Colorizer
    title: Bracket Pair Colorizer
    description: Bracket Pair Colorizer
    icon: https://raw.githubusercontent.com/redhat-developer/codeready-workspaces/master/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.
  7. 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
  8. Create a devfile.yaml that references the plugin.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 (instead of an ID pointing to a definition in the default plug-in registry).
  9. 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
  10. Before committing the files, add a pre-commit hook to update the {{REPOSITORY}} variable to the public external raw gist link:

    1. 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.

    2. Make the script executable:

      $ chmod u+x .git/hooks/pre-commit
  11. Commit and push the files:

    # Add files
    $ git add *
    
    # Commit
    $ git commit -m "Initial Commit for the test of our extension"
    [master 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
  12. 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>/f?url=$(git config --get remote.origin.url)/raw/devfile.yaml"

Verifying the VS Code extension API compatibility level

Che-Theia does not fully support the VS Code extensions API. The vscode-theia-comparator is used to analyze the compatibility between the Che-Theia plug-in API and the VS Code extension API. This tool runs nightly, and the results are published on the vscode-theia-comparator GitHub page.

Prerequisites
Procedure

To run the vscode-theia comparator manually:

  1. Clone the vscode-theia-comparator repository, and build it using the yarn command.

  2. Set the GITHUB_TOKEN environment variable to your token.

  3. Execute the yarn run generate command to generate a report.

  4. Open the out/status.html file to view the report.