Python testing in Visual Studio Code

ThePython extension builds on the built-intesting features in VS Code and provides test discovery, test coverage, and running and debugging tests for Python's built-inunittest framework andpytest.

Configure tests

When the Python extension is installed and a Python file is open within the editor, a test beaker icon displays on the VS Code Activity Bar representing theTest Explorer view. Opening the Test Explorer shows aConfigure Python Tests button if a test framework is not enabled. SelectingConfigure Python Tests prompts you to select a test framework and a folder containing the tests. If you use unittest, you also select the file glob pattern used to identify your test files.

Tests can be configured anytime by using thePython: Configure Tests command from theCommand Palette or by setting eitherpython.testing.unittestEnabled orpython.testing.pytestEnabled in the Settings editor orsettings.json file as described in the VS CodeSettings documentation. Each framework also has specific configuration settings as described underTest configuration settings for their folders and patterns.

If you enable pytest and it is not currently installed in the activated environment, the Python extension attempts to install it in the background. Furthermore, if both frameworks are enabled, the Python extension only runspytest.

Test discovery

By default, the Python extension attempts to discover tests once you enable a framework. You can trigger test discovery at any time using theTest: Refresh Tests command from the Command Palette.

Test discovery applies the discovery patterns for the current framework (which can be customized using theTest configuration settings). The default behavior is as follows:

• python.testing.unittestArgs: Looks for any Python (.py) file with "test" in the name in the top-level project folder. All test files must be importable modules or packages. You can customize the file matching pattern with the-p configuration setting, and customize the folder with the-t setting.

• python.testing.pytestArgs: Looks for any Python (.py) file whose name begins with "test_" or ends with "_test", located anywhere within the current folder and all subfolders.

If the test discovery succeeds, you'll see tests listed in the Test Explorer:

When triggering test discovery directly from the Test Explorer, you can also cancel an ongoing test discovery call. Use theCancel button, which replaces theRefresh button during discovery.

