pytest-language-server 🔥

A blazingly fast Language Server Protocol (LSP) implementation for pytest, built with Rust, with full support for fixture discovery, go to definition, code completion, find references, hover documentation, diagnostics, and more!

Features
Installation
Setup
Configuration
CLI Commands
Supported Fixture Patterns
Fixture Priority Rules
Supported Third-Party Fixtures
Architecture
Development
Security
Contributing
License
Acknowledgments

Features

Built with AI, maintained with care 🤖

This project was built with the help of AI coding agents, but carefully reviewed to ensure correctness, reliability, security and performance. If you find any issues, please open an issue or submit a pull request!

🎯 Go to Definition

Jump directly to fixture definitions from anywhere they're used:

Local fixtures in the same file
Fixtures in conftest.py files
Third-party fixtures from pytest plugins (pytest-mock, pytest-asyncio, etc.)
Respects pytest's fixture shadowing/priority rules

✨ Code Completion

Smart auto-completion for pytest fixtures:

Context-aware: Only triggers inside test functions and fixture functions
Hierarchy-respecting: Suggests fixtures based on pytest's priority rules (same file > conftest.py > third-party)
Rich information: Shows fixture source file and docstring
No duplicates: Automatically filters out shadowed fixtures
Works everywhere: Completions available in both function parameters and function bodies
Supports both sync and async functions

🔍 Find References

Find all usages of a fixture across your entire test suite:

Works from fixture definitions or usage sites
Character-position aware (distinguishes between fixture name and parameters)
Shows references in all test files
Correctly handles fixture overriding and hierarchies
LSP spec compliant: Always includes the current position in results

📚 Hover Documentation

View fixture information on hover:

Fixture signature
Source file location
Docstring (with proper formatting and dedenting)
Markdown support in docstrings

💡 Code Actions (Quick Fixes)

One-click fixes for common pytest issues:

Add missing fixture parameters: Automatically add undeclared fixtures to function signatures
Smart insertion: Handles both empty and existing parameter lists
Editor integration: Works with any LSP-compatible editor's quick fix menu
LSP compliant: Full support for CodeActionKind::QUICKFIX

⚠️ Diagnostics & Quick Fixes

Detect and fix common pytest fixture issues with intelligent code actions:

Undeclared Fixture Detection:

Detects when fixtures are used in function bodies but not declared as parameters
Line-aware scoping: Correctly handles local variables assigned later in the function
Hierarchy-aware: Only reports fixtures that are actually available in the current file's scope
Works in tests and fixtures: Detects undeclared usage in both test functions and fixture functions
Excludes built-in names (self, request) and actual local variables

One-Click Quick Fixes:

Code actions to automatically add missing fixture parameters
Intelligent parameter insertion (handles both empty and existing parameter lists)
Works with both single-line and multi-line function signatures
Triggered directly from diagnostic warnings

Example:

@pytest.fixture
def user_db():
    return Database()

def test_user(user_db):  # ✅ user_db properly declared
    user = user_db.get_user(1)
    assert user.name == "Alice"

def test_broken():  # ⚠️ Warning: 'user_db' used but not declared
    user = user_db.get_user(1)  # 💡 Quick fix: Add 'user_db' fixture parameter
    assert user.name == "Alice"

How to use quick fixes:

Place cursor on the warning squiggle
Trigger code actions menu (usually Cmd+. or Ctrl+. in most editors)
Select "Add 'fixture_name' fixture parameter"
The parameter is automatically added to your function signature

⚡️ Performance

Built with Rust for maximum performance:

Fast workspace scanning with concurrent file processing
Efficient AST parsing using rustpython-parser
Lock-free data structures with DashMap
Minimal memory footprint

Installation

Choose your preferred installation method:

📦 PyPI (Recommended)

The easiest way to install for Python projects:

# Using uv (recommended)
uv tool install pytest-language-server

# Or with pip
pip install pytest-language-server

# Or with pipx (isolated environment)
pipx install pytest-language-server

🍺 Homebrew (macOS/Linux)

Install via Homebrew for system-wide availability:

brew install bellini666/tap/pytest-language-server

To add the tap first:

brew tap bellini666/tap https://github.com/bellini666/pytest-language-server
brew install pytest-language-server

🦀 Cargo (Rust)

Install from crates.io if you have Rust installed:

