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 installed
• A Python project managed with uv
• pytest installed as a dev dependency:

uv add --dev pytest

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, the pytestArgs in .vscode/settings.json can stay empty:

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

Cursor reads pyproject.toml configuration the same way the terminal does, because the Python extension invokes the pytest binary from .venv directly.

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 tests still fail with ModuleNotFoundError after uv sync, run uv sync and reload the Cursor window to let the language server re-index the environment.

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

Cursor’s AI agent spawns a fresh shell per command and does not inherit your activated virtual environment. Without an explicit rule, the agent may suggest pytest (resolving to a system installation) instead of uv run pytest (which uses the locked versions in .venv).

Create a pytest rule via the Command Palette: search for New Cursor Rule, name it pytest, set the Rule Type to Agent Requested, and add this description:

Run pytest, execute tests, fix failing tests, check test coverage, or debug test errors in a Python project.

Rule body:

# Running pytest in a uv project

Always run pytest via uv to use the correct virtual environment:

- Run all tests: `uv run pytest`
- Run a specific file: `uv run pytest tests/test_foo.py`
- Run one test: `uv run pytest tests/test_foo.py::test_name`
- Run with verbose output: `uv run pytest -v`
- Stop after first failure: `uv run pytest -x`
- Re-run only failures: `uv run pytest --last-failed`

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: Run uv sync, then reload the window (Cmd+Shift+P → Developer: Reload Window) to re-index the environment.

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.

Learn More

• How to configure Cursor for a uv project covers the full editor setup including Ruff, type checking, and interpreter selection
• How to configure Cursor rules to use uv
• How to run tests using uv
• Setting up testing with pytest and uv
• pytest reference