diff --git a/docs/python/testing.md b/docs/python/testing.md index a75db9a534..683c2d7c12 100644 --- a/docs/python/testing.md +++ b/docs/python/testing.md @@ -313,6 +313,32 @@ Below are all the supported commands for testing with the Python extension in VS | **Testing: Focus on Test Explorer View** | Open the Test Explorer view. Similar to **Testing: Focus on Python View** on versions prior to 2021.9. | **Test: Stop Refreshing Tests** | Cancel test discovery. | +## 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 your `settings.json` [file](/docs/getstarted/settings.md#settingsjson). +2. Add `MANAGE_PY_PATH` as an environment variable: + 1. Create a `.env` file at the root of your project. + 2. Add `MANAGE_PY_PATH=''` to the `.env` file, replacing `` with the path to your application's `manage.py` file. + > **Tip**: you can copy the path by right clicking on the file in the Explorer view and selecting **Copy Path**. +3. Add Django test arguments to `"python.testing.unittestArgs": []` in the `settings.json` [file](/docs/getstarted/settings.md#settingsjson) as needed, and remove any arguments that are not compatible with Django. + +> **Note**: By default, the Python extension looks for and loads `.env` files at the project root. If your `.env` file is not at the project root or you are using [VS Code variable substitution](/docs/editor/variables-reference.md), add `"python.envFile": "${workspaceFolder}/"` to your `settings.json` [file](/docs/getstarted/settings.md#settingsjson). This enables the Python extension to load the environment variables from this file when running and discovering tests. Get more info about [Python environment variables](/docs/python/environments.md#_environment-variables). + +Navigate to the Testing view, and select the **Refresh 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 the **Python** Output panel. They might provide a hint as to why your tests are not being discovered. +- Try to [run the Django tests in the terminal](https://docs.djangoproject.com/en/dev/topics/testing/overview/#running-tests). Then "translate" the same command into VS Code settings. + For example, if you run `python manage.py test --arg` in the terminal, you would add `MANAGE_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 the **Python** Output panel. +- Use the absolute path to the `manage.py` file when setting the `MANAGE_PY_PATH` environment variable, if you initially used the relative path. + ## IntelliSense for pytest [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) offers IntelliSense features that can help you work more efficiently with [pytest fixtures](https://docs.pytest.org/en/6.2.x/fixture.html) and [parameterized tests](https://docs.pytest.org/en/6.2.x/parametrize.html).