Mockito for Python

Warnings

• breaking Several verification functions were renamed in v2.x for clarity. `verifyNoMoreInteractions` is now `ensureNoUnverifiedInteractions`, and `verifyNoUnwantedInteractions` is now `verifyExpectedInteractions`. The legacy `inorder.verify(...)` has been replaced by a more robust `InOrder(...)` API for cross-mock verification.
  Fix: Update calls to the new function names: `ensureNoUnverifiedInteractions`, `verifyExpectedInteractions`, and use `InOrder(...)` for ordered verification.
• breaking Context managers (e.g., `with when(...)`) in v2.x now automatically check usage and explicit expectations (set via `expect`) on exit. This can cause `UnnecessaryStubbingException` if stubs are defined but not used.
  Fix: Ensure all stubs defined within a context manager are actually invoked in the test. If intentional, this check can be disabled by setting the environment variable `MOCKITO_CONTEXT_MANAGERS_CHECK_USAGE` to '0'.
• deprecated The functions `verifyNoMoreInteractions`, `verifyNoUnwantedInteractions`, and the limited `inorder.verify(...)` mode are deprecated in favor of their renamed or enhanced counterparts.
  Fix: Migrate to `ensureNoUnverifiedInteractions`, `verifyExpectedInteractions`, and the `InOrder(...)` API for future compatibility and improved semantics.
• gotcha It is crucial to call `unstub()` after each test that uses Mockito's `when()` or `patch_*` functions to prevent mocks from leaking into other tests and causing flaky results.
  Fix: Always include `unstub()` in your test teardown (e.g., `tearDown` in `unittest.TestCase` or use `pytest-mockito` fixtures for automatic handling).
• gotcha By default, `mock()` objects are not 'strict'. This means unstubbed methods will return `None` without an error. If `mock(strict=True)` is used, any unexpected (unstubbed) interactions will raise an error immediately.
  Fix: Decide on strictness based on your testing philosophy. For robust tests that fail on unexpected calls, use `mock(strict=True)` or `mock(spec=YourClass)` (which implies strictness).
• gotcha Mockito's `any()` matchers in v2.x, similar to Java Mockito 2.x, do not accept `None` (null) values by default. Passing `None` to `any(SomeClass)` might fail if the mock expects a non-null object.
  Fix: If `None` is an expected argument, explicitly match it with `None` or consider using more specific argument matchers if applicable. For Java Mockito, `Mockito.<Type>any()` is used, but Python Mockito's behavior is often managed by the specific matchers or explicit `None`.

Install

• pip install mockito Install stable version

Imports

• when

  from mockito import when

• mock

  from mockito import mock

• unstub

  from mockito import unstub

• verify

  from mockito import verify

• expect

  from mockito import expect

• InOrder

  from mockito import InOrder

• patch_attr

  from mockito import patch_attr

• patch_dict

  from mockito import patch_dict

• * (wildcard import)

  from mockito import when, mock, unstub

  Wildcard imports are generally discouraged and specifically for Mockito v1.0.0 and later, the `Mock` (uppercase) class is no longer exported, which can lead to unexpected errors if relied upon.
• Mock (uppercase)

  from mockito import mock

  The uppercase `Mock` class has been deprecated and is for internal use only since v1.0.0. Use the lowercase `mock` function for creating mock objects.

Quickstart

This quickstart demonstrates how to use Mockito to stub module-level functions (like `os.path.exists`) and third-party library calls (like `requests.get`). It covers returning specific values, raising exceptions, and verifying interactions, always remembering to call `unstub()` to clean up mocks after each test.

import os
from mockito import when, mock, unstub, verify

class MyService:
    def get_file_content(self, path):
        if os.path.exists(path):
            # In a real scenario, this would read from the file system
            return f"Content of {path}"
        return None

    def fetch_data_from_api(self, url):
        # Imagine 'requests' is a dependency that makes HTTP calls
        import requests # Imported locally for example, usually at top
        try:
            response = requests.get(url)
            response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
            return response.text
        except Exception:
            return "Error fetching data"

# --- Test MyService with Mockito ---

# Scenario 1: Mocking a module function (os.path.exists)
def test_get_file_content_exists():
    service = MyService()
    when(os.path).exists('/foo').thenReturn(True)
    content = service.get_file_content('/foo')
    assert content == "Content of /foo"
    verify(os.path).exists('/foo')
    unstub()

def test_get_file_content_not_exists():
    service = MyService()
    when(os.path).exists('/bar').thenReturn(False)
    content = service.get_file_content('/bar')
    assert content is None
    verify(os.path).exists('/bar')
    unstub()

# Scenario 2: Mocking a third-party library (requests)
def test_fetch_data_success():
    service = MyService()
    import requests # Ensure requests is available or mocked correctly
    
    # Create a mock response object
    mock_response = mock({'status_code': 200, 'text': '{"data": "mocked data"}'})
    when(requests).get('http://example.com/api').thenReturn(mock_response)
    
    data = service.fetch_data_from_api('http://example.com/api')
    assert data == '{"data": "mocked data"}'
    verify(requests).get('http://example.com/api')
    unstub()

def test_fetch_data_failure():
    service = MyService()
    import requests
    
    # Mock requests.get to raise an exception
    when(requests).get('http://bad.com/api').thenRaise(requests.exceptions.ConnectionError)
    
    data = service.fetch_data_from_api('http://bad.com/api')
    assert data == "Error fetching data"
    verify(requests).get('http://bad.com/api')
    unstub()

# Run tests (example usage)
print("Running Mockito quickstart tests...")
test_get_file_content_exists()
test_get_file_content_not_exists()
test_fetch_data_success()
test_fetch_data_failure()
print("All Mockito quickstart tests passed!")