conversion of exit codes to enum + exposure (#5420)

conversion of exit codes to enum  + exposure

changelog/5125.removal.rst

@@ -0,0 +1,5 @@
+``Session.exitcode`` values are now coded in ``pytest.ExitCode``, an ``IntEnum``. This makes the exit code available for consumer code and are more explicit other than just documentation. User defined exit codes are still valid, but should be used with caution.
+
+The team doesn't expect this change to break test suites or plugins in general, except in esoteric/specific scenarios.
+
+**pytest-xdist** users should upgrade to ``1.29.0`` or later, as ``pytest-xdist`` required a compatibility fix because of this change.

doc/en/reference.rst

@@ -727,6 +727,14 @@ ExceptionInfo
 .. autoclass:: _pytest._code.ExceptionInfo
  :members:
 
+
+pytest.ExitCode
+~~~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.main.ExitCode
+ :members:
+
+
 FixtureDef
 ~~~~~~~~~~
 

doc/en/usage.rst

@@ -33,6 +33,8 @@ Running ``pytest`` can result in six different exit codes:
 :Exit code 4: pytest command line usage error
 :Exit code 5: No tests were collected
 
+They are repressended by the :class:`_pytest.main.ExitCode` enum.
+
 Getting help on version, option names, environment variables
 --------------------------------------------------------------
 

src/_pytest/config/__init__.py

@@ -48,7 +48,7 @@ def main(args=None, plugins=None):
  :arg plugins: list of plugin objects to be auto-registered during
  initialization.
  """
- from _pytest.main import EXIT_USAGEERROR
+ from _pytest.main import ExitCode
 
  try:
  try:
@@ -78,7 +78,7 @@ def main(args=None, plugins=None):
  tw = py.io.TerminalWriter(sys.stderr)
  for msg in e.args:
  tw.line("ERROR: {}\n".format(msg), red=True)
- return EXIT_USAGEERROR
+ return ExitCode.USAGE_ERROR
 
 
 class cmdline: # compatibility namespace

src/_pytest/main.py

@@ -1,4 +1,5 @@
 """ core implementation of testing process: init, session, runtest loop. """
+import enum
 import fnmatch
 import functools
 import os
@@ -18,13 +19,26 @@
 from _pytest.outcomes import exit
 from _pytest.runner import collect_one_node
 
-# exitcodes for the command line
-EXIT_OK = 0
-EXIT_TESTSFAILED = 1
-EXIT_INTERRUPTED = 2
-EXIT_INTERNALERROR = 3
-EXIT_USAGEERROR = 4
-EXIT_NOTESTSCOLLECTED = 5
+
+class ExitCode(enum.IntEnum):
+ """
+ Encodes the valid exit codes by pytest.
+
+ Currently users and plugins may supply other exit codes as well.
+ """
+
+ #: tests passed
+ OK = 0
+ #: tests failed
+ TESTS_FAILED = 1
+ #: pytest was interrupted
+ INTERRUPTED = 2
+ #: an internal error got in the way
+ INTERNAL_ERROR = 3
+ #: pytest was missused
+ USAGE_ERROR = 4
+ #: pytest couldnt find tests
+ NO_TESTS_COLLECTED = 5
 
 
 def pytest_addoption(parser):
@@ -188,7 +202,7 @@ def pytest_configure(config):
 def wrap_session(config, doit):
  """Skeleton command line program"""
  session = Session(config)
- session.exitstatus = EXIT_OK
+ session.exitstatus = ExitCode.OK
  initstate = 0
  try:
  try:
@@ -198,13 +212,13 @@ def wrap_session(config, doit):
  initstate = 2
  session.exitstatus = doit(config, session) or 0
  except UsageError:
- session.exitstatus = EXIT_USAGEERROR
+ session.exitstatus = ExitCode.USAGE_ERROR
  raise
  except Failed:
- session.exitstatus = EXIT_TESTSFAILED
+ session.exitstatus = ExitCode.TESTS_FAILED
  except (KeyboardInterrupt, exit.Exception):
  excinfo = _pytest._code.ExceptionInfo.from_current()
- exitstatus = EXIT_INTERRUPTED
+ exitstatus = ExitCode.INTERRUPTED
  if isinstance(excinfo.value, exit.Exception):
  if excinfo.value.returncode is not None:
  exitstatus = excinfo.value.returncode
@@ -217,7 +231,7 @@ def wrap_session(config, doit):
  except: # noqa
  excinfo = _pytest._code.ExceptionInfo.from_current()
  config.notify_exception(excinfo, config.option)
- session.exitstatus = EXIT_INTERNALERROR
+ session.exitstatus = ExitCode.INTERNAL_ERROR
  if excinfo.errisinstance(SystemExit):
  sys.stderr.write("mainloop: caught unexpected SystemExit!\n")
 
@@ -243,9 +257,9 @@ def _main(config, session):
  config.hook.pytest_runtestloop(session=session)
 
  if session.testsfailed:
- return EXIT_TESTSFAILED
+ return ExitCode.TESTS_FAILED
  elif session.testscollected == 0:
- return EXIT_NOTESTSCOLLECTED
+ return ExitCode.NO_TESTS_COLLECTED
 
 
 def pytest_collection(session):

src/_pytest/pytester.py

@@ -19,8 +19,7 @@
 from _pytest.assertion.rewrite import AssertionRewritingHook
 from _pytest.capture import MultiCapture
 from _pytest.capture import SysCapture
-from _pytest.main import EXIT_INTERRUPTED
-from _pytest.main import EXIT_OK
+from _pytest.main import ExitCode
 from _pytest.main import Session
 from _pytest.monkeypatch import MonkeyPatch
 from _pytest.pathlib import Path
@@ -691,7 +690,7 @@ def getnode(self, config, arg):
  p = py.path.local(arg)
  config.hook.pytest_sessionstart(session=session)
  res = session.perform_collect([str(p)], genitems=False)[0]
- config.hook.pytest_sessionfinish(session=session, exitstatus=EXIT_OK)
+ config.hook.pytest_sessionfinish(session=session, exitstatus=ExitCode.OK)
  return res
 
  def getpathnode(self, path):
@@ -708,11 +707,11 @@ def getpathnode(self, path):
  x = session.fspath.bestrelpath(path)
  config.hook.pytest_sessionstart(session=session)
  res = session.perform_collect([x], genitems=False)[0]
- config.hook.pytest_sessionfinish(session=session, exitstatus=EXIT_OK)
+ config.hook.pytest_sessionfinish(session=session, exitstatus=ExitCode.OK)
  return res
 
  def genitems(self, colitems):
- """Generate all test items from a collection node.
+ """Generate all test items from a collection node.src/_pytest/main.py
 
  This recurses into the collection node and returns a list of all the
  test items contained within.
@@ -841,7 +840,7 @@ class reprec:
 
  # typically we reraise keyboard interrupts from the child run
  # because it's our user requesting interruption of the testing
- if ret == EXIT_INTERRUPTED and not no_reraise_ctrlc:
+ if ret == ExitCode.INTERRUPTED and not no_reraise_ctrlc:
  calls = reprec.getcalls("pytest_keyboard_interrupt")
  if calls and calls[-1].excinfo.type == KeyboardInterrupt:
  raise KeyboardInterrupt()

src/_pytest/terminal.py

@@ -16,11 +16,7 @@
 
 import pytest
 from _pytest import nodes
-from _pytest.main import EXIT_INTERRUPTED
-from _pytest.main import EXIT_NOTESTSCOLLECTED
-from _pytest.main import EXIT_OK
-from _pytest.main import EXIT_TESTSFAILED
-from _pytest.main import EXIT_USAGEERROR
+from _pytest.main import ExitCode
 
 REPORT_COLLECTING_RESOLUTION = 0.5
 
@@ -654,17 +650,17 @@ def pytest_sessionfinish(self, exitstatus):
  outcome.get_result()
  self._tw.line("")
  summary_exit_codes = (
- EXIT_OK,
- EXIT_TESTSFAILED,
- EXIT_INTERRUPTED,
- EXIT_USAGEERROR,
- EXIT_NOTESTSCOLLECTED,
+ ExitCode.OK,
+ ExitCode.TESTS_FAILED,
+ ExitCode.INTERRUPTED,
+ ExitCode.USAGE_ERROR,
+ ExitCode.NO_TESTS_COLLECTED,
  )
  if exitstatus in summary_exit_codes:
  self.config.hook.pytest_terminal_summary(
  terminalreporter=self, exitstatus=exitstatus, config=self.config
  )
- if exitstatus == EXIT_INTERRUPTED:
+ if exitstatus == ExitCode.INTERRUPTED:
  self._report_keyboardinterrupt()
  del self._keyboardinterrupt_memo
  self.summary_stats()

src/pytest.py

@@ -15,6 +15,7 @@
 from _pytest.fixtures import fixture
 from _pytest.fixtures import yield_fixture
 from _pytest.freeze_support import freeze_includes
+from _pytest.main import ExitCode
 from _pytest.main import Session
 from _pytest.mark import MARK_GEN as mark
 from _pytest.mark import param
@@ -57,6 +58,7 @@
  "Collector",
  "deprecated_call",
  "exit",
+ "ExitCode",
  "fail",
  "File",
  "fixture",

testing/acceptance_test.py

@@ -8,8 +8,7 @@
 import py
 
 import pytest
-from _pytest.main import EXIT_NOTESTSCOLLECTED
-from _pytest.main import EXIT_USAGEERROR
+from _pytest.main import ExitCode
 from _pytest.warnings import SHOW_PYTEST_WARNINGS_ARG
 
 
@@ -24,7 +23,7 @@ class TestGeneralUsage:
  def test_config_error(self, testdir):
  testdir.copy_example("conftest_usageerror/conftest.py")
  result = testdir.runpytest(testdir.tmpdir)
- assert result.ret == EXIT_USAGEERROR
+ assert result.ret == ExitCode.USAGE_ERROR
  result.stderr.fnmatch_lines(["*ERROR: hello"])
  result.stdout.fnmatch_lines(["*pytest_unconfigure_called"])
 
@@ -83,7 +82,7 @@ def pytest_unconfigure():
  """
  )
  result = testdir.runpytest("-s", "asd")
