add additional info to healthy-after-install check

CONTRIBUTING.md

@@ -117,15 +117,16 @@ get_default_version = helpers.basic_default_version
 
 `python` is currently the only language which implements this api
 
-#### `healthy`
+#### `health_check`
 
 This is used to check whether the installed environment is considered healthy.
-This function should return `True` or `False`.
+This function should return a detailed message if unhealthy or `None` if
+healthy.
 
 You generally don't need to implement this on a first pass and can just use:
 
 ```python
-healthy = helpers.basic_healthy
+health_check = helpers.basic_healthy_check
 ```
 
 `python` is currently the only language which implements this api, for python

pre_commit/languages/all.py

@@ -34,7 +34,7 @@ class Language(NamedTuple):
     # return a value to replace `'default` for `language_version`
     get_default_version: Callable[[], str]
     # return whether the environment is healthy (or should be rebuilt)
-    healthy: Callable[[Prefix, str], bool]
+    health_check: Callable[[Prefix, str], str | None]
     # install a repository for the given language and language_version
     install_environment: Callable[[Prefix, str, Sequence[str]], None]
     # execute a hook and return the exit code and output
@@ -44,25 +44,25 @@ class Language(NamedTuple):
 # TODO: back to modules + Protocol: https://github.com/python/mypy/issues/5018
 languages = {
     # BEGIN GENERATED (testing/gen-languages-all)
-    'conda': Language(name='conda', ENVIRONMENT_DIR=conda.ENVIRONMENT_DIR, get_default_version=conda.get_default_version, healthy=conda.healthy, install_environment=conda.install_environment, run_hook=conda.run_hook),  # noqa: E501
+    'conda': Language(name='conda', ENVIRONMENT_DIR=conda.ENVIRONMENT_DIR, get_default_version=conda.get_default_version, health_check=conda.health_check, install_environment=conda.install_environment, run_hook=conda.run_hook),  # noqa: E501
-    'coursier': Language(name='coursier', ENVIRONMENT_DIR=coursier.ENVIRONMENT_DIR, get_default_version=coursier.get_default_version, healthy=coursier.healthy, install_environment=coursier.install_environment, run_hook=coursier.run_hook),  # noqa: E501
+    'coursier': Language(name='coursier', ENVIRONMENT_DIR=coursier.ENVIRONMENT_DIR, get_default_version=coursier.get_default_version, health_check=coursier.health_check, install_environment=coursier.install_environment, run_hook=coursier.run_hook),  # noqa: E501
-    'dart': Language(name='dart', ENVIRONMENT_DIR=dart.ENVIRONMENT_DIR, get_default_version=dart.get_default_version, healthy=dart.healthy, install_environment=dart.install_environment, run_hook=dart.run_hook),  # noqa: E501
+    'dart': Language(name='dart', ENVIRONMENT_DIR=dart.ENVIRONMENT_DIR, get_default_version=dart.get_default_version, health_check=dart.health_check, install_environment=dart.install_environment, run_hook=dart.run_hook),  # noqa: E501
-    'docker': Language(name='docker', ENVIRONMENT_DIR=docker.ENVIRONMENT_DIR, get_default_version=docker.get_default_version, healthy=docker.healthy, install_environment=docker.install_environment, run_hook=docker.run_hook),  # noqa: E501
+    'docker': Language(name='docker', ENVIRONMENT_DIR=docker.ENVIRONMENT_DIR, get_default_version=docker.get_default_version, health_check=docker.health_check, install_environment=docker.install_environment, run_hook=docker.run_hook),  # noqa: E501
-    'docker_image': Language(name='docker_image', ENVIRONMENT_DIR=docker_image.ENVIRONMENT_DIR, get_default_version=docker_image.get_default_version, healthy=docker_image.healthy, install_environment=docker_image.install_environment, run_hook=docker_image.run_hook),  # noqa: E501
+    'docker_image': Language(name='docker_image', ENVIRONMENT_DIR=docker_image.ENVIRONMENT_DIR, get_default_version=docker_image.get_default_version, health_check=docker_image.health_check, install_environment=docker_image.install_environment, run_hook=docker_image.run_hook),  # noqa: E501
-    'dotnet': Language(name='dotnet', ENVIRONMENT_DIR=dotnet.ENVIRONMENT_DIR, get_default_version=dotnet.get_default_version, healthy=dotnet.healthy, install_environment=dotnet.install_environment, run_hook=dotnet.run_hook),  # noqa: E501
+    'dotnet': Language(name='dotnet', ENVIRONMENT_DIR=dotnet.ENVIRONMENT_DIR, get_default_version=dotnet.get_default_version, health_check=dotnet.health_check, install_environment=dotnet.install_environment, run_hook=dotnet.run_hook),  # noqa: E501
-    'fail': Language(name='fail', ENVIRONMENT_DIR=fail.ENVIRONMENT_DIR, get_default_version=fail.get_default_version, healthy=fail.healthy, install_environment=fail.install_environment, run_hook=fail.run_hook),  # noqa: E501
+    'fail': Language(name='fail', ENVIRONMENT_DIR=fail.ENVIRONMENT_DIR, get_default_version=fail.get_default_version, health_check=fail.health_check, install_environment=fail.install_environment, run_hook=fail.run_hook),  # noqa: E501
-    'golang': Language(name='golang', ENVIRONMENT_DIR=golang.ENVIRONMENT_DIR, get_default_version=golang.get_default_version, healthy=golang.healthy, install_environment=golang.install_environment, run_hook=golang.run_hook),  # noqa: E501
+    'golang': Language(name='golang', ENVIRONMENT_DIR=golang.ENVIRONMENT_DIR, get_default_version=golang.get_default_version, health_check=golang.health_check, install_environment=golang.install_environment, run_hook=golang.run_hook),  # noqa: E501
-    'lua': Language(name='lua', ENVIRONMENT_DIR=lua.ENVIRONMENT_DIR, get_default_version=lua.get_default_version, healthy=lua.healthy, install_environment=lua.install_environment, run_hook=lua.run_hook),  # noqa: E501
+    'lua': Language(name='lua', ENVIRONMENT_DIR=lua.ENVIRONMENT_DIR, get_default_version=lua.get_default_version, health_check=lua.health_check, install_environment=lua.install_environment, run_hook=lua.run_hook),  # noqa: E501
-    'node': Language(name='node', ENVIRONMENT_DIR=node.ENVIRONMENT_DIR, get_default_version=node.get_default_version, healthy=node.healthy, install_environment=node.install_environment, run_hook=node.run_hook),  # noqa: E501
+    'node': Language(name='node', ENVIRONMENT_DIR=node.ENVIRONMENT_DIR, get_default_version=node.get_default_version, health_check=node.health_check, install_environment=node.install_environment, run_hook=node.run_hook),  # noqa: E501
-    'perl': Language(name='perl', ENVIRONMENT_DIR=perl.ENVIRONMENT_DIR, get_default_version=perl.get_default_version, healthy=perl.healthy, install_environment=perl.install_environment, run_hook=perl.run_hook),  # noqa: E501
+    'perl': Language(name='perl', ENVIRONMENT_DIR=perl.ENVIRONMENT_DIR, get_default_version=perl.get_default_version, health_check=perl.health_check, install_environment=perl.install_environment, run_hook=perl.run_hook),  # noqa: E501
-    'pygrep': Language(name='pygrep', ENVIRONMENT_DIR=pygrep.ENVIRONMENT_DIR, get_default_version=pygrep.get_default_version, healthy=pygrep.healthy, install_environment=pygrep.install_environment, run_hook=pygrep.run_hook),  # noqa: E501
+    'pygrep': Language(name='pygrep', ENVIRONMENT_DIR=pygrep.ENVIRONMENT_DIR, get_default_version=pygrep.get_default_version, health_check=pygrep.health_check, install_environment=pygrep.install_environment, run_hook=pygrep.run_hook),  # noqa: E501
-    'python': Language(name='python', ENVIRONMENT_DIR=python.ENVIRONMENT_DIR, get_default_version=python.get_default_version, healthy=python.healthy, install_environment=python.install_environment, run_hook=python.run_hook),  # noqa: E501
+    'python': Language(name='python', ENVIRONMENT_DIR=python.ENVIRONMENT_DIR, get_default_version=python.get_default_version, health_check=python.health_check, install_environment=python.install_environment, run_hook=python.run_hook),  # noqa: E501
-    'r': Language(name='r', ENVIRONMENT_DIR=r.ENVIRONMENT_DIR, get_default_version=r.get_default_version, healthy=r.healthy, install_environment=r.install_environment, run_hook=r.run_hook),  # noqa: E501
+    'r': Language(name='r', ENVIRONMENT_DIR=r.ENVIRONMENT_DIR, get_default_version=r.get_default_version, health_check=r.health_check, install_environment=r.install_environment, run_hook=r.run_hook),  # noqa: E501
-    'ruby': Language(name='ruby', ENVIRONMENT_DIR=ruby.ENVIRONMENT_DIR, get_default_version=ruby.get_default_version, healthy=ruby.healthy, install_environment=ruby.install_environment, run_hook=ruby.run_hook),  # noqa: E501
+    'ruby': Language(name='ruby', ENVIRONMENT_DIR=ruby.ENVIRONMENT_DIR, get_default_version=ruby.get_default_version, health_check=ruby.health_check, install_environment=ruby.install_environment, run_hook=ruby.run_hook),  # noqa: E501
-    'rust': Language(name='rust', ENVIRONMENT_DIR=rust.ENVIRONMENT_DIR, get_default_version=rust.get_default_version, healthy=rust.healthy, install_environment=rust.install_environment, run_hook=rust.run_hook),  # noqa: E501
+    'rust': Language(name='rust', ENVIRONMENT_DIR=rust.ENVIRONMENT_DIR, get_default_version=rust.get_default_version, health_check=rust.health_check, install_environment=rust.install_environment, run_hook=rust.run_hook),  # noqa: E501
-    'script': Language(name='script', ENVIRONMENT_DIR=script.ENVIRONMENT_DIR, get_default_version=script.get_default_version, healthy=script.healthy, install_environment=script.install_environment, run_hook=script.run_hook),  # noqa: E501
+    'script': Language(name='script', ENVIRONMENT_DIR=script.ENVIRONMENT_DIR, get_default_version=script.get_default_version, health_check=script.health_check, install_environment=script.install_environment, run_hook=script.run_hook),  # noqa: E501
-    'swift': Language(name='swift', ENVIRONMENT_DIR=swift.ENVIRONMENT_DIR, get_default_version=swift.get_default_version, healthy=swift.healthy, install_environment=swift.install_environment, run_hook=swift.run_hook),  # noqa: E501
+    'swift': Language(name='swift', ENVIRONMENT_DIR=swift.ENVIRONMENT_DIR, get_default_version=swift.get_default_version, health_check=swift.health_check, install_environment=swift.install_environment, run_hook=swift.run_hook),  # noqa: E501
-    'system': Language(name='system', ENVIRONMENT_DIR=system.ENVIRONMENT_DIR, get_default_version=system.get_default_version, healthy=system.healthy, install_environment=system.install_environment, run_hook=system.run_hook),  # noqa: E501
+    'system': Language(name='system', ENVIRONMENT_DIR=system.ENVIRONMENT_DIR, get_default_version=system.get_default_version, health_check=system.health_check, install_environment=system.install_environment, run_hook=system.run_hook),  # noqa: E501
     # END GENERATED
 }
 # TODO: fully deprecate `python_venv`

