pytest Plugin

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

See also

Are you using libvcs?

Looking for more flexibility, correctness, or power? Need different defaults? Connect with us on GitHub. We’d love to hear about your use case—APIs won’t be stabilized until we’re confident everything meets expectations.

Usage

Install libvcs using your preferred Python package manager:

$ pip install libvcs

Pytest will automatically detect the plugin, and its fixtures will be available.

Fixtures

This pytest plugin works by providing pytest fixtures. The plugin’s fixtures ensure that a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes session-scoped fixtures to cache initial repositories, improving performance across tests.

Recommended Fixtures

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

• Create temporary test directories for:

  • /home/ (home_path())

  • /home/${user} (user_path())

• Set the home directory:

  • Patch $HOME to point to user_path() using (set_home())

• Create configuration files:

  • .gitconfig via gitconfig()

  • .hgrc via hgconfig()

• Set default VCS configurations:

  • Use hgconfig() for HGRCPATH via set_hgconfig()

  • Use gitconfig() for GIT_CONFIG via set_gitconfig()

• Set default commit names and emails:

  • Name: vcs_name()

  • Email: vcs_email()

  • User (e.g. user <email@tld>): vcs_user()

  • For git only: git_commit_envvars()

These 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, adhering to best practices for pytest plugins and Python packages.

Setting a Temporary Home Directory

To set a temporary home directory, use the set_home() fixture with autouse=True:

import pytest

@pytest.fixture(autouse=True)
def setup(set_home: None):
    pass

VCS Configuration

Git

You can override the default author used in git_remote_repo() and other fixtures via vcs_name(), vcs_email(), and vcs_user():

@pytest.fixture(scope="session")
def vcs_name() -> str:
    return "My custom name"

Use the set_gitconfig() fixture with autouse=True:

import pytest

@pytest.fixture(autouse=True)
def setup(set_gitconfig: None):
    pass

Sometimes, set_getconfig via GIT_CONFIG doesn’t apply as expected. For those cases, you can use git_commit_envvars():

import pytest

@pytest.fixture
def my_git_repo(
    create_git_remote_repo: CreateRepoPytestFixtureFn,
    gitconfig: pathlib.Path,
    git_commit_envvars: "_ENV",
) -> pathlib.Path:
    """Copy the session-scoped Git repository to a temporary directory."""
    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

Mercurial

Use the set_hgconfig() fixture with autouse=True:

import pytest

@pytest.fixture(autouse=True)
def setup(set_hgconfig: None):
    pass

Examples

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

API Reference

pytest plugin for VCS Repository testing and management.

exception libvcs.pytest_plugin.MaxUniqueRepoAttemptsExceeded(attempts, *args)

Bases: LibVCSException

Raised when exceeded threshold of attempts to find a unique repo destination.

Raise LibVCSException exception with message including attempts tried.

Parameters:

• attempts (int)

• args (object)

Return type:

None

__init__(attempts, *args)

Raise LibVCSException exception with message including attempts tried.

Parameters:

• attempts (int)

• args (object)

Return type:

None

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

libvcs.pytest_plugin.vcs_name()

Return default VCS name.

Return type:

str

libvcs.pytest_plugin.vcs_email()

Return default VCS email.

Return type:

str

libvcs.pytest_plugin.vcs_user(vcs_name, vcs_email)

Return default VCS user.

Return type:

str

Parameters:

• vcs_name (str)

• vcs_email (str)

libvcs.pytest_plugin.git_commit_envvars(vcs_name, vcs_email)

Return environment variables for git commit.

For some reason, GIT_CONFIG via {func}`set_gitconfig` doesn’t work for git commit.

Return type:

Union[Mapping[bytes, Union[str, bytes, PathLike[str], PathLike[bytes]]], Mapping[str, Union[str, bytes, PathLike[str], PathLike[bytes]]]]

Parameters:

• vcs_name (str)

• vcs_email (str)

class libvcs.pytest_plugin.RandomStrSequence(characters='abcdefghijklmnopqrstuvwxyz0123456789_')

