# jest-environment-vscode-extension

> > 🎪 The best way to run and write tests for your VSCode extension

Latest version **0.0.5** (published 2022-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install jest-environment-vscode-extension
pnpm add jest-environment-vscode-extension
yarn add jest-environment-vscode-extension
bun add jest-environment-vscode-extension
```

Provides the commands `vscode-tests-runner`, `vscode-electron-starter`, `drop-monkey-patch-allow-mocks`, `insert-monkey-patch-allow-mocks`.

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2022-11-13 |
| First published | 2021-12-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/jest-environment-vscode-extension) |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 27.7 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 6 |
| Maintainers | macabeus |

## Links

- npm: https://www.npmjs.com/package/jest-environment-vscode-extension
- Repository: https://github.com/macabeus/jest-environment-vscode
- Homepage: https://github.com/macabeus/jest-environment-vscode#readme
- Issues: https://github.com/macabeus/jest-environment-vscode/issues
- npm.io page: https://npm.io/package/jest-environment-vscode-extension

## Dependencies (4)

- [lodash](https://npm.io/package/lodash.md) 4.17.21
- [dedent-js](https://npm.io/package/dedent-js.md) 1.0.1
- [@vscode/test-electron](https://npm.io/package/@vscode/test-electron.md) 2.2.0
- [jest-environment-node](https://npm.io/package/jest-environment-node.md) 27.4.4

## Recent versions

- 0.0.5 (latest) — 2022-11-13
- 0.0.4-rc2 — 2022-11-13
- 0.0.4-rc1 — 2022-10-30
- 0.0.3 — 2022-01-16
- 0.0.2-rc3 — 2022-01-06
- 0.0.2-rc2 — 2022-01-06
- 0.0.2-rc1 — 2022-01-06
- 0.0.2 — 2022-01-02
- 0.0.1 — 2021-12-31
- 0.0.1-rc3 — 2021-12-29
- 0.0.1-rc2 — 2021-12-29
- 0.0.1-rc1 — 2021-12-26

## README

# jest-environment-vscode-extension

> 🎪 The best way to run and write tests for your VSCode extension

<p align="center">
  <img src="https://user-images.githubusercontent.com/9501115/147397008-ab5ba201-095a-4ac4-b291-5854e9cf2db9.png">
</p>

**Key Features:**

- run tests using Jest
- built-in API making tests simpler to write and read
- zero JS configuration

## Setup

1 - Install the following packages:

```
npm install jest jest-environment-vscode-extension @types/jest @types/jest-environment-vscode-extension --save-dev
```

2 - On `.vscode/tasks.json`, add the following within the `tasks` array:

```json
{
  "label": "create-test-workspace-folder",
  "type": "shell",
  "command": "mkdir",
  "args": ["-p", "test-workspace"],
  "presentation": {
    "reveal": "silent",
    "revealProblems": "onProblem"
  }
},
{
  "label": "remove-test-workspace-folder",
  "type": "shell",
  "command": "rm",
  "args": ["-rf", "test-workspace"],
  "presentation": {
    "reveal": "silent",
    "revealProblems": "onProblem"
  }
},
{
  "label": "insert-monkey-patch-allow-mocks",
  "type": "shell",
  "command": "node ./node_modules/.bin/insert-monkey-patch-allow-mocks ${workspaceFolder}",
  "presentation": {
    "reveal": "silent",
    "revealProblems": "onProblem"
  },
},
{
  "label": "drop-monkey-patch-allow-mocks",
  "type": "shell",
  "command": "node ./node_modules/.bin/drop-monkey-patch-allow-mocks ${workspaceFolder}",
  "presentation": {
    "reveal": "silent",
    "revealProblems": "onProblem"
  }
},
{
  "label": "pre-run-tests",
  "dependsOrder": "sequence",
  "dependsOn": [
    "remove-test-workspace-folder",
    "create-test-workspace-folder",
    "build",
    "insert-monkey-patch-allow-mocks"
  ],
  "presentation": {
    "reveal": "silent",
    "revealProblems": "onProblem"
  }
},
{
  "label": "post-run-tests",
  "dependsOn": [
    "remove-test-workspace-folder",
    "drop-monkey-patch-allow-mocks"
  ],
  "presentation": {
    "reveal": "silent",
    "revealProblems": "onProblem"
  }
}
```

3 - On `.vscode/launch.json`, add the following within the `configurations` array:

```json
{
  "name": "Test Extension - No Workspace",
  "preLaunchTask": "pre-run-tests",
  "postDebugTask": "post-run-tests",
  "type": "extensionHost",
  "request": "launch",
  "runtimeExecutable": "${execPath}",
  "args": [
    "/no-workspace",
    "--disable-extensions",
    "--extensionDevelopmentPath=${workspaceFolder}",
    "--extensionTestsPath=${workspaceFolder}/node_modules/.bin/vscode-tests-runner"
  ],
  "env": {
    "VSCODE_TESTS_PATH": "${workspaceFolder}/out/tests/no-workspace/"
  },
  "outFiles": ["${workspaceFolder}/out/tests/**/*.js"]
},
{
  "name": "Test Extension - With Workspace",
  "preLaunchTask": "pre-run-tests",
  "postDebugTask": "post-run-tests",
  "type": "extensionHost",
  "request": "launch",
  "runtimeExecutable": "${execPath}",
  "args": [
    "${workspaceFolder}/test-workspace",
    "--disable-extensions",
    "--extensionDevelopmentPath=${workspaceFolder}",
    "--extensionTestsPath=${workspaceFolder}/node_modules/.bin/vscode-tests-runner"
  ],
  "env": {
    "VSCODE_TESTS_PATH": "${workspaceFolder}/out/tests/with-workspace/"
  },
  "outFiles": ["${workspaceFolder}/out/tests/**/*.js"]
}
```

4 - Now, write your tests that depend on a workspace within `tests/with-workspace`. And if it doesn't need it, you can write them within `tests/no-workspace`.

Setup finished! 🎉

Now you can run the tests using VSCode:

<img height="225px" src="https://user-images.githubusercontent.com/9501115/147397085-4fc88523-0eb7-4815-a738-3511f79ac7ba.png">

### Running on CI

Running by VSCode is great for development since it's quick and can use breakpoints. But we need to do one more step to can run on CI.

1 - On `package.json`, add the following within the `scripts` object:

```json
"tests:ci:no-workspace": "vscode-electron-starter no-workspace insiders out/tests/no-workspace",
"tests:ci:with-workspace": "vscode-electron-starter with-workspace insiders out/tests/with-workspace"
```

The penultimate parameter is the VSCode version being used. You can use `stable`, `insiders`, or a version number (e.g., `1.32.0`). The last parameter is the path of the test.

2 - Now you can call these scripts on CI. Following, a script to run on GitHub actions:

```yaml
on:
  push:
    branches:

jobs:
  test:
    name: Test
    strategy:
      matrix:
        os: [ubuntu-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 16
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Run test - No workspace
        uses: GabrielBB/xvfb-action@v1.0
        with:
          run: npm run tests:ci:no-workspace
      - name: Run test - With workspace
        uses: GabrielBB/xvfb-action@v1.0
        with:
          run: npm run tests:ci:with-workspace
```

## Writing your first test using `jest-environment-vscode-extension`

It's almost the same idea as writing any other test using Jest, but we have a powerful API focused on VSCode.

Let's do a walkthrough writing a simple test. We want to test if the "go to the definition" works well at the second `x`:

```js
const x = 42
console.log(x)
```

1 - Firstly, our test doesn't depend on a workspace. Then we'll write it at `tests/no-workspace/definitions.test.ts`. Usually, a test depends on a workspace if it interacts with other files on the same workspace.

2 - Let's write the test itself:

```js
// get some things from the global variable `vscode`
const { Position, Range } = vscode

describe('#Definition', () => {
  it('on message interpolation', () => {
    // create a new file
    return using({
      files: {
        'index.js': dedent(`
          const x = 42
          console.log(x)
        `),
      }},
      async (mapFileToDoc) => {
        // on the file `index.js`, take the definitions at 1:12 (the `x` within the `console.log`)
        const definitions = await take.definitions(mapFileToDoc['index.js'], new Position(1, 12))

        // assert that it's as the expected
        expect(definitions).toHaveLength(1)
        expect(definitions[0]).toMatchObject({
          originSelectionRange: new Range(new Position(1, 12), new Position(1, 13)),
          targetRange: new Range(new Position(0, 12), new Position(0, 0)),
          targetSelectionRange: new Range(new Position(0, 6), new Position(0, 7)),
        })
      })
  })
})
```

On the above test, we used some variables injected by `jest-environment-vscode-extension`: `vscode`, `using`, `dedent`, and `take`. Think of them as the Jest's `describe` or `it`, but focused on helping you while working with VSCode.

Let's talk about them!

## API

### `using`

Our most useful function.

It creates the files and, optionally, can mock VSCode's functions. It receives a callback and, when it's finished, clear the files and mocks.

#### Files

You can create as many files as needed, and their [`TextDocument`](https://code.visualstudio.com/api/references/vscode-api#TextDocument) is sent to the callback:

```js
using(
  {
    files: {
      'index.js': '"example";',
      'foo.js': '1;',
      'bar.js': '2;',
    },
  },
  async (mapFileToDoc) => {
    mapFileToDoc['index.js'] // TextDocument
    mapFileToDoc['foo.js']   // TextDocument
    mapFileToDoc['bar.js']   // TextDocument
  }
)
```

#### Mocks

There are some VSCode features in which we can't manipulate, such as the `window.showQuickPick`. But no worries! We can easily mock it:

```js
using(
  {
    files: {
      'index.js': '"example";',
    },
    mocks: {
      'window.showQuickPick': async () => 'My Option',
    },
  },
  async (mapFileToDoc) => {

  }
)
```

Now, if the extension calls `window.showQuickPick` it'll return `Promise<'My Option'>`.

But there is a rule to use mocks: You should ensure that the extension is initialized. For example, let's say that your extension is initialized only when there is a `.ml` file in the workspace:

```json
"activationEvents": [
  "workspaceContains:**/*.ml"
]
```

So you should run the tests using workspace and create at least one `.ml` file:

```js
using(
  {
    files: {
      'main.ml': 'let hello () = print_endline "hey there"',
    },
    mocks: {
      'window.showQuickPick': async () => 'My Option',
    },
  },
  async (mapFileToDoc) => {

  }
)
```

### `dedent`

Function to remove indentation. Helpful with `using`.

### `vscode`

It's the same `vscode` used by the extension itself. So you can use it to manipulate the VSCode.

For example, if you want to open and show a document, you should do:

```js
const { workspace, window } = vscode

const doc = await workspace.openTextDocument(mapFileToDoc['index.js'])
await window.showTextDocument(doc)
```

It doesn't export the types. If you want them, you should do:

```ts
import type { Position } from 'vscode'

const printPosition = (position: Position) => {
  console.log({
    line: position.line,
    character: position.character,
  })
}
```

### `take`

It exposes many helper functions to take values from the VSCode. Just use TypeScript's intellisense to explore what it has.

### `waitFor`

It exposes a helper function to wait for something.

For example, if your extension takes time to initialize, it can be useful:

```js
const waitForDocumentSymbols = async (doc, position) => {
  return await waitFor(async () => {
    const hovers = await take.hovers(doc, position)
    expect(hovers).toHaveLength(1)
    return hovers
  })
}

describe("#Document Symbol", () => {
  it("includes function declaration", () => {
    return using(
      {
        files: {
          'main.ml': 'let hello () = print_endline "hey there"',
        },
      },
      async (mapFileToDoc) => {
        const symbols = await waitForDocumentSymbols(mapFileToDoc['main.ml'])

        expect(symbols[0]).toMatchObject({
            name: 'hello',
            detail: 'unit -> unit',
        })
      }
    )
  })
})
```

## Who is using

<table align="center">
  <tr>
    <td align="center" width="50%">
      <img src="https://github.com/macabeus/vscode-fluent/raw/master/docs/featured-image.png">
      <br />
      <strong><a href="https://github.com/macabeus/vscode-fluent">vscode-fluent</a></strong>,
      extension for Fluent, the correct-by-design l10n programming language
    </td>
    <td align="center" width="50%">
      <i><a href="https://github.com/macabeus/jest-environment-vscode-extension/issues/new">Add your project here</a></i>
    </td>
  </tr>
</table>

---
_Source: https://npm.io/package/jest-environment-vscode-extension · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
