tox-ignore-env-name-mismatch

Reuse virtualenvs with multiple tox test environments.

If two environments have compatible specifications (basically, same deps) and use the same env_dir, installing this plugin and setting runner = ignore_env_name_mismatch will allow tox to use the same underlying virtualenv for each test environment.

Development status: EXPRIMENTAL - The API is evolving and things are breaking. Please vendor the plugin as described below, or you will get broken.

Usage

1. Install tox-ignore-env-name-mismatch in the same environment as tox.
2. Set runner = ignore_env_name_mismatch in a testenv to opt-out of recreating the virtualenv when the env name changes.

To always use this plugin:

Vendor

• copy src/tox_ignore_env_name_mismatch.py to the root of your project directory as toxfile.py

This uses the tox4's new "inline plugin" approach instead of relying on the provisioning system (which can be disabled via CLI).

Install/provision

[tox]
min_version = 4.3.3
requires =
    tox-ignore-env-name-mismatch ~= 0.2.0

This will cause tox to provision a new virtualenv for tox itself and other dependencies named in the requires key if the current environment does not meet the specification.

Pinning the plugin to a minor version is highly recommended to avoid breaking changes.

NOTE: tox < 4.3.3 had a bug which prevented this type of installation.

Example

[tox]
envlist = py39,py310,py311,lint,format,types
min_version = 4.3.3
requires =
    tox-ignore-env-name-mismatch ~= 0.2.0

[testenv]
deps = pytest
commands = pytest {posargs}

[testenv:{lint,format,types}]
env_dir = {toxworkdir}{/}static
runner = ignore_env_name_mismatch
deps =
    black
    flake8
    mypy
commands =
    lint: flake8 src tests
    format: black --check src tests
    types: mypy --strict src

see ./examples directory for a working example including the tox configuration above.

Why??

Typically this usage pattern is seen with "auxillary" environments that perform project operations, like linting, generating docs, or publishing packages. Using different testenv sections is a nice way to separate commands and passenv / setenv, but creating separate virtualenv that would otherwise use identical dependencies is both a waste of time and space.

In tox 3, it was possible to achieve this behavior (with a bug and some caveats) by simply having testenvs share an env_dir. In tox 4, this hackaround was properly fixed and now tox checks a cached {envdir}/.tox-info.json and recreates the virtualenv if the current testenv doesn't match what is cached.

This plugin allows a test environment to specifically opt-out of recreating the virtualenv when only the env_name differs.

This plugin only supports tox 4.

Motivation

People have been asking for this for at least 7 years and the core tox project is specifically not interested in supporting this use case in tox 4 (which is fine, that's what plugins are for).

• [tox-dev/tox#2788] Re-use of virtual environments across envs in tox4 [2022, Github]
• Reuse environment on Tox 4 [2022, StackOverflow]
• tox multiple tests, re-using tox environment [2019, StackOverflow]
• [tox-dev/tox#425] Ability to share tox environments within a project [2016, Github]
• Tox tricks and patterns#Environment reuse [2015, Blog]

Changelog

v0.2 - 2023-01-15

[BREAKING] #3 Rewrite plugin to use Public API

To upgrade to v0.2, change ignore_env_name_mismatch = true to runner = ignore_env_name_mismatch.

v0.1 - 2023-01-14

Initial Release