cargo install pytest-language-server

📥 Pre-built Binaries

Download pre-built binaries from the GitHub Releases page.

Available for:

Linux: x86_64, aarch64, armv7 (glibc and musl)
macOS: Intel and Apple Silicon
Windows: x64 and x86

🔨 From Source

Build from source for development or customization:

git clone https://github.com/bellini666/pytest-language-server
cd pytest-language-server
cargo build --release

The binary will be at target/release/pytest-language-server.

Setup

Neovim

Add this to your config:

vim.lsp.config('pytest_lsp', {
  cmd = { 'pytest-language-server' },
  filetypes = { 'python' },
  root_markers = { 'pyproject.toml', 'setup.py', 'setup.cfg', 'pytest.ini', '.git' },
})

vim.lsp.enable('pytest_lsp')

Zed

Install from the Zed Extensions Marketplace:

Open Zed
Open the command palette (Cmd+Shift+P / Ctrl+Shift+P)
Search for "zed: extensions"
Search for "pytest Language Server"
Click "Install"

The extension downloads platform-specific binaries from GitHub Releases. If you prefer to use your own installation (via pip, cargo, or brew), place pytest-language-server in your PATH.

After installing the extension, you need to enable the language server for Python files. Add the following to your Zed settings.json:

{
  "languages": {
    "Python": {
      "language_servers": ["pyright", "pytest-language-server", "..."]
    }
  }
}

VS Code

The extension includes pre-built binaries - no separate installation required!

Install from the Visual Studio Marketplace:

Open VS Code
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Search for "pytest Language Server"
Click "Install"

Works out of the box with zero configuration!

IntelliJ IDEA / PyCharm

The plugin includes pre-built binaries - no separate installation required!

Install from the JetBrains Marketplace:

Open PyCharm or IntelliJ IDEA
Go to Settings/Preferences → Plugins
Search for "pytest Language Server"
Click "Install"

Requires PyCharm 2024.2+ or IntelliJ IDEA 2024.2+ with Python plugin.

Other Editors

Any editor with LSP support can use pytest-language-server. Configure it to run the pytest-language-server command.

Configuration

Logging

Control log verbosity with the RUST_LOG environment variable:

# Minimal logging (default)
RUST_LOG=warn pytest-language-server

# Info level
RUST_LOG=info pytest-language-server

# Debug level (verbose)
RUST_LOG=debug pytest-language-server

# Trace level (very verbose)
RUST_LOG=trace pytest-language-server

Logs are written to stderr, so they won't interfere with LSP communication.

Virtual Environment Detection

The server automatically detects your Python virtual environment:

Checks for .venv/, venv/, or env/ in your project root
Falls back to $VIRTUAL_ENV environment variable
Scans third-party pytest plugins for fixtures

Code Actions / Quick Fixes

Code actions are automatically available on diagnostic warnings. If code actions don't appear in your editor:

Check LSP capabilities: Ensure your editor supports code actions (most modern editors do)
Enable debug logging: Use RUST_LOG=info to see if actions are being created
Verify diagnostics: Code actions only appear where there are warnings
Trigger manually: Use your editor's code action keybinding (Cmd+. / Ctrl+.)

CLI Commands

In addition to the LSP server mode, pytest-language-server provides useful command-line tools:

Fixtures List

View all fixtures in your test suite with a hierarchical tree view:

# List all fixtures
pytest-language-server fixtures list tests/

# Skip unused fixtures
pytest-language-server fixtures list tests/ --skip-unused

# Show only unused fixtures
pytest-language-server fixtures list tests/ --only-unused

The output includes:

Color-coded display: Files in cyan, directories in blue, used fixtures in green, unused in gray
Usage statistics: Shows how many times each fixture is used
Smart filtering: Hides files and directories with no matching fixtures
Hierarchical structure: Visualizes fixture organization across conftest.py files

Example output:

Fixtures tree for: /path/to/tests

conftest.py (7 fixtures)
├── another_fixture (used 2 times)
├── cli_runner (used 7 times)
├── database (used 6 times)
├── generator_fixture (used 1 time)
├── iterator_fixture (unused)
├── sample_fixture (used 7 times)
└── shared_resource (used 5 times)
subdir/
└── conftest.py (4 fixtures)
    ├── cli_runner (used 7 times)
    ├── database (used 6 times)
    ├── local_fixture (used 4 times)
    └── sample_fixture (used 7 times)