- assert result.ret == 4 # EXIT_USAGEERROR
+ assert result.ret == ExitCode.USAGE_ERROR
  result.stderr.fnmatch_lines(["ERROR: file not found*asd"])
  result.stdout.fnmatch_lines(["*---configure", "*---unconfigure"])
 
@@ -229,7 +228,7 @@ def pytest_collect_directory():
  """
  )
  result = testdir.runpytest()
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
  result.stdout.fnmatch_lines(["*1 skip*"])
 
  def test_issue88_initial_file_multinodes(self, testdir):
@@ -247,7 +246,7 @@ def test_issue93_initialnode_importing_capturing(self, testdir):
  """
  )
  result = testdir.runpytest()
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
  assert "should not be seen" not in result.stdout.str()
  assert "stderr42" not in result.stderr.str()
 
@@ -290,13 +289,13 @@ def test_issue109_sibling_conftests_not_loaded(self, testdir):
  sub2 = testdir.mkdir("sub2")
  sub1.join("conftest.py").write("assert 0")
  result = testdir.runpytest(sub2)
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
  sub2.ensure("__init__.py")
  p = sub2.ensure("test_hello.py")
  result = testdir.runpytest(p)
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
  result = testdir.runpytest(sub1)
- assert result.ret == EXIT_USAGEERROR
+ assert result.ret == ExitCode.USAGE_ERROR
 
  def test_directory_skipped(self, testdir):
  testdir.makeconftest(
@@ -308,7 +307,7 @@ def pytest_ignore_collect():
  )
  testdir.makepyfile("def test_hello(): pass")
  result = testdir.runpytest()
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
  result.stdout.fnmatch_lines(["*1 skipped*"])
 
  def test_multiple_items_per_collector_byid(self, testdir):
