Added the pytest.mark.skip_on_env marker.

Fixes #14

Signed-off-by: Pedro Algarvio <palgarvio@vmware.com>

Author: Pedro Algarvio

.pylint-spelling-words

@@ -17,6 +17,7 @@ cwd
 darwin
 dns
 eg
+eq
 favicon
 favicons
 freebsd
@@ -40,6 +41,7 @@ macos
 mtime
 namespace
 namespaced
+ne
 netbsd
 noqa
 nox
@@ -67,5 +69,6 @@ sys
 toml
 towncrier
 utils
+varname
 virtualenvs
 vmware

changelog/14.feature.rst

@@ -0,0 +1 @@
+Added the ``pytest.mark.skip_on_env`` marker.

docs/ref/pytestskipmarkers/plugin.rst

@@ -565,6 +565,41 @@ Markers
 
 
 
+.. _markers.skip_on_env:
+
+``skip_on_env``
+===============
+
+.. py:decorator:: pytest.mark.skip_on_env(envvar, present=True, eq=None, ne=None)
+
+    :keyword str varname: The environment variable to check
+    :keyword bool present:
+        When ``True``, skip if variable is present in the environment.
+        When ``False``, skip if variable is not present in the environment.
+    :keyword str eq: Skips when the variable is present in the environment and matches this value.
+    :keyword str ne: Skips when the variable is present in the environment and does not match this value.
+    :keyword str reason: The skip reason
+
+    Skip test based on the presence/absence of `envvar` in the environment and it's value.
+
+    .. code-block:: python
+
+        @pytest.mark.skip_on_env("FLAKY_TEST")
+        def test_func():
+            assert True
+
+
+        @pytest.mark.skip_on_env("FLAKY_TEST", eq="1")
+        def test_func():
+            assert True
+
+
+        @pytest.mark.skip_on_env("FLAKY_TEST", present=False)
+        def test_func():
+            assert True
+
+
+
 .. _markers.skip_on_platforms:
 
 ``skip_on_platforms``

src/pytestskipmarkers/downgraded/plugin.py

@@ -131,3 +131,7 @@ def pytest_configure(config: 'Config') -> None:
         'markers',
         'skip_unless_on_platforms(windows=False, linux=False, darwin=False, sunos=False, smartos=False, freebsd=False, netbsd=False, openbsd=False, aix=False, aarch64=False, spawning=False, photonos=False): Pass True to one or more keywords to get the test skipped unless matched.',
     )
+    config.addinivalue_line(
+        'markers',
+        'skip_on_env(envvar, present=True, eq=None, ne=None): Skip test based on environment variables presence and contents.',
+    )

src/pytestskipmarkers/downgraded/utils/markers.py

@@ -168,6 +168,63 @@ def skip_if_no_remote_network() -> Optional[str]:
     return None
 
 
