How to configure Cursor for pytest

Cursor’s Testing sidebar runs pytest tests without leaving the editor, shows pass/fail status inline next to each test, and opens the debugger on a single test with one click. Getting this working in a uv-managed project takes three steps: installing pytest, enabling it in .vscode/settings.json, and optionally setting pytest defaults in pyproject.toml.

Confirm prerequisites

• Cursor editor with the Python extension installed
• A Python project managed with uv
• pytest installed as a dev dependency:

uv add --dev pytest

The --dev flag marks pytest as a development dependencyA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag. , keeping it out of production installs. uv adds pytest to pyproject.toml, updates uv.lock, and installs it in .venv.

Enable pytest in Cursor

Add these settings to .vscode/settings.json at your project root:

{
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestArgs": ["tests"]
}

Open the Testing sidebar (the beaker icon in the Activity Bar, or View → Testing) and click Refresh Tests. Cursor discovers test files matching test_*.py or *_test.py inside tests/ and lists each test individually.

Configure test discovery in pyproject.toml

Keep pytest configuration in pyproject.toml so the same settings apply both in the editor and when running uv run pytest in CI:

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v"

With testpaths set in pyproject.toml, replace the earlier pytestArgs value with an empty list so pytest chooses the paths from its configuration:

{
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestArgs": []
}

The Python extension runs pytest using the selected interpreter. uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. Select .venv in Cursor so both runs use the same environment.

Set testpaths for a src/ layout

With a project created by uv init --package, the package is installed as an editable install inside .venv. Imports from your package work in tests without extra flags. Point pytest at your tests directory:

[tool.pytest.ini_options]
testpaths = ["tests"]

If pytest reports ModuleNotFoundError, check that the package is installed in the selected environment and that pytest runs from the intended project directory. Reloading the language server does not fix a test process’s import path.

Set the working directory in a monorepo

For a monorepo where the pytest configuration lives in a subdirectory, tell the Python extension which directory to use as the working directory:

{
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": [],
    "python.testing.cwd": "${workspaceFolder}/backend"
}

python.testing.cwd sets the working directory before pytest runs, so pytest finds pyproject.toml and tests/ relative to the backend subdirectory.

Run and debug tests from the sidebar

The Testing sidebar shows a run icon and a debug icon when you hover over any discovered test. The run icon executes that test alone and reports pass or fail inline. The debug icon launches the Python debugger at that test function, so you can set breakpoints and inspect variables without leaving the editor. The top-level play button at the top of the sidebar runs all discovered tests at once.

To run only tests that match a marker, add marker filtering to addopts in pyproject.toml:

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v -m 'not slow'"

Or keep addopts clean and pass the flag via pytestArgs when you want temporary filtering:

{
    "python.testing.pytestArgs": ["-m", "not slow"]
}

Add a Cursor rule for pytest

The editor’s selected interpreter and the agent’s terminal commands are separate settings. Give the agent an explicit test command so it uses the project’s environment without relying on shell activation.

Create .cursor/rules/pytest.mdc with the full contents:

---
description: Run pytest, investigate test failures, or debug Python tests.
alwaysApply: false
---
# Run pytest in this uv project

Run commands from the directory containing pyproject.toml.
Use `uv run pytest` for the full suite and append paths or flags as needed:

- One file: `uv run pytest tests/test_foo.py`
- One test: `uv run pytest tests/test_foo.py::test_name`
- Verbose output: `uv run pytest -v`
- Stop after the first failure: `uv run pytest -x`
- Re-run failures: `uv run pytest --last-failed`

The description makes this an Apply Intelligently rule: the agent chooses it when relevant. Use alwaysApply: true if the test instructions must accompany every chat.

Commit .cursor/rules/pytest.mdc to version control so all team members using Cursor get the same agent behavior.

Debug failures with Cursor Chat

When pytest prints a failing traceback in the integrated terminal, paste it into Cursor’s Chat panel and ask the AI to explain what went wrong. The AI has access to your open files and can trace the failure back to the source function.

For the best diagnosis, include the full traceback rather than just the error line. Pytest’s output includes the assertion value, the failing line, and any fixture setup errors, all of which help the AI identify the root cause.

After the AI proposes a fix, run the test again from the sidebar or with uv run pytest --last-failed to confirm the fix works.

Fix common setup problems

Tests not discovered: Run uv run pytest --collect-only in the terminal to see what pytest finds. Check that test files follow the test_*.py naming convention and that testpaths points to the right directory.

Wrong pytest version: Run uv run pytest --version. If it differs from what Cursor shows, verify the status bar interpreter is .venv. Re-select it with Python: Select Interpreter from the Command Palette.

Import errors after uv add: Compare uv run pytest with the sidebar run. If only the sidebar fails, check its selected interpreter and working directory. If both fail, fix the package installation or test configuration.

Agent uses pytest instead of uv run pytest: Add the pytest Cursor rule above. Verify it triggers by asking the agent to “run the tests” and confirming it suggests uv run pytest.