vscode-jest

Getting Started

This extension supports full jest features in vscode environment to make testing more intuitive and fun. It should work out-of-the-box for most common jest projects. To get started:

1. Setup jest in your project if you haven't.
2. install "Jest" extension in vscode.
3. reload or restart vscode

If the extension can find the jest command, by default it will automatically run and monitor all tests in watch mode upon launch, and you should see tests, status, errors, coverage (if enabled) in TestExplorer and editors like this:

If you have a more sophisticated project configuration or prefer to run tests differently, fear not, the extension supports extensive customization settings. For example:

• you can use jest.jestCommandLine to tell the extension to use yarn test instead of the default jest command.
• you can use jest.autoRun to optimize performance and control when the extension should run your tests.
• you can use the extension with monorepo projects, see monorepo project support for details.

You can see the full features and learn more details in the How-To section. If you encounter an unexpected error, feel free to checkout the Troubleshooting or file an issue.

Happy testing!

Release Notes

Stable: v4.6.0

• added a new setting "jest.showTerminalOnLaunch" to control if test explorer terminal should be automatically opened upon launch. Default is true.
• refactor README

Previous Releases

Content

• vscode-jest
  • Getting Started
  • Release Notes
  • Features
  • Installation
  • How To?
    • How to set up the jest command?
    • How to trigger the test run?
    • How to debug tests?
    • How to use code coverage?
    • How to use the extension with monorepo projects?
    • How to read the StatusBar?
    • How to use the Test Explorer?
    • How to see more debug info (self-diagnosis)?
  • Customization
    • Settings
      • Details
        • jestCommandLine
        • rootPath
        • debugCodeLens.showWhenTestStateIn
        • coverageFormatter
        • coverageColors
        • autoRun
        • testExplorer
    • Debug Config
    • Debug Config v2
  • Commands
  • Menu
  • Troubleshooting
    • Jest failed to run
    • I don't see "Jest" in the bottom status bar
    • The extension seems to consume high CPU
    • The tests and status do not match or some tests showing question marks unexpectedly?
  • Want to Contribute?
  • License

Features

• Starts Jest automatically when you're in a root folder project with Jest installed.
• Show individual fail / passes inline.
• Show fails inside the problem inspector.
• Highlights the errors next to the expect functions.
• Adds syntax highlighting to snapshot files.
• A one button update for failed snapshots.
• Show coverage information in files being tested.
• Help debug jest tests in vscode.
• Supports multiple test run modes (automated, manual, and hybrid onSave) to meet user's preferred development experience.
• Track and shows overall workspace/project test stats

Installation

Simply open Jest - Visual Studio Marketplace and click "Install". Alternatively open Visual Studio Code, go to the extension view and search for "Jest".

For detailed releases and migration help, please see releases.

How To?

How to set up the jest command?

The extension starts jest on behave of the user, therefore a valid Jest command is the minimal required info.

• default jest command This extension can automatically start the jest process without any custom configuration if:

  • it finds Jest installed in the workspace: node_modules/.bin/jest
  • it finds the workspace has been bootstrapped with create-react-app: node_modules/react-scripts/node_modules/.bin/jest or node_modules/react-native-scripts

• custom jest command

  • if no default jest command is found, the extension will fail unless a custom jest command is configured.
  • user can set custom jest command with jest.jestCommandLine setting, for example "jest.jestCommandLine": "yarn test" .
  • or to use the Setup Wizard via command "Jest: Setup Extension (Beta)".

How to trigger the test run?

By default, users need not do anything, the extension will automatically trigger related test run when needed by running jest in the watch mode. However, this can be easily changed if more granular control is desired. Below shows the execution models supported and how to use jest.autoRun to opt into it:

Note: other than the "off" mode, users can specify the "onStartup" option for any "jest.autoRun" config, for example: {"watch": false, "onSave": "test-file", "onStartup": ["all-tests"]}

How to debug tests?

A test can be debugged via the debug codeLens appeared above the debuggable tests. Simply clicking on the codeLens will launch vscode debugger for the specific test. The extension also supports parameterized tests and allows users to pick the specific parameter set to debug.

The simplest use cases should be supported out-of-the-box. If VS Code displays errors about the attribute program or runtimeExecutable not being available, you can either use setup wizard to help or create your own debug configuration within launch.json. See more details in Customization - Debug Config.

How to use code coverage?