@@ -410,18 +409,18 @@ def test_a():
  def test_report_all_failed_collections_initargs(self, testdir):
  testdir.makeconftest(
  """
- from _pytest.main import EXIT_USAGEERROR
+ from _pytest.main import ExitCode
 
  def pytest_sessionfinish(exitstatus):
- assert exitstatus == EXIT_USAGEERROR
+ assert exitstatus == ExitCode.USAGE_ERROR
  print("pytest_sessionfinish_called")
  """
  )
  testdir.makepyfile(test_a="def", test_b="def")
  result = testdir.runpytest("test_a.py::a", "test_b.py::b")
  result.stderr.fnmatch_lines(["*ERROR*test_a.py::a*", "*ERROR*test_b.py::b*"])
  result.stdout.fnmatch_lines(["pytest_sessionfinish_called"])
- assert result.ret == EXIT_USAGEERROR
+ assert result.ret == ExitCode.USAGE_ERROR
 
  @pytest.mark.usefixtures("recwarn")
  def test_namespace_import_doesnt_confuse_import_hook(self, testdir):
@@ -612,7 +611,7 @@ def test_invoke_with_invalid_type(self, capsys):
 
  def test_invoke_with_path(self, tmpdir, capsys):
  retcode = pytest.main(tmpdir)