This command is useful for:

Auditing fixture usage across your test suite
Finding unused fixtures that can be removed
Understanding fixture organization and hierarchy
Documentation - visualizing available fixtures for developers

Supported Fixture Patterns

Decorator Style

@pytest.fixture
def my_fixture():
    """Fixture docstring."""
    return 42

Assignment Style (pytest-mock)

mocker = pytest.fixture()(_mocker)

Async Fixtures

@pytest.fixture
async def async_fixture():
    return await some_async_operation()

Fixture Dependencies

@pytest.fixture
def fixture_a():
    return "a"

@pytest.fixture
def fixture_b(fixture_a):  # Go to definition works on fixture_a
    return fixture_a + "b"

@pytest.mark.usefixtures

@pytest.mark.usefixtures("database", "cache")
class TestWithFixtures:
    def test_something(self):
        pass  # database and cache are available

@pytest.mark.parametrize with indirect

@pytest.fixture
def user(request):
    return User(name=request.param)

# All parameters treated as fixtures
@pytest.mark.parametrize("user", ["alice", "bob"], indirect=True)
def test_user(user):
    pass

# Selective indirect fixtures
@pytest.mark.parametrize("user,value", [("alice", 1)], indirect=["user"])
def test_user_value(user, value):
    pass

Fixture Priority Rules

pytest-language-server correctly implements pytest's fixture shadowing rules:

Same file: Fixtures defined in the same file have highest priority
Closest conftest.py: Searches parent directories for conftest.py files
Virtual environment: Third-party plugin fixtures

Fixture Overriding

The LSP correctly handles complex fixture overriding scenarios:

# conftest.py (parent)
@pytest.fixture
def cli_runner():
    return "parent runner"

# tests/conftest.py (child)
@pytest.fixture
def cli_runner(cli_runner):  # Overrides parent
    return cli_runner  # Uses parent

# tests/test_example.py
def test_example(cli_runner):  # Uses child
    pass

When using find-references:

Clicking on the function name def cli_runner(...) shows references to the child fixture
Clicking on the parameter cli_runner(cli_runner) shows references to the parent fixture
Character-position aware to distinguish between the two

Supported Third-Party Fixtures

Automatically discovers fixtures from 50+ popular pytest plugins, including:

Testing frameworks: pytest-mock, pytest-asyncio, pytest-bdd, pytest-cases
Web frameworks: pytest-flask, pytest-django, pytest-aiohttp, pytest-tornado, pytest-sanic, pytest-fastapi
HTTP clients: pytest-httpx
Databases: pytest-postgresql, pytest-mongodb, pytest-redis, pytest-mysql, pytest-elasticsearch
Infrastructure: pytest-docker, pytest-kubernetes, pytest-rabbitmq, pytest-celery
Browser testing: pytest-selenium, pytest-playwright, pytest-splinter
Performance: pytest-benchmark, pytest-timeout
Test data: pytest-factoryboy, pytest-freezegun, pytest-mimesis
And many more...

The server automatically scans your virtual environment for any pytest plugin and makes their fixtures available.

Architecture

Language: Rust 🦀
LSP Framework: tower-lsp
Parser: rustpython-parser
Concurrency: tokio async runtime
Data Structures: DashMap for lock-free concurrent access

Development

Prerequisites

Rust 1.83+ (2021 edition)
Python 3.10+ (for testing)

Building

cargo build --release

Running Tests

cargo test

Logging During Development

RUST_LOG=debug cargo run

Security

Security is a priority. This project includes:

Automated dependency vulnerability scanning (cargo-audit)
License compliance checking (cargo-deny)
Daily security audits in CI/CD
Dependency review on pull requests
Pre-commit security hooks

See SECURITY.md for our security policy and how to report vulnerabilities.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Install pre-commit hooks:
```
pre-commit install
```
Run security checks locally:
```
cargo audit
cargo clippy
cargo test
```

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with:

tower-lsp - LSP framework
rustpython-parser - Python AST parsing
tokio - Async runtime

Special thanks to the pytest team for creating such an amazing testing framework.

Made with ❤️ and Rust. Blazingly fast 🔥

Built with AI assistance, maintained with care.

pytest-language-server 0.11.1