Bases: object

Create a random string sequence.

Parameters:

characters (str)

libvcs.pytest_plugin.pytest_ignore_collect(collection_path, config)

Skip tests if VCS binaries are missing.

Return type:

bool

Parameters:

• collection_path (Path)

• config (Config)

libvcs.pytest_plugin.home_path(tmp_path_factory)

Return temporary directory to use as user’s home path, pytest fixture.

Return type:

Path

Parameters:

tmp_path_factory (TempPathFactory)

libvcs.pytest_plugin.home_user_name()

Return default username to set for user_path() fixture.

Return type:

str

libvcs.pytest_plugin.user_path(home_path, home_user_name)

Return user’s home directory, pytest fixture.

Return type:

Path

Parameters:

• home_path (Path)

• home_user_name (str)

libvcs.pytest_plugin.set_home(monkeypatch, user_path)

Set home directory, pytest fixture.

Return type:

None

Parameters:

• monkeypatch (MonkeyPatch)

• user_path (Path)

libvcs.pytest_plugin.gitconfig(user_path, vcs_email, vcs_name)

Return git configuration, pytest fixture.

Return type:

Path

Parameters:

• user_path (Path)

• vcs_email (str)

• vcs_name (str)

libvcs.pytest_plugin.set_gitconfig(monkeypatch, gitconfig)

Set git configuration.

Return type:

Path

Parameters:

• monkeypatch (MonkeyPatch)

• gitconfig (Path)

libvcs.pytest_plugin.hgconfig(user_path, vcs_user)

Return Mercurial configuration.

Return type:

Path

Parameters:

• user_path (Path)

• vcs_user (str)

libvcs.pytest_plugin.set_hgconfig(monkeypatch, hgconfig)

Set Mercurial configuration.

Return type:

Path

Parameters:

• monkeypatch (MonkeyPatch)

• hgconfig (Path)

libvcs.pytest_plugin.projects_path(user_path, request)

User’s local checkouts and clones. Emphemeral directory.

Return type:

Path

Parameters:

• user_path (Path)

• request (FixtureRequest)

libvcs.pytest_plugin.remote_repos_path(user_path, request)

System’s remote (file-based) repos to clone and push to. Emphemeral directory.

Return type:

Path

Parameters:

• user_path (Path)

• request (FixtureRequest)

libvcs.pytest_plugin.unique_repo_name(remote_repos_path, max_retries=15)

Attempt to find and return a unique repo named based on path.

Return type:

str

Parameters:

• remote_repos_path (Path)

• max_retries (int)

class libvcs.pytest_plugin.CreateRepoPostInitFn(*args, **kwargs)

Bases: Protocol

Typing for VCS repo creation callback.

_abc_impl = <_abc._abc_data object>

_is_protocol = True

_is_runtime_protocol = False

class libvcs.pytest_plugin.CreateRepoPytestFixtureFn(*args, **kwargs)

Bases: Protocol

Typing for VCS pytest fixture callback.

_abc_impl = <_abc._abc_data object>

_is_protocol = True

_is_runtime_protocol = False

libvcs.pytest_plugin._create_git_remote_repo(remote_repo_path, remote_repo_post_init=None, init_cmd_args=['--bare'], env=None)

Return type:

Path

Parameters:

• remote_repo_path (Path)

• remote_repo_post_init (CreateRepoPostInitFn | None)

• init_cmd_args (list[str] | None)

• env (Mapping[bytes, str | bytes | PathLike[str] | PathLike[bytes]] | Mapping[str, str | bytes | PathLike[str] | PathLike[bytes]] | None)

libvcs.pytest_plugin.libvcs_test_cache_path(tmp_path_factory)

Return temporary directory to use as cache path for libvcs tests.

Return type:

Path

Parameters:

tmp_path_factory (TempPathFactory)

libvcs.pytest_plugin.empty_git_repo_path(libvcs_test_cache_path)

Return temporary directory to use for master-copy of a git repo.

