hints on the potential signal raised + better tests

doc/example/general.rst

@@ -228,8 +228,11 @@ This is why for exit codes larger than 128, an additional hint is given:
 
     ERROR: InvocationError for command
            '<command defined in tox.ini>' (exited with code 139)
-    Note: On unix systems, an exit code larger than 128 often means a fatal error (e.g. 139=128+11: segmentation fault)
+    Note: On unix systems, an exit code larger than 128 often
+          means a fatal error signal (e.g. 139=128+11: SIGSEGV)
 
+The example given is based on ``<exit code> - 128``
+if it is found in the :py:mod:`signal` module.
 The signal numbers (e.g. 11 for a segmentation fault) can be found in the
 "Standard signals" section of the `signal man page`_.
 Their meaning is described in `POSIX signals`_.

tests/test_result.py

@@ -1,3 +1,4 @@
+import signal
 import socket
 import sys
 
@@ -69,3 +70,30 @@ def test_get_commandlog(pkg):
     assert envlog.dict["setup"]
     setuplog2 = replog.get_envlog("py36").get_commandlog("setup")
     assert setuplog2.list == setuplog.list
+
+
+@pytest.mark.parametrize('exitcode', [None, 0, 5, 128 + signal.SIGTERM, 1234])
+def test_InvocationError(exitcode):
+    if exitcode is None:
+        exception = tox.exception.InvocationError("<command>")
+    else:
+        exception = tox.exception.InvocationError("<command>", exitcode)
+    result = str(exception)
+    if exitcode is None:
+        needle = "(exited with code"
+        assert needle not in result
+    else:
+        needle = "(exited with code %d)" % exitcode
+        assert needle in result
+        if exitcode > 128:
+            needle = ("Note: On unix systems, an exit code larger than 128 often "
+                      "means a fatal error signal")
+            assert needle in result
+            if exitcode == 128 + signal.SIGTERM:
+                eg_number = signal.SIGTERM
+                eg_name = "SIGTERM"
+            else:
+                eg_number = 11
+                eg_name = "SIGSEGV"
+            eg_str = "(e.g. {}=128+{}: {})".format(eg_number+128, eg_number, eg_name)
+            assert eg_str in result

tests/test_z_cmdline.py

@@ -906,18 +906,16 @@ def test_tox_cmdline(monkeypatch):
         tox.cmdline(['caller_script', '--help'])
 
 
-@pytest.mark.parametrize('exitcode', [0, 5, 129])
+@pytest.mark.parametrize('exitcode', [0, 6])
 def test_exitcode(initproj, cmd, exitcode):
+    """ Check for correct InvocationError, with exit code,
+        except for zero exit code """
     tox_ini_content = "[testenv:foo]\ncommands=python -c 'import sys; sys.exit(%d)'" % exitcode
     initproj("foo", filedefs={'tox.ini': tox_ini_content})
     result = cmd()
     if exitcode:
         needle = "(exited with code %d)" % exitcode
         assert any(needle in line for line in result.outlines)
-        if exitcode > 128:
-            needle = ("Note: On unix systems, an exit code larger than 128 "
-                      "often means a fatal error (e.g. 139=128+11: segmentation fault)")
-            assert any(needle in line for line in result.outlines)
     else:
-        needle = "(exited with code"
+        needle = "InvocationError"
         assert all(needle not in line for line in result.outlines)

tox/__init__.py

@@ -1,9 +1,12 @@
+import signal
+
 from pkg_resources import DistributionNotFound
 from pkg_resources import get_distribution
 
 from .hookspecs import hookimpl
 from .hookspecs import hookspec
 
+
 try:
     _full_version = get_distribution(__name__).version
     __version__ = _full_version.split('+', 1)[0]
@@ -41,11 +44,18 @@ def __init__(self, command, exitcode=None):
 
         def __str__(self):
             str_ = "%s for command %s" % (self.__class__.__name__, self.command)
-            if self.exitcode:
+            if self.exitcode is not None:
                 str_ += " (exited with code %d)" % (self.exitcode)
                 if self.exitcode > 128:
-                    str_ += ("\nNote: On unix systems, an exit code larger than 128 "
-                             "often means a fatal error (e.g. 139=128+11: segmentation fault)")
+                    signals = {number: name
+                               for name, number in vars(signal).items()
+                               if name.startswith("SIG")}
+                    number = self.exitcode - 128
+                    name = signals.get(number)
+                    (eg_number, eg_name) = (number, name) if name else (11, "SIGSEGV")
+                    str_ += ("\nNote: On unix systems, an exit code larger than 128 often "
+                             "means a fatal error signal "
+                             "(e.g. {}=128+{}: {})".format(eg_number+128, eg_number, eg_name))
             return str_
 
     class MissingFile(Error):