Closes #673

Author: sobolevn

docs/pages/contrib/pytest_plugins.rst

@@ -31,6 +31,43 @@ To use it in your tests, request ``returns`` fixture like so:
       ...
 
 
+assert_equal
+~~~~~~~~~~~~
+
+We have a special helper to compare containers' equality.
+
+It might be an easy task for two ``Result`` or ``Maybe`` containers,
+but it is not very easy for two ``ReaderResult`` or ``FutureResult`` instances.
+
+Take a look:
+
+.. code:: python
+
+  >>> from returns.result import Result
+  >>> from returns.context import Reader
+
+  >>> assert Result.from_value(1) == Result.from_value(1)
+  >>> Reader.from_value(1) == Reader.from_value(1)
+  False
+
+So, we can use :func:`~returns.primitives.asserts.assert_equal`
+or ``returns.assert_equal`` method from our ``pytest`` fixture:
+
+.. code:: python
+
+  >>> from returns.result import Success
+  >>> from returns.context import Reader
+  >>> from returns.contrib.pytest import ReturnsAsserts
+
+  >>> def test_container_equality(returns: ReturnsAsserts):
+  ...     returns.assert_equal(Success(1), Success(1))
+  ...     returns.assert_equal(Reader.from_value(1), Reader.from_value(1))
+
+  >>> # We only run these tests manually, because it is a doc example:
+  >>> returns_fixture = getfixture('returns')
+  >>> test_container_equality(returns_fixture)
+
+
 is_error_handled
 ~~~~~~~~~~~~~~~~
 
@@ -39,14 +76,18 @@ It tests that containers do handle error track.
 
 .. code:: python
 
-  from returns.result import Failure, Success
-  from returns.contrib.pytest import ReturnsAsserts
+  >>> from returns.result import Failure, Success
+  >>> from returns.contrib.pytest import ReturnsAsserts
+
+  >>> def test_error_handled(returns: ReturnsAsserts):
+  ...     assert not returns.is_error_handled(Failure(1))
+  ...     assert returns.is_error_handled(
+  ...         Failure(1).lash(lambda _: Success('default value')),
+  ...     )
 
-  def test_my_container(returns: ReturnsAsserts):
-      assert not returns.is_error_handled(Failure(1))
-      assert returns.is_error_handled(
-          Failure(1).lash(lambda _: Success('default value')),
-      )
+  >>> # We only run these tests manually, because it is a doc example:
+  >>> returns_fixture = getfixture('returns')
+  >>> test_error_handled(returns_fixture)
 
 We recommed to unit test big chunks of code this way.
 This is helpful for big pipelines where
@@ -82,8 +123,6 @@ created and looking for the desired function.
   >>> from returns.result import Result, Success, Failure
   >>> from returns.contrib.pytest import ReturnsAsserts
 
-  >>> returns_fixture = getfixture('returns')
-
   >>> def desired_function(arg: str) -> Result[int, str]:
   ...     if arg.isnumeric():
   ...         return Success(int(arg))
@@ -101,6 +140,8 @@ created and looking for the desired function.
   ...     with returns.has_trace(Success, desired_function):
   ...         Success('42').bind(desired_function)
 
+  >>> # We only run these tests manually, because it is a doc example:
+  >>> returns_fixture = getfixture('returns')
   >>> test_if_failure_is_created_at_convert_function(returns_fixture)
   >>> test_if_success_is_created_at_convert_function(returns_fixture)
 
@@ -128,3 +169,6 @@ API Reference
 
 .. automodule:: returns.contrib.pytest.plugin
    :members:
+
+.. automodule:: returns.primitives.asserts
+   :members:

returns/contrib/pytest/plugin.py

@@ -33,6 +33,18 @@ class ReturnsAsserts(object):
 
     __slots__ = ()
 
+    def assert_equal(
+        self,
+        first,
+        second,
+        *,
+        deps=None,
+        backend: str = 'asyncio',
+    ) -> None:
+        """Can compare two containers even with extra calling and awaiting."""
+        from returns.primitives.asserts import assert_equal
+        assert_equal(first, second, deps=deps, backend=backend)
+
     def is_error_handled(self, container: 'FailableN') -> bool:
         """Ensures that container has its error handled in the end."""
         return bool(getattr(container, _ERROR_FIELD, False))

returns/primitives/asserts.py

@@ -41,8 +41,7 @@ def _convert(container, *, deps, backend: str):
             deps=deps,
             backend=backend,
         )
