feat: add example project

.eslintrc.json

@@ -0,0 +1,30 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "root": true,
+  "rules": {
+    "@typescript-eslint/member-delimiter-style": [
+      "warn",
+      {
+        "multiline": {
+          "delimiter": "semi",
+          "requireLast": true
+        },
+        "singleline": {
+          "delimiter": "semi",
+          "requireLast": false
+        }
+      }
+    ],
+    "@typescript-eslint/naming-convention": "warn",
+    "@typescript-eslint/no-unused-expressions": "off",
+    "@typescript-eslint/semi": ["warn", "always"],
+    "curly": "warn",
+    "eqeqeq": ["warn", "always"],
+    "no-redeclare": "warn",
+    "no-throw-literal": "warn",
+    "no-unused-expressions": "off",
+    "semi": "off"
+  },
+  "ignorePatterns": ["src/ui-test/resources/*"]
+}

.github/workflows/main.yml

@@ -0,0 +1,50 @@
+name: Main CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    env:
+      TEST_RESOURCES: test-resources
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup NodeJS 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: npm-ci
+        run: npm ci
+
+      - name: npm-compile
+        run: npm run compile
+
+      - name: UI test
+        run: xvfb-run --auto-servernum npm run ui-test
+
+      - name: Store UI test log
+        uses: actions/upload-artifact@v4
+        if: failure() || cancelled()
+        with:
+          name: uitest-logs
+          path: test-resources/settings/logs/*
+
+      - name: Store UI Test screenshots
+        uses: actions/upload-artifact@v4
+        if: failure() || cancelled()
+        with:
+          name: uitest-screenshots
+          path: test-resources/screenshots/*.png

.gitignore

@@ -0,0 +1,6 @@
+out
+node_modules
+.vscode-test/
+*.vsix
+test-resources/
+.test-extensions

.mocharc.js

@@ -0,0 +1,4 @@
+// increase default test case timeout to 5 seconds
+module.exports = {
+	timeout: 5000,
+};

.vscode/launch.json

@@ -0,0 +1,36 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug UI Tests",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/node_modules/.bin/extest",
+      "args": [
+        "setup-and-run",
+        "${workspaceFolder}/out/ui-test/*-test.js",
+        "--code_settings",
+        "settings.json",
+        "--extensions_dir",
+        ".test-extensions",
+        "--mocha_config",
+        "${workspaceFolder}/src/ui-test/.mocharc-debug.js"
+      ],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    },
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
+      "outFiles": ["${workspaceFolder}/out/**/*.js"],
+      "preLaunchTask": "npm: watch"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,20 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "never"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    }
+  ]
+}

.vscodeignore

@@ -0,0 +1,3 @@
+test-resources/**
+*.gif
+.test-extensions/**

LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -186,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2019 Software Freedom Conservancy (SFC)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,2 +1,33 @@
-# vscode-extension-tester-example
+# Hello World ExTester
+
 This is a Hello World example extension that shows you how to set up and run simple UI tests for VS Code extensions using the ExTester.
+
+## Motivation
+
+Our example extension gives us the ability to call the `Hello World` command, one that shows a notification saying `Hello World!`. We would like to write automated regression tests for this feature.
+
+![demo](./demo.gif)
+
+## Dependencies and Requirements
+
+In order to run the ExTester, the extension needs 2 packages as (dev)Dependencies:
+
+- `vscode-extension-tester` - the extension testing framework itself
+- `mocha` - Mocha test framework is required, as the ExTester uses it for writing and running its tests
+
+This example also uses `chai` as the assertion framework of choice, but feel free to use any assertion package you like.
+
+Also note that the folder `test-resources` (which stores all the required binaries for testing) is excluded from typescript compiler and ESLint. This is necessary for both to work when building your project. We also recommend adding the folder into your `.gitignore` file.
+
+## Running the Tests
+
+- Run `npm install` in terminal to install dependencies
+- Run `npm run ui-test` in terminal. This will:
+  - Compile the code
+  - Download the latest version of VS Code
+  - Download the adequate version of ChromeDriver
+  - Run the downloaded VS Code binary using ChromeDriver
+  - Run the tests located in `src/ui-test`
+
+To check the `ui-test` script, see the `script` section inside `package.json`.
+To check the test code, see the `src/ui-test/*-test.ts` files.