pytest plugin

Create git, svn, and hg repos on the fly in pytest.

See also

Using libvcs?

Do you want more flexbility? Correctness? Power? Defaults changed? Connect with us on the tracker, we want to know your case, we won’t stabilize APIs until we’re sure everything is by the book.

Usage

Install libvcs via the python package manager of your choosing, e.g.

$ pip install libvcs

The pytest plugin will automatically be detected via pytest, and the fixtures will be added.

Fixtures

pytest-vcs works through providing pytest fixtures - so read up on those!

The plugin’s fixtures guarantee a fresh git repository every test.

Recommended fixtures

These are fixtures are automatically used when the plugin is enabled and pytest is ran.

• Creating temporary, test directories for:

  • /home/ (home_path())

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

• Setting your home directory

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

• Set default configuration

  • .gitconfig, via gitconfig():

  • .hgrc, via hgconfig():

  These are set to ensure you can correctly clone and create repositories without. without extra warnings.

Bootstrapping pytest in your conftest.py

The most common scenario is you will want to configure the above fixtures with autouse.

Why doesn’t the plugin automatically add them? It’s part of being a decent pytest plugin and python package: explicitness.

Setting a temporary home directory

import pytest

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

See examples

View 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()

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

args

with_traceback()

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

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, set_home)

Return git configuration, pytest fixture.

Return type:

Path

Parameters:

• user_path (Path) –

• set_home (Path) –

libvcs.pytest_plugin.hgconfig(user_path, set_home)

Return Mercurial configuration, pytest fixture.

Return type:

Path

Parameters:

• user_path (Path) –

• set_home (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 andpush 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_repos_path, remote_repo_name, remote_repo_post_init=None, init_cmd_args=['--bare'])

Return type:

Path

Parameters:

• remote_repos_path (Path) –

• remote_repo_name (str) –

• remote_repo_post_init (CreateRepoPostInitFn | None) –

• init_cmd_args (list[str] | None) –

libvcs.pytest_plugin.create_git_remote_repo(remote_repos_path)

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

Return type:

CreateRepoPytestFixtureFn

Parameters:

remote_repos_path (Path) –

libvcs.pytest_plugin.git_remote_repo_single_commit_post_init(remote_repo_path)

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

Return type:

None

Parameters:

remote_repo_path (Path) –

libvcs.pytest_plugin.git_remote_repo(remote_repos_path)

Pre-made git repo w/ 1 commit, used as a file:// remote to clone and push to.

Return type:

Path

Parameters:

remote_repos_path (Path) –

libvcs.pytest_plugin._create_svn_remote_repo(remote_repos_path, remote_repo_name, remote_repo_post_init=None, init_cmd_args=None)

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

Return type:

Path

Parameters:

• remote_repos_path (Path) –

• remote_repo_name (str) –

• 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.create_svn_remote_repo(remote_repos_path)

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

Return type:

CreateRepoPytestFixtureFn

Parameters:

remote_repos_path (Path) –

libvcs.pytest_plugin.svn_remote_repo(remote_repos_path)

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

Return type:

Path

Parameters:

remote_repos_path (Path) –

libvcs.pytest_plugin._create_hg_remote_repo(remote_repos_path, remote_repo_name, remote_repo_post_init=None, init_cmd_args=None)

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

Return type:

Path

Parameters:

• remote_repos_path (Path) –

• remote_repo_name (str) –

• 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)

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

Return type:

None

Parameters:

remote_repo_path (Path) –

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

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

Return type:

CreateRepoPytestFixtureFn

Parameters:

• remote_repos_path (Path) –

• hgconfig (Path) –

• set_home (Path) –

libvcs.pytest_plugin.hg_remote_repo(remote_repos_path, hgconfig)

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

Return type:

Path

Parameters:

• remote_repos_path (Path) –

• hgconfig (Path) –

libvcs.pytest_plugin.git_repo(projects_path, git_remote_repo)

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

Return type:

GitSync

Parameters:

• projects_path (Path) –

• git_remote_repo (Path) –

libvcs.pytest_plugin.hg_repo(projects_path, hg_remote_repo)

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

Return type:

HgSync

Parameters:

• projects_path (Path) –

• hg_remote_repo (Path) –

libvcs.pytest_plugin.svn_repo(projects_path, svn_remote_repo)

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

Return type:

SvnSync

Parameters:

• projects_path (Path) –

• svn_remote_repo (Path) –

libvcs.pytest_plugin.add_doctest_fixtures(request, doctest_namespace, tmp_path, set_home, gitconfig, 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) –

• gitconfig (Path) –

• create_git_remote_repo (CreateRepoPytestFixtureFn) –

• create_svn_remote_repo (CreateRepoPytestFixtureFn) –

• create_hg_remote_repo (CreateRepoPytestFixtureFn) –

• git_repo (Path) –