- assert retcode == EXIT_NOTESTSCOLLECTED
+ assert retcode == ExitCode.NO_TESTS_COLLECTED
  out, err = capsys.readouterr()
 
  def test_invoke_plugin_api(self, testdir, capsys):
@@ -1160,7 +1159,7 @@ def test_fixture_mock_integration(testdir):
 
 def test_usage_error_code(testdir):
  result = testdir.runpytest("-unknown-option-")
- assert result.ret == EXIT_USAGEERROR
+ assert result.ret == ExitCode.USAGE_ERROR
 
 
 @pytest.mark.filterwarnings("default")

testing/python/collect.py

@@ -4,7 +4,7 @@
 
 import _pytest._code
 import pytest
-from _pytest.main import EXIT_NOTESTSCOLLECTED
+from _pytest.main import ExitCode
 from _pytest.nodes import Collector
 
 
@@ -246,7 +246,7 @@ def prop(self):
  """
  )
  result = testdir.runpytest()
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
 
 
 class TestFunction:
@@ -1140,7 +1140,7 @@ class Test(object):
  )
  result = testdir.runpytest()
  assert "TypeError" not in result.stdout.str()
- assert result.ret == EXIT_NOTESTSCOLLECTED
+ assert result.ret == ExitCode.NO_TESTS_COLLECTED
 
 
 def test_collect_functools_partial(testdir):

testing/test_assertrewrite.py

@@ -15,7 +15,7 @@
 from _pytest.assertion.rewrite import AssertionRewritingHook
 from _pytest.assertion.rewrite import PYTEST_TAG
 from _pytest.assertion.rewrite import rewrite_asserts
-from _pytest.main import EXIT_NOTESTSCOLLECTED
+from _pytest.main import ExitCode
 
 
 def setup_module(mod):
@@ -692,7 +692,7 @@ def test_zipfile(self, testdir):
  import test_gum.test_lizard"""
  % (z_fn,)
  )
- assert testdir.runpytest().ret == EXIT_NOTESTSCOLLECTED
+ assert testdir.runpytest().ret == ExitCode.NO_TESTS_COLLECTED
 
  def test_readonly(self, testdir):
  sub = testdir.mkdir("testing")
@@ -792,7 +792,7 @@ def test_package_without__init__py(self, testdir):
  pkg = testdir.mkdir("a_package_without_init_py")
  pkg.join("module.py").ensure()
  testdir.makepyfile("import a_package_without_init_py.module")
- assert testdir.runpytest().ret == EXIT_NOTESTSCOLLECTED
+ assert testdir.runpytest().ret == ExitCode.NO_TESTS_COLLECTED
 
  def test_rewrite_warning(self, testdir):
  testdir.makeconftest(