PyCharm 2023.2 Help

Vitest

PyCharm integrates with Vitest, a Vite-native unit test framework. You can run, debug, do snapshot testing, and measure test coverage both from the editor and via a run/debug configuration.

You can re-run failed tests or turn on the watch mode. When you launch a test session in this mode, PyCharm monitors changes in your project source code. As soon as any changes are made to a test or to its subject, PyCharm re-runs the affected test, you do not even have to re-start the run/debug configuration.

Before you start

  1. Make sure you have Node.js on your computer.

  2. Make sure the JavaScript and TypeScript plugin is enabled in the settings. Press Control+Alt+S to open the IDE settings and then select Plugins. Click the Installed tab. In the search field, type JavaScript and TypeScript. For more information about plugins, refer to Managing plugins.

Install Vitest

  • In the embedded Terminal (Alt+F12) , type:

    npm install --save-dev vitest

Learn more from Getting Started and Configuring Vitest on the Vitest official website.

Run and debug tests

With PyCharm, you can quickly run or debug a single Vitest test right from the editor or create a run/debug configuration to run or debug some or all of your tests.

For more information about creating Vitest tests for JavaScript and TypeScript code, refer to Vitest features on the Vitest official website.

Run or debug a single test from the editor

  • Click the Run icon or the Rerun icon in the gutter and select Run <test_name> from the list.

    Run one Vitest test from the editor

    You can also see whether a test has passed or failed right in the editor, thanks to the test status icons Test passed and Test failed in the gutter.

  • To debug a test, set a breakpoint inside it, click the Run icon or the Rerun icon in the gutter and select Debug <test_name> from the list.

    Debug one Vitest test from the editor

    In the Debug tool window, examine the suspended test and step through it.

    A Vitest debugging session

Create a Vitest run configuration

  1. Open the Run/Debug Configuration dialog (Run | Edit Configurations on the main menu), click the Add button in the left-hand pane, and select Vitest from the list. The Run/Debug Configuration: Vitest dialog opens.

  2. Specify the Node.js interpreter to use.

    If you choose the Project alias, PyCharm will automatically use the project default interpreter from the Node interpreter field on the Node.js page . In most cases, PyCharm detects the project default interpreter and fills in the field itself.

    You can also choose another configured local or remote interpreter or click the Browse button and configure a new one.

    Optionally specify the Node.js-specific option parameters and the environment variables to be passed to Node.js.

  3. Specify the location of the vitest package.

  4. Specify the working directory of the application. By default, the Working directory field shows the project root folder. To change this predefined setting, specify the path to the desired folder.

  5. Specify the tests to run. This can be a specific test or suite, an entire test file, or a folder with test files.

  6. By default, vite.config.ts is used. If vite.config.ts is missing, or you want to use a custom configuration, specify the vitest.config.ts to use. Learn more from the Vitest official website.

  7. Optionally:

    Configure rerunning tests automatically on changes in them or in the related source files. To do that, add the --watch flag in the Vitest options field.

    You can also add other Vitest options. For more information, refer to the Vitest official website.

  8. Optionally:

    In the Node options field, type the Node.js-specific command-line options to be passed to the Node.js executable file. The acceptable options are:

    • Use --require coffeescript/register to have CoffeeScript files compiled into JavaScript on the fly during run.

      This mode requires that the register.js file, which is a part of the coffeescript package, is located inside your project. Therefore make sure you have the coffeescript package installed locally as described in Install the CoffeeScript compiler.

    • Use --inspect or --inspect-brk parameter when you are using Node.js v7 for Chrome Debugging Protocol support. Otherwise, by default the debug process will use V8 Debugging Protocol.

Run tests via a run configuration

  1. Select the Vitest run/debug configuration from the list of configurations and click the Run icon   in the list or on the toolbar.

    select run/debug configuration
  2. Monitor test execution and analyze test results in the Test Runner tab of the Run tool window. For more information, refer to Explore test results.

    Vitest: test results

To debug tests, set breakpoints where necessary, select the run/debug configuration, and click the Debug button.

Rerun tests

You can rerun all the tests in the specified scope Alt+Shift+R or rerun only the tests that failed.

You can also launch tests in the --watch mode. In this mode, PyCharm monitors saved changes to tests and related test subjects. As soon as a change is detected, PyCharm reruns the affected test without stopping the current test session.

Rerun failed tests

  • In the Test Runner tab, click Rerun Failed Tests button on the toolbar. PyCharm will execute all the tests that failed during the previous session.

    Vitest: Rerunning all failed tests
  • To rerun a specific failed test, select Run <test name> on its context menu.

For more information, refer to Rerunning tests.

Rerun updated tests automatically (--watch mode)

  1. Open a Vitest run/debug configuration or create a new one as described above.

  2. In the Vitest options field, type --watch. In the autogenerated All tests configuration, the --watch option is already specified.

  3. Launch the run/debug configuration. If some tests fail, you can update them or related test subjects without stopping the test session. As soon as your changes are saved, PyCharm detects them and reruns the affected tests.

    In the example below, the test at line 29 of vue.test.ts fails. With the --watch option, the test is rerun after you replace '4 x 4 = 18' with '4 x 4 = 16' in vue.test.ts an save the changes with Control+S or move the focus from PyCharm.

    Rerun updated test in the --watch mode

Snapshot testing

PyCharm also supports Vitest snapshot testing. When PyCharm runs a test with the toMatchSnapshot() method for the first time, a snapshot file is created and a Snapshot icon appears in the gutter next to toMatchSnapshot (). Click the Snapshot icon to open the generated snapshot.

Snapshot

Monitor code coverage

With PyCharm, you can also monitor how much of your code is covered with Vitest tests. PyCharm displays this statistics in a dedicated Coverage tool window and marks covered and uncovered lines visually in the editor and in the Project tool window.

Vitest Coverage report

Enable code coverage for Vitest

Install c8 or istanbul. To do that, open the built-in Terminal Alt+F12 and type one of the following:

  • npm install --save-dev @vitest/coverage-c8

  • npm install --save-dev @vitest/coverage-istanbul.

Learn more from Coverage on the Vitest official website.

Run tests with coverage

  1. Run a specific suite or a test with coverage from the editor: click the Run button or the Rerun button in the gutter and select Run <test_name> with Coverage from the list.

    Run Vitest tests with coverage from the editor

    Alternatively:

    Create a Vitest run/debug configuration as described above. Select the Vitest run/debug configuration from the list on the main toolbar and click Run with Coverage icon  to the right of the list.

  2. Monitor the code coverage in the Coverage tool window. The report shows how many files were covered with tests and the percentage of covered lines in them. From the report you can jump to the file and see what lines were covered – marked green – and what lines were not covered – marked red:

Last modified: 07 September 2023