document is_hypothesis_test

Author: tybug

hypothesis-python/RELEASE.rst

@@ -0,0 +1,3 @@
+RELEASE_TYPE: minor
+
+Add |is_hypothesis_test|, for third-party libraries which want to determine whether a test has been defined with Hypothesis.

hypothesis-python/docs/conf.py

@@ -259,6 +259,8 @@ def setup(app):
 .. |BackgroundWriteDatabase| replace:: :class:`~hypothesis.database.BackgroundWriteDatabase`
 .. |RedisExampleDatabase| replace:: :class:`~hypothesis.extra.redis.RedisExampleDatabase`
 
+.. |is_hypothesis_test| replace:: :func:`~hypothesis.is_hypothesis_test`
+
 .. |str| replace:: :obj:`python:str`
 .. |int| replace:: :obj:`python:int`
 .. |bool| replace:: :obj:`python:bool`

hypothesis-python/docs/reference/api.rst

@@ -1013,3 +1013,10 @@ For authors of test runners however, assigning to the ``inner_test`` attribute o
     and ``**kwargs`` expected by the original test.
 
 If the end user has also specified a custom executor using the ``execute_example`` method, it - and all other execution-time logic - will be applied to the *new* inner test assigned by the test runner.
+
+Detecting Hypothesis tests
+--------------------------
+
+To determine whether a test has been defined with Hypothesis or not, use |is_hypothesis_test|:
+
+.. autofunction:: hypothesis.is_hypothesis_test

hypothesis-python/src/_hypothesis_pytestplugin.py

@@ -203,8 +203,7 @@ def pytest_runtest_call(item):
             yield
             return
 
-        from hypothesis import core
-        from hypothesis.internal.detection import is_hypothesis_test
+        from hypothesis import core, is_hypothesis_test
 
         # See https://github.com/pytest-dev/pytest/issues/9159
         core.pytest_shows_exceptiongroups = (
@@ -415,7 +414,7 @@ def pytest_collection_modifyitems(items):
         if "hypothesis" not in sys.modules:
             return
 
-        from hypothesis.internal.detection import is_hypothesis_test
+        from hypothesis import is_hypothesis_test
 
         for item in items:
             if isinstance(item, pytest.Function) and is_hypothesis_test(item.obj):
@@ -433,7 +432,7 @@ def pytest_sessionstart(session):
 
     def _ban_given_call(self, function):
         if "hypothesis" in sys.modules:
-            from hypothesis.internal.detection import is_hypothesis_test
+            from hypothesis import is_hypothesis_test
 
             if is_hypothesis_test(function):
                 raise RuntimeError(

hypothesis-python/src/hypothesis/__init__.py

@@ -28,6 +28,7 @@
 )
 from hypothesis.core import example, find, given, reproduce_failure, seed
 from hypothesis.entry_points import run
+from hypothesis.internal.detection import is_hypothesis_test
 from hypothesis.internal.entropy import register_random
 from hypothesis.utils.conventions import infer
 from hypothesis.version import __version__, __version_info__
@@ -45,6 +46,7 @@
     "find",
     "given",
     "infer",
+    "is_hypothesis_test",
     "note",
     "register_random",
     "reject",

hypothesis-python/src/hypothesis/internal/detection.py

@@ -11,7 +11,26 @@
 from types import MethodType
 
 
-def is_hypothesis_test(test: object) -> bool:
-    if isinstance(test, MethodType):
-        return is_hypothesis_test(test.__func__)
-    return getattr(test, "is_hypothesis_test", False)
+def is_hypothesis_test(f: object) -> bool:
+    """
+    Returns ``True`` if ``f`` represents a test function that has been defined
+    with Hypothesis. This is true for:
+
+    * Functions decorated with |@given|
+    * The ``runTest`` method of stateful tests
+
+    For example:
+
+    .. code-block:: python
+
+        @given(st.integers())
+        def f(n): ...
+
+        class MyStateMachine(RuleBasedStateMachine): ...
+
+        assert is_hypothesis_test(f)
+        assert is_hypothesis_test(MyStateMachine.TestCase().runTest)
+    """
+    if isinstance(f, MethodType):
+        return is_hypothesis_test(f.__func__)
+    return getattr(f, "is_hypothesis_test", False)

hypothesis-python/tests/conftest.py

@@ -21,11 +21,11 @@
 import pytest
 from _pytest.monkeypatch import MonkeyPatch
 
+from hypothesis import is_hypothesis_test
 from hypothesis._settings import is_in_ci
 from hypothesis.errors import NonInteractiveExampleWarning
 from hypothesis.internal.compat import add_note
 from hypothesis.internal.conjecture import junkdrawer
-from hypothesis.internal.detection import is_hypothesis_test
 
 from tests.common import TIME_INCREMENT
 from tests.common.setup import run

hypothesis-python/tests/cover/test_detection.py

@@ -8,8 +8,7 @@
 # v. 2.0. If a copy of the MPL was not distributed with this file, You can
 # obtain one at https://mozilla.org/MPL/2.0/.
 
-from hypothesis import given
-from hypothesis.internal.detection import is_hypothesis_test
+from hypothesis import given, is_hypothesis_test
 from hypothesis.stateful import RuleBasedStateMachine, rule
 from hypothesis.strategies import integers