Return type:

Path

Parameters:

libvcs_test_cache_path (Path)

libvcs.pytest_plugin.empty_git_bare_repo_path(libvcs_test_cache_path)

Return temporary directory to use for master-copy of a bare git repo.

Return type:

Path

Parameters:

libvcs_test_cache_path (Path)

libvcs.pytest_plugin.empty_git_bare_repo(empty_git_bare_repo_path)

Return factory to create git remote repo to for clone / push purposes.

Return type:

Path

Parameters:

empty_git_bare_repo_path (Path)

libvcs.pytest_plugin.empty_git_repo(empty_git_repo_path)

Return factory to create git remote repo to for clone / push purposes.

Return type:

Path

Parameters:

empty_git_repo_path (Path)

libvcs.pytest_plugin.create_git_remote_bare_repo(remote_repos_path, empty_git_bare_repo)

Return factory to create git remote repo to for clone / push purposes.

Return type:

CreateRepoPytestFixtureFn

Parameters:

• remote_repos_path (Path)

• empty_git_bare_repo (Path)

libvcs.pytest_plugin.create_git_remote_repo(remote_repos_path, empty_git_repo)

Return factory to create git remote repo to for clone / push purposes.

Return type:

CreateRepoPytestFixtureFn

Parameters:

• remote_repos_path (Path)

• empty_git_repo (Path)

libvcs.pytest_plugin.git_remote_repo_single_commit_post_init(remote_repo_path, env=None)

Post-initialization: Create a test git repo with a single commit.

Return type:

None

Parameters:

• remote_repo_path (Path)

• env (Mapping[bytes, str | bytes | PathLike[str] | PathLike[bytes]] | Mapping[str, str | bytes | PathLike[str] | PathLike[bytes]] | None)

libvcs.pytest_plugin.git_remote_repo(create_git_remote_repo, gitconfig, git_commit_envvars)

Copy the session-scoped Git repository to a temporary directory.

Return type:

Path

Parameters:

• create_git_remote_repo (CreateRepoPytestFixtureFn)

• gitconfig (Path)

• git_commit_envvars (Mapping[bytes, str | bytes | PathLike[str] | PathLike[bytes]] | Mapping[str, str | bytes | PathLike[str] | PathLike[bytes]])

libvcs.pytest_plugin._create_svn_remote_repo(remote_repo_path, remote_repo_post_init=None, init_cmd_args=None)

Create a test SVN repo to for checkout / commit purposes.

Return type:

Path

Parameters:

• remote_repo_path (Path)

• remote_repo_post_init (CreateRepoPostInitFn | None)

• init_cmd_args (list[str] | None)

libvcs.pytest_plugin.svn_remote_repo_single_commit_post_init(remote_repo_path)

Post-initialization: Create a test SVN repo with a single commit.

Return type:

None

Parameters:

remote_repo_path (Path)

libvcs.pytest_plugin.empty_svn_repo_path(libvcs_test_cache_path)

Return temporary directory to use for master-copy of a svn repo.

Return type:

Path

Parameters:

libvcs_test_cache_path (Path)

libvcs.pytest_plugin.empty_svn_repo(empty_svn_repo_path)

Return factory to create svn remote repo to for clone / push purposes.

Return type:

Path

Parameters:

empty_svn_repo_path (Path)

libvcs.pytest_plugin.create_svn_remote_repo(remote_repos_path, empty_svn_repo)

Pre-made svn repo, bare, used as a file:// remote to checkout and commit to.

Return type:

CreateRepoPytestFixtureFn

Parameters:

• remote_repos_path (Path)

• empty_svn_repo (Path)

libvcs.pytest_plugin.svn_remote_repo(create_svn_remote_repo)

Pre-made. Local file:// based SVN server.

Return type:

Path

Parameters:

create_svn_remote_repo (CreateRepoPytestFixtureFn)

libvcs.pytest_plugin.svn_remote_repo_with_files(create_svn_remote_repo)

Pre-made. Local file:// based SVN server.