pre_commit/languages/conda.py

@@ -18,7 +18,7 @@ from pre_commit.util import cmd_output_b
 
 ENVIRONMENT_DIR = 'conda'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def get_env_patch(env: str) -> PatchesT:

pre_commit/languages/coursier.py

@@ -17,7 +17,7 @@ from pre_commit.util import clean_path_on_failure
 ENVIRONMENT_DIR = 'coursier'
 
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def install_environment(

pre_commit/languages/dart.py

@@ -21,7 +21,7 @@ from pre_commit.util import yaml_load
 ENVIRONMENT_DIR = 'dartenv'
 
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def get_env_patch(venv: str) -> PatchesT:

pre_commit/languages/docker.py

@@ -16,7 +16,7 @@ from pre_commit.util import cmd_output_b
 ENVIRONMENT_DIR = 'docker'
 PRE_COMMIT_LABEL = 'PRE_COMMIT'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def _is_in_docker() -> bool:

pre_commit/languages/docker_image.py

@@ -8,7 +8,7 @@ from pre_commit.languages.docker import docker_cmd
 
 ENVIRONMENT_DIR = None
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 install_environment = helpers.no_install
 
 

pre_commit/languages/dotnet.py

@@ -18,7 +18,7 @@ ENVIRONMENT_DIR = 'dotnetenv'
 BIN_DIR = 'bin'
 
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def get_env_patch(venv: str) -> PatchesT:

pre_commit/languages/fail.py

@@ -7,7 +7,7 @@ from pre_commit.languages import helpers
 
 ENVIRONMENT_DIR = None
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 install_environment = helpers.no_install
 
 

pre_commit/languages/golang.py

@@ -21,7 +21,7 @@ from pre_commit.util import rmtree
 
 ENVIRONMENT_DIR = 'golangenv'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def get_env_patch(venv: str) -> PatchesT:

pre_commit/languages/helpers.py

@@ -88,8 +88,8 @@ def basic_get_default_version() -> str:
     return C.DEFAULT
 
 
-def basic_healthy(prefix: Prefix, language_version: str) -> bool:
+def basic_health_check(prefix: Prefix, language_version: str) -> str | None:
-    return True
+    return None
 
 
 def no_install(

pre_commit/languages/lua.py

@@ -18,7 +18,7 @@ from pre_commit.util import cmd_output
 
 ENVIRONMENT_DIR = 'lua_env'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def _get_lua_version() -> str:  # pragma: win32 no cover

pre_commit/languages/node.py

@@ -73,10 +73,13 @@ def in_env(
         yield
 
 
-def healthy(prefix: Prefix, language_version: str) -> bool:
+def health_check(prefix: Prefix, language_version: str) -> str | None:
     with in_env(prefix, language_version):
         retcode, _, _ = cmd_output_b('node', '--version', retcode=None)
-        return retcode == 0
+        if retcode != 0:  # pragma: win32 no cover
+            return f'`node --version` returned {retcode}'
+        else:
+            return None
 
 
 def install_environment(

pre_commit/languages/perl.py

@@ -16,7 +16,7 @@ from pre_commit.util import clean_path_on_failure
 
 ENVIRONMENT_DIR = 'perl_env'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def _envdir(prefix: Prefix, version: str) -> str:

pre_commit/languages/pygrep.py

@@ -14,7 +14,7 @@ from pre_commit.xargs import xargs
 
 ENVIRONMENT_DIR = None
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 install_environment = helpers.no_install
 
 

pre_commit/languages/python.py

@@ -163,27 +163,44 @@ def in_env(
         yield
 
 
-def healthy(prefix: Prefix, language_version: str) -> bool:
+def health_check(prefix: Prefix, language_version: str) -> str | None:
     directory = helpers.environment_dir(ENVIRONMENT_DIR, language_version)
     envdir = prefix.path(directory)
     pyvenv_cfg = os.path.join(envdir, 'pyvenv.cfg')
 
     # created with "old" virtualenv
     if not os.path.exists(pyvenv_cfg):
-        return False
+        return 'pyvenv.cfg does not exist (old virtualenv?)'
 
     exe_name = win_exe('python')
     py_exe = prefix.path(bin_dir(envdir), exe_name)
     cfg = _read_pyvenv_cfg(pyvenv_cfg)
 
-    return (
+    if 'version_info' not in cfg:
-        'version_info' in cfg and
+        return "created virtualenv's pyvenv.cfg is missing `version_info`"
-        # always use uncached lookup here in case we replaced an unhealthy env
+
-        _version_info.__wrapped__(py_exe) == cfg['version_info'] and (
+    # always use uncached lookup here in case we replaced an unhealthy env
-            'base-executable' not in cfg or
+    virtualenv_version = _version_info.__wrapped__(py_exe)
-            _version_info(cfg['base-executable']) == cfg['version_info']
+    if virtualenv_version != cfg['version_info']:
+        return (
+            f'virtualenv python version did not match created version:\n'
+            f'- actual version: {virtualenv_version}\n'
+            f'- expected version: {cfg["version_info"]}\n'
         )
-    )
+
+    # made with an older version of virtualenv? skip `base-executable` check
+    if 'base-executable' not in cfg:
+        return None
+
+    base_exe_version = _version_info(cfg['base-executable'])
+    if base_exe_version != cfg['version_info']:
+        return (
+            f'base executable python version does not match created version:\n'
+            f'- base-executable version: {base_exe_version}\n'
+            f'- expected version: {cfg["version_info"]}\n'
+        )
+    else:
+        return None
 
 
 def install_environment(

pre_commit/languages/r.py

@@ -19,7 +19,7 @@ from pre_commit.util import cmd_output_b
 ENVIRONMENT_DIR = 'renv'
 RSCRIPT_OPTS = ('--no-save', '--no-restore', '--no-site-file', '--no-environ')
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def get_env_patch(venv: str) -> PatchesT:

pre_commit/languages/ruby.py

@@ -21,7 +21,7 @@ from pre_commit.util import clean_path_on_failure
 from pre_commit.util import resource_bytesio
 
 ENVIRONMENT_DIR = 'rbenv'
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 @functools.lru_cache(maxsize=1)

pre_commit/languages/rust.py

@@ -19,7 +19,7 @@ from pre_commit.util import cmd_output_b
 
 ENVIRONMENT_DIR = 'rustenv'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 
 
 def get_env_patch(target_dir: str) -> PatchesT:

pre_commit/languages/script.py

@@ -7,7 +7,7 @@ from pre_commit.languages import helpers
 
 ENVIRONMENT_DIR = None
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 install_environment = helpers.no_install
 
 

pre_commit/languages/swift.py

@@ -17,7 +17,7 @@ from pre_commit.util import cmd_output_b
 
 ENVIRONMENT_DIR = 'swift_env'
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 BUILD_DIR = '.build'
 BUILD_CONFIG = 'release'
 

pre_commit/languages/system.py

@@ -8,7 +8,7 @@ from pre_commit.languages import helpers
 
 ENVIRONMENT_DIR = None
 get_default_version = helpers.basic_get_default_version
-healthy = helpers.basic_healthy
+health_check = helpers.basic_health_check
 install_environment = helpers.no_install
 
 

pre_commit/repository.py

@@ -57,7 +57,7 @@ def _hook_installed(hook: Hook) -> bool:
                 _read_state(hook.prefix, venv) ==
                 _state(hook.additional_dependencies)
             ) and
-            lang.healthy(hook.prefix, hook.language_version)
+            not lang.health_check(hook.prefix, hook.language_version)
         )
     )
 
@@ -79,11 +79,13 @@ def _hook_install(hook: Hook) -> None:
     lang.install_environment(
         hook.prefix, hook.language_version, hook.additional_dependencies,
     )
-    if not lang.healthy(hook.prefix, hook.language_version):
+    health_error = lang.health_check(hook.prefix, hook.language_version)
+    if health_error:
         raise AssertionError(
-            f'BUG: expected environment for {hook.language} to be healthy() '
+            f'BUG: expected environment for {hook.language} to be healthy '
             f'immediately after install, please open an issue describing '
-            f'your environment',
+            f'your environment\n\n'
+            f'more info:\n\n{health_error}',
         )
     # Write our state to indicate we're installed
     _write_state(hook.prefix, venv, _state(hook.additional_dependencies))

testing/gen-languages-all

@@ -3,15 +3,15 @@ from __future__ import annotations
 
 import sys
 
-LANGUAGES = [
+LANGUAGES = (
     'conda', 'coursier', 'dart', 'docker', 'docker_image', 'dotnet', 'fail',
     'golang', 'lua', 'node', 'perl', 'pygrep', 'python', 'r', 'ruby', 'rust',
     'script', 'swift', 'system',
-]
+)
-FIELDS = [
+FIELDS = (
-    'ENVIRONMENT_DIR', 'get_default_version', 'healthy', 'install_environment',
+    'ENVIRONMENT_DIR', 'get_default_version', 'health_check',
-    'run_hook',
+    'install_environment', 'run_hook',
-]
+)
 
 
 def main() -> int:

tests/languages/helpers_test.py

@@ -67,8 +67,8 @@ def test_basic_get_default_version():
     assert helpers.basic_get_default_version() == C.DEFAULT
 
 
-def test_basic_healthy():
+def test_basic_health_check():
-    assert helpers.basic_healthy(Prefix('.'), 'default') is True
+    assert helpers.basic_health_check(Prefix('.'), 'default') is None
 
 
 def test_failed_setup_command_does_not_unicode_error():

tests/languages/node_test.py

@@ -62,7 +62,7 @@ def test_healthy_system_node(tmpdir):
 
     prefix = Prefix(str(tmpdir))
     node.install_environment(prefix, 'system', ())
-    assert node.healthy(prefix, 'system')
+    assert node.health_check(prefix, 'system') is None
 
 
 @xfailif_windows  # pragma: win32 no cover
@@ -78,10 +78,11 @@ def test_unhealthy_if_system_node_goes_missing(tmpdir):
     with envcontext.envcontext((path,)):
         prefix = Prefix(str(prefix_dir))
         node.install_environment(prefix, 'system', ())
-        assert node.healthy(prefix, 'system')
+        assert node.health_check(prefix, 'system') is None
 
         node_bin.remove()
-        assert not node.healthy(prefix, 'system')
+        ret = node.health_check(prefix, 'system')
+        assert ret == '`node --version` returned 127'
 
 
 @xfailif_windows  # pragma: win32 no cover
@@ -101,7 +102,7 @@ def test_installs_without_links_outside_env(tmpdir):
 
     prefix = Prefix(str(tmpdir))
     node.install_environment(prefix, 'system', ())
-    assert node.healthy(prefix, 'system')
+    assert node.health_check(prefix, 'system') is None
 
     # this directory shouldn't exist, make sure we succeed without it existing
     cmd_output('rm', '-rf', str(tmpdir.join('node_modules')))

tests/languages/python_test.py

@@ -93,11 +93,11 @@ def test_healthy_default_creator(python_dir):
     python.install_environment(prefix, C.DEFAULT, ())
 
     # should be healthy right after creation
-    assert python.healthy(prefix, C.DEFAULT) is True
+    assert python.health_check(prefix, C.DEFAULT) is None
 
     # even if a `types.py` file exists, should still be healthy
     tmpdir.join('types.py').ensure()
-    assert python.healthy(prefix, C.DEFAULT) is True
+    assert python.health_check(prefix, C.DEFAULT) is None
 
 
 def test_healthy_venv_creator(python_dir):
@@ -107,7 +107,7 @@ def test_healthy_venv_creator(python_dir):
     with envcontext((('VIRTUALENV_CREATOR', 'venv'),)):
         python.install_environment(prefix, C.DEFAULT, ())
 
-    assert python.healthy(prefix, C.DEFAULT) is True
+    assert python.health_check(prefix, C.DEFAULT) is None
 
 
 def test_unhealthy_python_goes_missing(python_dir):
@@ -119,7 +119,12 @@ def test_unhealthy_python_goes_missing(python_dir):
     py_exe = prefix.path(python.bin_dir('py_env-default'), exe_name)
     os.remove(py_exe)
 
-    assert python.healthy(prefix, C.DEFAULT) is False
+    ret = python.health_check(prefix, C.DEFAULT)
+    assert ret == (
+        f'virtualenv python version did not match created version:\n'
+        f'- actual version: <<error retrieving version from {py_exe}>>\n'
+        f'- expected version: {python._version_info(sys.executable)}\n'
+    )
 
 
 def test_unhealthy_with_version_change(python_dir):
@@ -127,10 +132,15 @@ def test_unhealthy_with_version_change(python_dir):
 
     python.install_environment(prefix, C.DEFAULT, ())
 
-    with open(prefix.path('py_env-default/pyvenv.cfg'), 'w') as f:
+    with open(prefix.path('py_env-default/pyvenv.cfg'), 'a+') as f:
         f.write('version_info = 1.2.3\n')
 
-    assert python.healthy(prefix, C.DEFAULT) is False
+    ret = python.health_check(prefix, C.DEFAULT)
+    assert ret == (
+        f'virtualenv python version did not match created version:\n'
+        f'- actual version: {python._version_info(sys.executable)}\n'
+        f'- expected version: 1.2.3\n'
+    )
 
 
 def test_unhealthy_system_version_changes(python_dir):
@@ -141,7 +151,12 @@ def test_unhealthy_system_version_changes(python_dir):
     with open(prefix.path('py_env-default/pyvenv.cfg'), 'a') as f:
         f.write('base-executable = /does/not/exist\n')
 
-    assert python.healthy(prefix, C.DEFAULT) is False
+    ret = python.health_check(prefix, C.DEFAULT)
+    assert ret == (
+        f'base executable python version does not match created version:\n'
+        f'- base-executable version: <<error retrieving version from /does/not/exist>>\n'  # noqa: E501
+        f'- expected version: {python._version_info(sys.executable)}\n'
+    )
 
 
 def test_unhealthy_old_virtualenv(python_dir):
@@ -152,7 +167,21 @@ def test_unhealthy_old_virtualenv(python_dir):
     # simulate "old" virtualenv by deleting this file
     os.remove(prefix.path('py_env-default/pyvenv.cfg'))
 
-    assert python.healthy(prefix, C.DEFAULT) is False
+    ret = python.health_check(prefix, C.DEFAULT)
+    assert ret == 'pyvenv.cfg does not exist (old virtualenv?)'
+
+
+def test_unhealthy_unexpected_pyvenv(python_dir):
+    prefix, tmpdir = python_dir
+
+    python.install_environment(prefix, C.DEFAULT, ())
+
+    # simulate a buggy environment build (I don't think this is possible)
+    with open(prefix.path('py_env-default/pyvenv.cfg'), 'w'):
+        pass
+
+    ret = python.health_check(prefix, C.DEFAULT)
+    assert ret == "created virtualenv's pyvenv.cfg is missing `version_info`"
 
 
 def test_unhealthy_then_replaced(python_dir):
@@ -170,9 +199,14 @@ def test_unhealthy_then_replaced(python_dir):
     make_executable(py_exe)
 
     # should be unhealthy due to version mismatch
-    assert python.healthy(prefix, C.DEFAULT) is False
+    ret = python.health_check(prefix, C.DEFAULT)
+    assert ret == (
+        f'virtualenv python version did not match created version:\n'
+        f'- actual version: 1.2.3\n'
+        f'- expected version: {python._version_info(sys.executable)}\n'
+    )
 
     # now put the exe back and it should be healthy again
     os.replace(f'{py_exe}.tmp', py_exe)
 
-    assert python.healthy(prefix, C.DEFAULT) is True
+    assert python.health_check(prefix, C.DEFAULT) is None