If discovery fails (for example, the test framework isn't installed or you have a syntax error in your test file), you'll see an error message displayed in the Test Explorer including a link to the logs. You can check thePython output panel to see the entire error message (use theView >Output menu command to show theOutput panel, then selectPython from the dropdown on the right side).

Run tests

You can run tests using any of the following actions:

• With a test file open, select the green run icon that is displayed in the gutter next to the test definition line, as shown in the previous section. This command runs only that one method.

  

• From the Command Palette, by running any of the following commands:

  • Test: Run All Tests - Runs all tests that have been discovered.
  • Test: Run Tests in Current File - Runs all tests in a file that that is open in the editor.
  • Test: Run Test at Cursor - Runs only the test method under your cursor in the editor.

• From theTest Explorer:

  • To run all discovered tests, select the play button at the top ofTest Explorer:

    

  • To run a specific group of tests, or a single test, select the file, class, or test, then select the play button to the right of that item:

    

  • You can also run a selection of tests through the Test Explorer. To do that,Ctrl+Click (orCmd+Click on macOS) on the tests you wish to run, right-click on one of them and then selectRun Test.

After a test run, VS Code displays results directly in the editor as gutter decorations. Failed tests will also be highlighted in the editor, with a Peek View that displays the test run error message and a history of all of the tests' runs. You can pressEscape to dismiss the view, and you can disable it by opening the User settings (Preferences: Open Settings (UI) command in theCommand Palette) and changing the value of theTesting: Automatically Open Peek View setting tonever.

In theTest Explorer, results are shown for individual tests and any classes and files containing those tests. Folders will display a failure icon if any of the tests within that folder did not pass.

VS Code also shows test results in theTest Results panel.

Run tests with coverage

To run tests with coverage enabled, select the coverage run icon in the Test Explorer or theRun with coverage option from any menu you normally trigger test runs from. The Python extension runs coverage using thepytest-cov plugin if you are using pytest, or withcoverage.py for unittest.

Once the coverage run completes, lines are highlighted in the editor for line-level coverage. Test coverage results appear as a "Test Coverage" sub-tab in the Test Explorer, which you can also navigate to withTesting: Focus on Test Coverage View in the Command Palette (⇧⌘P (Windows, LinuxCtrl+Shift+P)). On this panel, you can view line coverage metrics for each file and folder in your workspace, as well as branch coverage, if relevant.

For finer grain control of your coverage run when using pytest, you can edit thepython.testing.pytestArgs setting to include your specifications. When the pytest argument--cov exists inpython.testing.pytestArgs, the Python extension will make no additional edits to coverage args, to allow your customizations to take effect. If there is no--cov argument found, the extension will add--cov=. to the pytest args prior to run to enable coverage at the workspace root.

For more information on test coverage, visit VS Code'sTest Coverage documentation.

Debug tests

To debug tests, right-click on the gutter decoration next to the function definition and selectDebug Test, or select theDebug Test icon next to that test in theTest Explorer.

You can use the following commands from the Command Palette to debug tests:

• Test: Debug All Tests - Launches the debugger for all tests in your workspace.
• Test: Debug Tests in Current File - Launches the debugger for the tests you have defined in the file you have open in the editor.
• Test: Debug Test at Cursor - Launches the debugger only for the method where you have your cursor focused on the editor. You can also use theDebug Test icons in Test Explorer to launch the debugger for all tests in a selected scope and all discovered tests.

You can also change the default behavior of clicking on the gutter decoration to debug tests instead of run, by changing thetesting.defaultGutterClickAction setting value todebug in yoursettings.json file.

The debugger works the same for tests as for other Python code, including breakpoints, variable inspection, and so on. To customize settings for debugging tests, you can specify test debug configs in either thelaunch.json orsettings.json files in the.vscode folder from your workspace by adding the"purpose": ["debug-test"] to your config. This configuration will be used when you runTest: Debug All Tests,Test: Debug Tests in Current File andTest: Debug Test at Cursor commands.

For example, the configuration below in thelaunch.json file disables thejustMyCode setting for debugging tests:

{  "name":"Python: Debug Tests",  "type":"debugpy",  "request":"launch",  "program":"${file}",  "purpose": ["debug-test"],  "console":"integratedTerminal",  "justMyCode":false}

If you have more than one configuration entry with"purpose": ["debug-test"], the first definition will be used since we currently don't support multiple definitions for this request type.

For more information on debugging or to understand how it works in VS Code, read thePython debugging configurations and general VS CodeDebugging articles.

Run tests in parallel

Support for running tests in parallel with pytest is available through thepytest-xdist package. Visit theirdocumentation, for more information on how to usepytest-xdist.

Whenxdist is enabled and no worker count is specified in the arguments, the number of workers is automatically optimized by the Python extension based on how many tests are selected in the Test Explorer.

Django unit tests

The Python extension also offers support for discovering and running Django unit tests! You can get your Django tests discovered with only a few additional setup steps:

1. Set"python.testing.unittestEnabled": true, in yoursettings.jsonfile.
2. AddMANAGE_PY_PATH as an environment variable:
   1. Create a.env file at the root of your project.
   2. AddMANAGE_PY_PATH='<path-to-manage.py>' to the.env file, replacing<path-to-manage.py> with the path to your application'smanage.py file.

      Tip: you can copy the path by right clicking on the file in the Explorer view and selectingCopy Path.

3. Add Django test arguments to"python.testing.unittestArgs": [] in thesettings.jsonfile as needed, and remove any arguments that are not compatible with Django.

Navigate to the Testing view, and select theRefresh Tests button to have your Django tests displayed!

Troubleshooting

If your Django unit tests are not showing in the Testing view, try the following troubleshooting steps:

• Search for error messages in thePython Output panel. They might provide a hint as to why your tests are not being discovered.
• Try torun the Django tests in the terminal. Then "translate" the same command into VS Code settings.For example, if you runpython manage.py test --arg in the terminal, you would addMANAGE_PY_PATH='./manage.py' to a.env file, and set"python.testing.unittestArgs": [--arg] in the VS Code settings. Alternatively, you can also find the commands that are run by the Python extension in thePython Output panel.
• Use the absolute path to themanage.py file when setting theMANAGE_PY_PATH environment variable, if you initially used the relative path.

Test commands

Below are all the supported commands for testing with the Python extension in VS Code. These are all found via the Command Palette:

Test configuration settings

The behavior of testing with Python is driven by general UI settings provided by VS Code, and settings that are specific to Python and to whichever framework you've enabled.

General UI settings

The settings that affect the UI of the testing features are provided by VS Code itself, and can be found in theVS Code Settings editor when you search for "Testing".

General Python settings

unittest configuration settings

The default arguments for unittest are as follows:

• -v sets default verbosity. Remove this argument for simpler output.
• -s . specifies the starting directory for discovering tests. If you have tests in a "test" folder, change the argument to-s test (meaning"-s", "test" in the arguments array).
• -p *test*.py is the discovery pattern used to look for tests. In this case, it's any.py file that includes the word "test". If you name test files differently, such as appending "_test" to every filename, then use a pattern like*_test.py in the appropriate argument of the array.

To stop a test run on the first failure, add the fail fast option"-f" to the arguments array.

Seeunittest command-line interface for the full set of available options.

pytest configuration settings

The default arguments for pytest are as follows:

• rootdir is dynamically adjusted based on the presence of apython.testing.cwd setting in your workspace.

You can also configure pytest using apytest.ini file as described onpytest Configuration.

IntelliSense settings

See also

• Python environments - Control which Python interpreter is used for editing and debugging.
• Settings reference - Explore the full range of Python-related settings in VS Code.