Return type:

Path

Parameters:

create_svn_remote_repo (CreateRepoPytestFixtureFn)

libvcs.pytest_plugin._create_hg_remote_repo(remote_repo_path, remote_repo_post_init=None, init_cmd_args=None)

Create a test hg repo to for checkout / commit purposes.

Return type:

Path

Parameters:

• remote_repo_path (Path)

• remote_repo_post_init (CreateRepoPostInitFn | None)

• init_cmd_args (list[str] | None)

libvcs.pytest_plugin.hg_remote_repo_single_commit_post_init(remote_repo_path, env=None)

Post-initialization: Create a test mercurial repo with a single commit.

Return type:

None

Parameters:

• remote_repo_path (Path)

• env (Mapping[bytes, str | bytes | PathLike[str] | PathLike[bytes]] | Mapping[str, str | bytes | PathLike[str] | PathLike[bytes]] | None)

libvcs.pytest_plugin.empty_hg_repo_path(libvcs_test_cache_path)

Return temporary directory to use for master-copy of a hg repo.

Return type:

Path

Parameters:

libvcs_test_cache_path (Path)

libvcs.pytest_plugin.empty_hg_repo(empty_hg_repo_path)

Return factory to create hg remote repo to for clone / push purposes.

Return type:

Path

Parameters:

empty_hg_repo_path (Path)

libvcs.pytest_plugin.create_hg_remote_repo(remote_repos_path, empty_hg_repo, hgconfig)

Pre-made hg repo, bare, used as a file:// remote to checkout and commit to.

Return type:

CreateRepoPytestFixtureFn

Parameters:

• remote_repos_path (Path)

• empty_hg_repo (Path)

• hgconfig (Path)

libvcs.pytest_plugin.hg_remote_repo(remote_repos_path, create_hg_remote_repo, hgconfig)

Pre-made, file-based repo for push and pull.

Return type:

Path

Parameters:

• remote_repos_path (Path)

• create_hg_remote_repo (CreateRepoPytestFixtureFn)

• hgconfig (Path)

libvcs.pytest_plugin.git_repo(remote_repos_path, projects_path, git_remote_repo, set_gitconfig)

Pre-made git clone of remote repo checked out to user’s projects dir.

Return type:

GitSync

Parameters:

• remote_repos_path (Path)

• projects_path (Path)

• git_remote_repo (Path)

• set_gitconfig (Path)

libvcs.pytest_plugin.hg_repo(remote_repos_path, projects_path, hg_remote_repo, set_hgconfig)

Pre-made hg clone of remote repo checked out to user’s projects dir.

Return type:

HgSync

Parameters:

• remote_repos_path (Path)

• projects_path (Path)

• hg_remote_repo (Path)

• set_hgconfig (Path)

libvcs.pytest_plugin.svn_repo(remote_repos_path, projects_path, svn_remote_repo)

Pre-made svn clone of remote repo checked out to user’s projects dir.

Return type:

SvnSync

Parameters:

• remote_repos_path (Path)

• projects_path (Path)

• svn_remote_repo (Path)

libvcs.pytest_plugin.add_doctest_fixtures(request, doctest_namespace, tmp_path, set_home, git_commit_envvars, hgconfig, create_git_remote_repo, create_svn_remote_repo, create_hg_remote_repo, git_repo)

Harness pytest fixtures to pytest’s doctest namespace.

Return type:

None

Parameters:

• request (FixtureRequest)

• doctest_namespace (dict[str, Any])

• tmp_path (Path)

• set_home (Path)

• git_commit_envvars (Mapping[bytes, str | bytes | PathLike[str] | PathLike[bytes]] | Mapping[str, str | bytes | PathLike[str] | PathLike[bytes]])

• hgconfig (Path)

• create_git_remote_repo (CreateRepoPytestFixtureFn)

• create_svn_remote_repo (CreateRepoPytestFixtureFn)

• create_hg_remote_repo (CreateRepoPytestFixtureFn)

• git_repo (Path)