Add new functions to testing.py

Author: domdfcoding

domdf_python_tools/testing.py

@@ -35,16 +35,21 @@
 import sys
 from functools import lru_cache
 from pathlib import Path
-from typing import Any, Iterator, List, Optional, Sequence, Tuple, Union
+from textwrap import dedent
+from typing import Any, Callable, Iterator, List, Optional, Sequence, Tuple, Union
 
 # 3rd party
 import pytest  # nodep
 from _pytest.mark import MarkDecorator  # nodep
+from jaraco.docker import is_docker  # type: ignore  # nodep
+from pytest_regressions.file_regression import FileRegressionFixture  # nodep
 
 # this package
 from domdf_python_tools.doctools import PYPY
 from domdf_python_tools.iterative import Len
 from domdf_python_tools.paths import PathPlus
+from domdf_python_tools.stringlist import StringList
+from domdf_python_tools.typing import PathLike
 from domdf_python_tools.versions import Version
 
 __all__ = [
@@ -63,6 +68,13 @@
 		"only_pypy",
 		"pytest_report_header",
 		"PEP_563",
+		"platform_boolean_factory",
+		"not_macos",
+		"only_macos",
+		"not_docker",
+		"only_docker",
+		"check_file_regression",
+		"check_file_output",
 		]
 
 MarkDecorator.__module__ = "_pytest.mark"
