pytest-plugin.md

(pytest_plugin)=

pytest Plugin

With libvcs's pytest plugin for pytest, you can easily create Git, Subversion (SVN), and Mercurial repositories on the fly.

Looking for more flexibility, correctness, or power? Need different defaults? [Connect with us] on GitHub. We'd love to hear about your use case. Our APIs won't be stabilized until we're confident they meet all expectations.

[connect with us]: https://github.com/vcs-python/libvcs/discussions

Usage

Install libvcs using your preferred Python package manager:

$ python -m pip install libvcs

Once installed, pytest will automatically detect the plugin and make its fixtures available.

Fixtures

This pytest plugin provides {ref}pytest fixtures <pytest:fixtures-api> that ensure a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes session-scoped fixtures to cache the initial repositories, improving performance across tests.

(recommended-fixtures)=

Recommended Fixtures

When the plugin is enabled and pytest is run, the following overridable fixtures are automatically used:

• Create temporary test directories for:
  • /home/ ({func}home_path)
  • /home/${user} ({func}user_path)
• Set up the home directory:
  • Patch $HOME to point to {func}user_path using {func}set_home
• Create configuration files:
  • .gitconfig via {func}gitconfig
  • .hgrc via {func}hgconfig
• Configure default VCS settings:
  • Use {func}hgconfig for HGRCPATH via {func}set_hgconfig
  • Use {func}gitconfig for GIT_CONFIG via {func}set_gitconfig
• Set default commit information:
  • Name: {func}vcs_name
  • Email: {func}vcs_email
  • User (e.g., user <email@tld>): {func}vcs_user
  • Git-specific: {func}git_commit_envvars

These fixtures ensure that repositories can be cloned and created without unnecessary warnings.

Bootstrapping pytest in conftest.py

To configure the above fixtures with autouse=True, add them to your conftest.py file or test file, depending on the desired scope.

Why aren't these fixtures added automatically by the plugin? This design choice promotes explicitness and adheres to best practices for pytest plugins and Python packages.

Setting a Temporary Home Directory

To set up a temporary home directory, use the {func}set_home fixture with autouse=True:

import pytest

@pytest.fixture(autouse=True)
def setup_home(set_home: None) -> None:
    """Configure a temporary home directory for testing."""
    pass

VCS Configuration

Git

You can override the default author information used in {func}git_remote_repo and other fixtures by customizing {func}vcs_name, {func}vcs_email, or {func}vcs_user:

@pytest.fixture(scope="session")
def vcs_name() -> str:
    """Provide a custom author name for Git commits."""
    return "My custom name"

Use the {func}set_gitconfig fixture with autouse=True:

import pytest

@pytest.fixture(autouse=True)
def setup_git(set_gitconfig: None) -> None:
    """Configure Git settings for testing."""
    pass

Sometimes, set_gitconfig via GIT_CONFIG doesn't apply as expected. For those cases, you can use {func}git_commit_envvars:

import pytest
from typing import Dict, Any
from libvcs.pytest_plugin import CreateRepoPytestFixtureFn, git_remote_repo_single_commit_post_init

@pytest.fixture
def my_git_repo(
    create_git_remote_repo: CreateRepoPytestFixtureFn,
    gitconfig: pathlib.Path,
    git_commit_envvars: Dict[str, Any],
) -> pathlib.Path:
    """Create a fresh Git repository in a temporary directory.
    
    This fixture demonstrates how to create a Git repository with custom commit settings.
    """
    repo_path = create_git_remote_repo()
    git_remote_repo_single_commit_post_init(
        remote_repo_path=repo_path,
        env=git_commit_envvars,
    )
    return repo_path

The `create_git_remote_repo` fixture creates a repository once per test session and reuses it, making copies for individual tests to avoid repeated `git init` operations.

Mercurial

Use the {func}set_hgconfig fixture with autouse=True:

import pytest

@pytest.fixture(autouse=True)
def setup_hg(set_hgconfig: None) -> None:
    """Configure Mercurial settings for testing."""
    pass

Examples

For more usage examples, refer to libvcs's own tests/.

API Reference

.. automodule:: libvcs.pytest_plugin
    :members:
    :inherited-members:
    :private-members:
    :show-inheritance:
    :member-order: bysource