+def skip_on_env(
+    varname: str,
+    present: bool = True,
+    eq: Optional[str] = None,
+    ne: Optional[str] = None,
+    reason: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Helper function to check for environment variables.
+
+    If any of the checks match, return the skip reason.
+
+    Args:
+        varname(str):
+            The environment variable to check
+        present(bool):
+            When ``True``, skip if variable is present in the environment.
+            When ``False``, skip if variable is not present in the environment.
+        eq(str):
+            Skips when the variable is present in the environment and matches this value.
+        ne(str):
+            Skips when the variable is present in the environment and does not match this value.
+        reason(str):
+            The custom reason message to use.
+
+    Returns:
+        str: The skip reason
+        None: Should not be skipped.
+    """
+    if eq and ne:
+        raise pytest.UsageError('Cannot pass both `eq` and `ne`.')
+    if present is False and (eq or ne):
+        raise pytest.UsageError('Cannot pass `present=False` and either `eq` or `ne`.')
+    if present is False and varname not in os.environ:
+        if not reason:
+            reason = "The variable '{0}' is not present in the environ.".format(varname)
+        return reason
+    elif present is True and varname in os.environ:
+        varname_value = os.environ[varname]
+        if eq:
+            if varname_value == eq:
+                if not reason:
+                    reason = "'{0}' present in environ and '{1}=={2}'".format(
+                        varname, varname, eq
+                    )
+        elif ne:
+            if varname_value != ne:
+                if not reason:
+                    reason = "'{0}' present in environ and '{1}!={2}'".format(
+                        varname, varname, eq
+                    )
+        elif not reason:
+            reason = "The variable '{0}' is present in the environ.".format(varname)
+        return reason
+    return None
+
+
 def evaluate_markers(item: 'Item') -> None:
     """
     Fixtures injection based on markers or test skips based on CLI arguments.
@@ -695,3 +752,31 @@ def evaluate_markers(item: 'Item') -> None:
             raise pytest.UsageError(
                 'Passed an invalid platform to skip_unless_on_platforms: {}'.format(exc)
             )
+    skip_on_env_marker = item.get_closest_marker('skip_on_env')
+    if skip_on_env_marker is not None:
+        args = list(skip_on_env_marker.args)
+        if not args:
+            raise pytest.UsageError(
+                "The 'skip_on_env' marker needs at least one argument to be passed, the environment variable name."
+            )
+        envvar = args.pop(0)
+        if args:
+            raise pytest.UsageError(
+                "The 'skip_on_env' only accepts one argument, the environment variable name."
+            )
+        if not isinstance(envvar, str):
+            raise pytest.UsageError(
+                'The environment variable argument must be a string.'
+            )
+        kwargs = cast(Dict[str, Any], skip_on_env_marker.kwargs).copy()
+        present = kwargs.pop('present', True)
+        eq = kwargs.pop('eq', None)
+        ne = kwargs.pop('ne', None)
+        reason = kwargs.pop('reason', None)
+        if kwargs:
+            raise pytest.UsageError(
+                "The 'skip_on_env' marker only accepts 'present', 'eq', 'ne' and 'reason' as keyword arguments."
+            )
+        skip_reason = skip_on_env(envvar, present=present, eq=eq, ne=ne, reason=reason)
+        if skip_reason:
+            raise pytest.skip.Exception(skip_reason, **exc_kwargs)

src/pytestskipmarkers/plugin.py

@@ -195,3 +195,8 @@ def pytest_configure(config: "Config") -> None:
         "netbsd=False, openbsd=False, aix=False, aarch64=False, spawning=False, photonos=False): Pass True to "
         "one or more keywords to get the test skipped unless matched.",
     )
+    config.addinivalue_line(
+        "markers",
+        "skip_on_env(envvar, present=True, eq=None, ne=None): Skip test based on environment variables presence "
+        "and contents.",
+    )

src/pytestskipmarkers/utils/markers.py

@@ -173,6 +173,59 @@ def skip_if_no_remote_network() -> Optional[str]:
     return None
 
 