@@ -286,64 +298,71 @@ def max_version(
 	return pytest.mark.skipif(condition=sys.version_info[:3] > version_, reason=reason)
 
 
-def not_windows(reason: str = "Not required on Windows.", ) -> MarkDecorator:
+def platform_boolean_factory(
+		condition: bool,
+		platform: str,
+		versionadded: Optional[str] = None,
+		) -> Tuple[Callable[[str], MarkDecorator], Callable[[str], MarkDecorator]]:
 	"""
-	Factory function to return a ``@pytest.mark.skipif`` decorator that will
-	skip a test if the current platform is Windows.
-
-	:param reason: The reason to display when skipping.
-
-	:rtype:
-
-	.. versionadded:: 0.9.0
-	"""  # noqa D400
+	Factory function to return decorators such as :func:`~.not_pypy` and :func:`~.only_windows`.
 
-	return pytest.mark.skipif(condition=sys.platform == "win32", reason=reason)
+	:param condition: Should evaluate to :py:obj:`True` if the test should be skipped.
+	:param platform:
+	:param versionadded:
 
+	:return: 2-element tuple of ``not_function``, ``only_function``.
 
-def only_windows(reason: str = "Only required on Windows.", ) -> MarkDecorator:
+	.. versionadded: 1.5.0
 	"""
-	Factory function to return a ``@pytest.mark.skipif`` decorator that will
-	skip a test if the current platform is **not** Windows.
 
-	:param reason: The reason to display when skipping.
+	default_reason = "{} required on Windows"
 
-	:rtype:
+	def not_function(reason: str = default_reason.format("Not")) -> MarkDecorator:
+		return pytest.mark.skipif(condition=condition, reason=reason)
 
-	.. versionadded:: 0.9.0
-	"""  # noqa D400
+	def only_function(reason: str = default_reason.format("Only")) -> MarkDecorator:
+		return pytest.mark.skipif(condition=not condition, reason=reason)
 
-	return pytest.mark.skipif(condition=sys.platform != "win32", reason=reason)
+	docstring = dedent(
+			"""\
+Factory function to return a ``@pytest.mark.skipif`` decorator that will
+skip a test {why} the current platform is {platform}.
 
+:param reason: The reason to display when skipping.
+"""
+			)
 
-def not_pypy(reason: str = "Not required on PyPy.") -> MarkDecorator:
-	"""
-	Factory function to return a ``@pytest.mark.skipif`` decorator that will
-	skip a test if the current Python implementation is PyPy.
+	if versionadded:
+		docstring += f"\n\n:rtype:\n\n.. versionadded:: {versionadded}"
 
-	:param reason: The reason to display when skipping.
+	not_function.__name__ = f"not_{platform.lower()}"
+	not_function.__doc__ = docstring.format(why="if", platform=platform)
 
-	:rtype:
+	only_function.__name__ = f"only_{platform.lower()}"
+	only_function.__doc__ = docstring.format(why="unless", platform=platform)
 
-	.. versionadded:: 0.9.0
-	"""  # noqa D400
+	return not_function, only_function
 
-	return pytest.mark.skipif(condition=PYPY, reason=reason)
 
+not_windows, only_windows = platform_boolean_factory(
+		condition=sys.platform == "win32",
+		platform="Windows",
+		versionadded="0.9.0",
+		)
 
-def only_pypy(reason: str = "Only required on PyPy.") -> MarkDecorator:
-	"""
-	Factory function to return a ``@pytest.mark.skipif`` decorator that will
-	skip a test if the current Python implementation is not PyPy.
+not_macos, only_macos = platform_boolean_factory(
+		condition=sys.platform == "darwin",
+		platform="macOS",
+		versionadded="1.5.0",
+		)
 
-	:param reason: The reason to display when skipping.
+not_docker, only_docker = platform_boolean_factory(condition=is_docker(), platform="Docker", versionadded="1.5.0")
+not_docker.__doc__ = not_docker.__doc__.replace("the current platform is", "running on")
+only_docker.__doc__ = only_docker.__doc__.replace("the current platform is", "running on")
 
-	:rtype:
-
-	.. versionadded:: 0.9.0
-	"""  # noqa D400
-
-	return pytest.mark.skipif(condition=not PYPY, reason=reason)
+not_pypy, only_pypy = platform_boolean_factory(condition=PYPY, platform="Docker", versionadded="0.9.0")
+not_pypy.__doc__ = not_pypy.__doc__.replace("current platform", "current Python implementation")
+only_pypy.__doc__ = only_pypy.__doc__.replace("current platform", "current Python implementation")
 
 
 @pytest.fixture()
@@ -388,3 +407,56 @@ def pytest_report_header(config, startdir):
 
 .. versionadded:: 1.4.2
 """
+
+
+def check_file_regression(
+		data: Union[str, StringList],
+		file_regression: FileRegressionFixture,
+		extension: str = ".txt",
+		**kwargs,
+		):
+	r"""
+	Check the given data against that in the reference file.
+
+	:param data:
+	:param file_regression: The file regression fixture for the test.
+	:param extension: The extension of the reference file.
+	:param \*\*kwargs: Additional keyword arguments passed to :meth:`.FileRegressionFixture.check`.
+
+	.. versionadded:: 1.5.0
+	"""
+
+	if isinstance(data, StringList):
+		data = str(data)
+
+	file_regression.check(data, encoding="UTF-8", extension=extension, **kwargs)
+
+	return True
+
+
+def check_file_output(
+		filename: PathLike,
+		file_regression: FileRegressionFixture,
+		extension: Optional[str] = None,
+		**kwargs,
+		):
+	r"""
+	Check the content of the given file against the reference file.
+
+	:param filename:
+	:param file_regression: The file regression fixture for the test.
+	:param extension: The extension of the reference file.
+	:param \*\*kwargs: Additional keyword arguments passed to :meth:`.FileRegressionFixture.check`.
+
+	.. versionadded:: 1.5.0
+	"""
+
+	filename = PathPlus(filename)
+
+	data = filename.read_text(encoding="UTF-8")
+	extension = extension or filename.suffix
+
+	if extension == ".py":
+		extension = "._py_"
+
+	return check_file_regression(data, file_regression, extension, **kwargs)

repo_helper.yml

@@ -30,9 +30,6 @@ short_desc: 'Helpful functions for Python 🐍 🛠️'
 
 classifiers:
  - 'Development Status :: 4 - Beta'
-# - "Development Status :: 5 - Production/Stable"
-# - "Development Status :: 6 - Mature"
-# - "Development Status :: 7 - Inactive"
  - 'Intended Audience :: Developers'
  - 'Topic :: Software Development :: Libraries :: Python Modules'
 
@@ -41,6 +38,8 @@ extras_require:
    - pytz>=2019.1
   testing:
    - pytest>=6.0.0
+   - pytest-regressions>=2.0.2
+   - jaraco.docker>=2.0
 
 keywords:
  - utilities

tests/test_testing.py

@@ -2,14 +2,15 @@
 import platform
 import random
 import re
+import sys
 
 # 3rd party
 from _pytest.mark import Mark, MarkDecorator
 
 # this package
 from domdf_python_tools import testing
 from domdf_python_tools.paths import PathPlus
-from domdf_python_tools.testing import not_pypy
+from domdf_python_tools.testing import not_macos, not_pypy, not_windows, only_macos, only_pypy, only_windows
 from domdf_python_tools.utils import strtobool
 
 
@@ -149,6 +150,36 @@ def test_not_pypy():
 		assert False  # noqa: PT015
 
 
+@only_pypy("Success")
+def test_only_pypy():
+	if platform.python_implementation() != "PyPy":
+		assert False  # noqa: PT015
+
+
+@not_windows("Success")
+def test_not_windows():
+	if sys.platform == "win32":
+		assert False  # noqa: PT015
+
+
+@only_windows("Success")
+def test_only_windows():
+	if sys.platform != "win32":
+		assert False  # noqa: PT015
+
+
+@not_macos("Success")
+def test_not_macos():
+	if sys.platform == "darwin":
+		assert False  # noqa: PT015
+
+
+@only_macos("Success")
+def test_only_macos():
+	if sys.platform != "darwin":
+		assert False  # noqa: PT015
+
+
 pytest_plugins = ("domdf_python_tools.testing", )