Code coverage can be triggered via Command Palette, select command like Jest: Toggle Coverage to activate or deactivate code coverage (see full list in commands. The coverage state is also shown in the StatusBar:

⚠️ In rare cases, coverage info might be less than what it actual is in "watch" mode (with --watch flag), where only changed files/tests are run (see facebook/jest#1284).

How to use the extension with monorepo projects?

The recommended approach is to setup the monorepo project as a multi-root workspaces in vscode. This is a simple one time setup that add each sub package as a "folder" in the workspace.

You can use jest.disabledWorkspaceFolders setting to exclude non-jest folders, if needed.

Note: While you can use jest projects to run all tests without multi-root workspaces, you won't be able to take advantage a more fine grained control such as toggle coverage for a specific package instead of all packages.

How to read the StatusBar?

StatusBar shows 2 kinds of information: Jest shows the mode and state of the "active" workspace folder. Jest-WS shows the total test suite stats for the whole workspace. Clicking on each of these button will reveal the OUTPUT channel with more details.

Illustration

shows the active workspace has coverage on.

shows the active workspace has onSave for test file only, and that the workspace stats is out of sync with the code, such as when the source file is changed but the related tests are not run yet.

shows the autoRun will be triggered by either test or source file changes.

How to use the Test Explorer?

Users with vscode v1.59 and vscode-jest v4.1 and up will start to see tests appearing in the test explorer automatically. Test explorer provides a "test-centric" view (vs. "source-centric" view in the editors), allows users to run/debug tests directly from the explorer (in addition to the inline debug codeLens), and provides a native terminal output experience (with colors!):

You can further customize the explorer with jest.testExplorer in settings.

However, test explorer is new and some features are still work-in-progress or not available yet:

• can't turn on/off coverage yet (pending on vscode API change)
• not able to accurately indicate run/debug eligibility on the item level, this means you might not be able to run/debug some items through run/debug buttons. (pending on vscode API change)
• the tests stats on the top of the explorer might not be accurate, especially for multiroot workspaces. (pending on vscode fix))
• for watch-mode workspaces, the run button is turned off since tests will be automatically executed.
• debug can only be executed for the test blocks, not on the file or folder level. (Please let us know if you have an use case otherwise)

How to see more debug info (self-diagnosis)?

It is usually helpful to see the actual command and shell environment the extension spawned for your project. You can see them in the developer console (via Help > Toggle Developer Tools menu), for example to examine the PATH environment variables: look for the "spawn" log, expand the "options" object, expand "env" property, all env variables (inherited from vscode process) should be there (view animation).

You can also see process output in the following methods:

• The color coded process output terminal from TestExplorer. If it is not open or not updated, you can manually open it from TestExplore view (the square arrow icon on the top of the Explorer View)
• Otherwise you can see the output in "OUTPUT" channel, which is usually named after the workspace folder, such as Jest (your-workspace-name). Or you can click on Jest label on status bar to show Jest Output window. This will show you the jest run output and the errors.

You can also turn on the debug mode to see more internal debugging message in the developer console:

• set "jest.debugMode": true in .vscode/settings.json

Customization

Settings

Users can use the following settings to tailor the extension for their environments.

• All settings are prefixed with jest and saved in standard .vscode/settings.json.
• settings crossed out are to be deprecated in the future
• settings marked with 💼 apply to the whole project, otherwise per workspace.

Details

jestCommandLine

This should be the command users used to kick off the jest tests in the terminal. However, since the extension will append additional options at run time, please make sure the command line can pass along these options, which usually just means if you uses npm, add an additional "--" at the end (e.g. "npm run test --") if you haven't already in your script. It is recommended not to add the following options as they are managed by the extension: --watch, --watchAll, --coverage

rootPath

If your project doesn't live in the root of your repository, you may want to customize the jest.rootPath setting to enlighten the extension as to where to look. For instance: "jest.rootPath": "src/client-app" will direct the extension to use the src/client-app folder as the root for Jest.

debugCodeLens.showWhenTestStateIn

Possible status are: [ "fail", "pass", "skip", "unknown"]. Please note that this is a window level setting, i.e. its value will apply for all workspaces.

coverageFormatter

There are 2 formatters to choose from:

(Note, there is an known issue in vscode (microsoft/vscode#5923) that gutter decorators could interfere with debug breakpoints visibility. Therefore, you probably want to disable coverage before debugging or switch to DefaultFormatter)

coverageColors

Besides the formatter, user can also customize the color via jest.coverageColors to change color for 3 coverage categories: "uncovered", "covered", or "partially-covered",

"jest.coverageColors": {
  "uncovered": "rgba(255,99,71, 0.2)",
  "partially-covered": "rgba(255,215,0, 0.2)",
}

"jest.coverageColors": {
  "covered": "rgba(9, 156, 65, 0.4)",
  "uncovered": "rgba(121, 31, 10, 0.4)",
  "partially-covered": "rgba(235, 198, 52, 0.4)",
}

autoRun

AutoRun =
  | 'off'
  | { watch: true, onStartup?: ["all-tests"] }
  | {
      watch: false,
      onStartup?: ["all-tests"],
      onSave?: 'test-file' | 'test-src-file',
    }

testExplorer

testExplorer =
  | {enabled: true; showClassicStatus?: boolean; showInlineError?: boolean}
  | {enabled: false}

• enabled: switch to turn on/off the explorer support. Default is true.
• showClassicStatus: (optional) show status symbol (prior to 4.1) in editor gutter, in addition to explorer status symbols. Default is false if explorer is enabled.
• showInlineError: (optional) show vscode style inline error and error message viewer. Default is false.

4.1 default is "jest.testExplorer": {"enabled": true}

Debug Config

This extension looks for jest specific debug config ("vscode-jest-tests" or "vscode-jest-tests.v2") in the workspace .vscode/launch.json. If not found, it will attempt to generate a default config that should work for most standard jest or projects bootstrapped by create-react-app.

If the default config is not working for your project, you can either use the setup wizard, probably the easier approach (available in v4), or edit the launch.json file manually.

If you choose to edit the launch.json manually, you can use the jest templates, such as "Jest: Default jest configuration" or "Jest: create-react-app", as a starting point. See more detail on how to add debug config in vscode Debugging.

There are many information online about how to setup vscode debug config for specific environments/frameworks, you might find the following helpful:

• vscode debug config properties
• Launch configurations for common scenarios
• vscode-recipes for debug jest tests

Debug Config v2

v4.3 introduces a "variable substitution" based config with name "vscode-jest-tests.v2". The extension will merely substitute the jest variables in the config, without adding/removing anything else.

Currently supported variables:

• ${jest.testNamePattern} - will be replaced by the test block's full name (include the surrounding describe block names).
• ${jest.testFile} - will be replaced by the test file name.
• ${jest.testFilePattern} - will be replaced by the test file name suitable for regex arguments such as --testPathPattern.

Commands

This extension contributes the following commands and can be accessed via Command Palette:

In addition, TestExplorer also exposed many handy commands, see the full list by searching for testing in vscode keyboard shortcuts editor. One can assign/change keyboard shortcut to any of these commands, see vscode Key Bindings for more details.

Menu

User can trigger the following action from the text editor context-menu

Please see vscode Key Bindings if you want to change the keyboard shortcut.

Troubleshooting

Sorry you are having trouble with the extension. If your issue did not get resolved after checking out the how-to section and the tips below, feel free to ask the community, chances are some one else had a similar experience and could help resolving it.

Jest failed to run

If you can't run jest in the terminal, please reference jest configuration to setup accordingly.

If you can run jest manually in the terminal but the extension showed error like "xxx ended unexpectedly", following are the most common causes (see self-diagnosis if you need more debug info):

• runtime environment issue: such as the shell env is not fully initialized upon vscode start up. A good indicator is messages prefixed with "env:", such as env: node: No such file or directory
  • Most likely the child_process environment the extension used to run jest is not correctly initialized. There are many possible causes, sometimes restarting vscode from a terminal will fix it, otherwise feel free to check out a more in-depth explanation and suggestions here.
• jest command line issue: such as you usually run yarn test but the extension uses the default jest instead.
  • Try configuring the jest.jestCommandLine to mimic how you run jest from the terminal, such as yarn test or npm run test --. The extension can auto-config common configurations like create react apps but not custom scripts like CRACO.
  • or you can use the "Run Setup Wizard" button in the error panel to resolve the configuration issue, see Setup Wizard.
• monorepo project issue: you have a monorepo project but not setup as a multi-root workspace.
  • see monorepo projects on how to set it up correctly.

There could be other causes, such as jest test root path is different from the project's, which can be fixed by setting jest.rootPath. Feel free to check out the customization section to manually adjust the extension if needed.

I don't see "Jest" in the bottom status bar

This means the extension is not activated.

vscode will automatically activate the extension upon detecting any of the following files from the project root directory:

• jest config file (jest.json, jest.config.js, jest.config.ts, jest.config.mjs, jest.config.cjs)
• jest command (node_modules/.bin/jest, node_modules/react-scripts/node_modules/.bin/jest)
• react-native script (node_modules/react-native-scripts)

If none of the activation criteria is met because

• you have a monorepo project: see monorepo projects support.
• your source and tests are not in the project root directory: try jest.rootPath to point to that directory instead.

Users can also try to manually activate the extension via command palette: "Jest: Start All Runners"

The extension seems to consume high CPU

By default the extension will run all tests when it is launched followed by a jest watch process. If you have many resource intensive tests or source files that can trigger many tests when changed, this could be the reason. Check out jest.autoRun to see how you can change and control when and what tests should be run.

The tests and status do not match or some tests showing question marks unexpectedly?

If your test file happen to have parameterized tests, i.e. test.each variations, please make sure you have jest version >= 26.5.

If the above did not resolve your issue, please see the self-diagnosis to show more insight of why the test and result could not be matched.

Want to Contribute?

Thanks for considering! Check here for useful tips and guidelines.

License

vscode-jest is MIT licensed.