+def skip_on_env(
+    varname: str,
+    present: bool = True,
+    eq: Optional[str] = None,
+    ne: Optional[str] = None,
+    reason: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Helper function to check for environment variables.
+
+    If any of the checks match, return the skip reason.
+
+    Args:
+        varname(str):
+            The environment variable to check
+        present(bool):
+            When ``True``, skip if variable is present in the environment.
+            When ``False``, skip if variable is not present in the environment.
+        eq(str):
+            Skips when the variable is present in the environment and matches this value.
+        ne(str):
+            Skips when the variable is present in the environment and does not match this value.
+        reason(str):
+            The custom reason message to use.
+
+    Returns:
+        str: The skip reason
+        None: Should not be skipped.
+    """
+    if eq and ne:
+        raise pytest.UsageError("Cannot pass both `eq` and `ne`.")
+    if present is False and (eq or ne):
+        raise pytest.UsageError("Cannot pass `present=False` and either `eq` or `ne`.")
+    if present is False and varname not in os.environ:
+        if not reason:
+            reason = f"The variable '{varname}' is not present in the environ."
+        return reason
+    elif present is True and varname in os.environ:
+        varname_value = os.environ[varname]
+        if eq:
+            if varname_value == eq:
+                if not reason:
+                    reason = f"'{varname}' present in environ and '{varname}=={eq}'"
+        elif ne:
+            if varname_value != ne:
+                if not reason:
+                    reason = f"'{varname}' present in environ and '{varname}!={eq}'"
+        elif not reason:
+            reason = f"The variable '{varname}' is present in the environ."
+        return reason
+    return None
+
+
 def evaluate_markers(item: "Item") -> None:
     """
     Fixtures injection based on markers or test skips based on CLI arguments.
@@ -659,3 +712,33 @@ def evaluate_markers(item: "Item") -> None:
             raise pytest.UsageError(
                 "Passed an invalid platform to skip_unless_on_platforms: {}".format(exc)
             )
+
+    skip_on_env_marker = item.get_closest_marker("skip_on_env")
+    if skip_on_env_marker is not None:
+        args = list(skip_on_env_marker.args)
+        if not args:
+            raise pytest.UsageError(
+                "The 'skip_on_env' marker needs at least one argument to be passed, the environment "
+                "variable name."
+            )
+        envvar = args.pop(0)
+        if args:
+            raise pytest.UsageError(
+                "The 'skip_on_env' only accepts one argument, the environment variable name."
+            )
+        if not isinstance(envvar, str):
+            raise pytest.UsageError("The environment variable argument must be a string.")
+
+        kwargs = cast(Dict[str, Any], skip_on_env_marker.kwargs).copy()
+        present = kwargs.pop("present", True)
+        eq = kwargs.pop("eq", None)
+        ne = kwargs.pop("ne", None)
+        reason = kwargs.pop("reason", None)
+        if kwargs:
+            raise pytest.UsageError(
+                "The 'skip_on_env' marker only accepts 'present', 'eq', 'ne' and 'reason' as "
+                "keyword arguments."
+            )
+        skip_reason = skip_on_env(envvar, present=present, eq=eq, ne=ne, reason=reason)
+        if skip_reason:
+            raise pytest.skip.Exception(skip_reason, **exc_kwargs)

tests/functional/test_skip_on_env.py

@@ -0,0 +1,40 @@
+# Copyright 2021-2022 VMware, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+"""
+Test the ``@pytest.mark.skip_on_env`` marker.
+"""
+import os
+from unittest import mock
+
+
+def test_skipped(pytester):
+    pytester.makepyfile(
+        """
+        import pytest
+
+        @pytest.mark.skip_on_env("FOOBAR")
+        def test_one():
+            assert True
+        """
+    )
+    with mock.patch.dict(os.environ, FOOBAR="1"):
+        res = pytester.runpytest_inprocess()
+        res.assert_outcomes(skipped=1)
+    res.stdout.no_fnmatch_line("*PytestUnknownMarkWarning*")
+
+
+def test_not_skipped(pytester):
+    pytester.makepyfile(
+        """
+        import pytest
+
+        @pytest.mark.skip_on_env("FOOBAR", eq="2")
+        def test_one():
+            assert True
+        """
+    )
+    with mock.patch.dict(os.environ, FOOBAR="1"):
+        res = pytester.runpytest_inprocess()
+        res.assert_outcomes(passed=1)
+    res.stdout.no_fnmatch_line("*PytestUnknownMarkWarning*")

tests/unit/utils/markers/test_skip_on_env.py

@@ -0,0 +1,51 @@
+# Copyright 2021-2022 VMware, Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+"""
+Test the "skip_on_env" marker helper.
+"""
+import logging
+import os
+from unittest import mock
+
+import pytest
+
+import pytestskipmarkers.utils.markers as markers
+
+log = logging.getLogger(__name__)
+
+
+def test_not_present_and_eq():
+    with pytest.raises(pytest.UsageError):
+        markers.skip_on_env("FOOBAR", present=False, eq="1")
+
+
+def test_not_present_and_ne():
+    with pytest.raises(pytest.UsageError):
+        markers.skip_on_env("FOOBAR", present=False, ne="1")
+
+
+def test_present_and_eq_and_ne():
+    with pytest.raises(pytest.UsageError):
+        markers.skip_on_env("FOOBAR", eq="1", ne="1")
+
+
+def test_present_true():
+    with mock.patch.dict(os.environ, FOO="1"):
+        assert markers.skip_on_env("FOO") is not None
+
+
+def test_present_false():
+    assert markers.skip_on_env(__name__.upper(), present=False) is not None
+
+
+def test_present_true_and_eq():
+    with mock.patch.dict(os.environ, FOO="1"):
+        assert markers.skip_on_env("FOO", eq="1") is not None
+        assert markers.skip_on_env("FOO", eq="2") is None
+
+
+def test_present_true_and_ne():
+    with mock.patch.dict(os.environ, FOO="1"):
+        assert markers.skip_on_env("FOO", ne="2") is not None
+        assert markers.skip_on_env("FOO", ne="1") is None