-    # TODO: remove `callable`
-    if callable(container) or isinstance(container, reader.Contextable):
+    elif isinstance(container, reader.Contextable):
         return _convert(
             container(deps),
             deps=deps,

tests/test_contrib/test_pytest/test_plugin_error_handler.py

@@ -5,6 +5,7 @@
     RequiresContextIOResult,
     RequiresContextResult,
 )
+from returns.contrib.pytest import ReturnsAsserts
 from returns.functions import identity
 from returns.future import FutureResult
 from returns.io import IOFailure, IOSuccess
@@ -38,7 +39,7 @@ def _under_test(
 @pytest.mark.parametrize('kwargs', [
     {'should_lash': True},
 ])
-def test_error_handled(container, returns, kwargs):
+def test_error_handled(returns: ReturnsAsserts, container, kwargs):
     """Demo on how to use ``pytest`` helpers to work with error handling."""
     error_handled = _under_test(container, **kwargs)
 
@@ -59,7 +60,7 @@ def test_error_handled(container, returns, kwargs):
     RequiresContextResult.from_value(1),
     RequiresContextResult.from_failure(1),
 ])
-def test_error_not_handled(container, returns):
+def test_error_not_handled(returns: ReturnsAsserts, container):
     """Demo on how to use ``pytest`` helpers to work with error handling."""
     error_handled = _under_test(container)
 
@@ -76,7 +77,7 @@ def test_error_not_handled(container, returns):
     RequiresContextFutureResult.from_value(1),
     RequiresContextFutureResult.from_failure(1),
 ])
-async def test_error_not_handled_async(container, returns):
+async def test_error_not_handled_async(returns: ReturnsAsserts, container):
     """Demo on how to use ``pytest`` helpers to work with error handling."""
     error_handled = _under_test(container)
 

tests/test_primitives/test_asserts/test_assert_equal.py

@@ -8,6 +8,7 @@
     ReaderIOResult,
     ReaderResult,
 )
+from returns.contrib.pytest import ReturnsAsserts
 from returns.future import Future, FutureResult
 from returns.io import IO, IOResult
 from returns.maybe import Maybe
@@ -42,17 +43,42 @@
 
 
 @pytest.mark.parametrize('container', _containers)
-def test_assert_equal(container, anyio_backend_name):
+def test_assert_equal(container, anyio_backend_name: str):
     """Ensure that containers can be equal."""
     assert_equal(container, container, backend=anyio_backend_name)
 
 
 @pytest.mark.parametrize('container', _containers)
-def test_assert_equal_not(container, anyio_backend_name):
+def test_assert_equal_plugin(
+    container,
+    anyio_backend_name: str,
+    returns: ReturnsAsserts,
+):
+    """Ensure that containers can be equal."""
+    returns.assert_equal(container, container, backend=anyio_backend_name)
+
+
+@pytest.mark.parametrize('container', _containers)
+def test_assert_equal_not(container, anyio_backend_name: str):
     """Ensure that containers can be not equal."""
     with pytest.raises(AssertionError):
         assert_equal(
             container,
             container.from_value(2),
             backend=anyio_backend_name,
         )
+
+
+@pytest.mark.parametrize('container', _containers)
+def test_assert_equal_not_plugin(
+    container,
+    anyio_backend_name: str,
+    returns: ReturnsAsserts,
+):
+    """Ensure that containers can be not equal."""
+    with pytest.raises(AssertionError):
+        returns.assert_equal(
+            container,
+            container.from_value(2),
+            backend=anyio_backend_name,
+        )

typesafety/test_contrib/test_pytest/test_returns_asserts.yml

@@ -0,0 +1,13 @@
+- case: check_all_laws
+  disable_cache: false
+  main: |
+    from returns.contrib.pytest import ReturnsAsserts
+
+    x: ReturnsAsserts
+    reveal_type(x.has_trace)
+    reveal_type(x.is_error_handled)
+    reveal_type(x.assert_equal)
+  out: |
+    main:4: note: Revealed type is 'def [_ReturnsResultType <: def (*Any, **Any) -> returns.interfaces.specific.result.ResultLikeN[Any, Any, Any], _FunctionType <: def (*Any, **Any) -> Any] (trace_type: _ReturnsResultType`1429, function_to_search: _FunctionType`1430) -> contextlib._GeneratorContextManager[None]'
+    main:5: note: Revealed type is 'def (container: returns.interfaces.failable.FailableN[Any, Any, Any]) -> builtins.bool'
+    main:6: note: Revealed type is 'def (first: Any, second: Any, *, deps: Any =, backend: builtins.str =)'