MockPlugin

MockPlugin

MockPlugin(verifier)

Bases: BasePlugin

Core mock plugin: intercepts method calls on named proxy objects.

Source code in src/bigfoot/_mock_plugin.py

def __init__(self, verifier: "StrictVerifier") -> None:
    super().__init__(verifier)
    self._proxies: dict[str, MockProxy] = {}

get_or_create_proxy

get_or_create_proxy(name, wraps=None)

Return an existing MockProxy for name, or create a new one.

If wraps is provided and a proxy already exists, update its wraps attribute (e.g., spy() called after mock()). If no proxy exists, create a new one with wraps set.

Source code in src/bigfoot/_mock_plugin.py

def get_or_create_proxy(self, name: str, wraps: object = None) -> MockProxy:
    """Return an existing MockProxy for name, or create a new one.

    If wraps is provided and a proxy already exists, update its wraps
    attribute (e.g., spy() called after mock()). If no proxy exists,
    create a new one with wraps set.
    """
    if name not in self._proxies:
        self._proxies[name] = MockProxy(name=name, plugin=self, wraps=wraps)
    elif wraps is not None:
        # Allow updating wraps on a pre-existing proxy (e.g., spy() called after mock())
        object.__setattr__(self._proxies[name], "_wraps", wraps)
    return self._proxies[name]

activate

activate()

Reference-counted install. Increments _install_count under lock.

Source code in src/bigfoot/_mock_plugin.py

def activate(self) -> None:
    """Reference-counted install. Increments _install_count under lock."""
    with MockPlugin._install_lock:
        MockPlugin._install_count += 1

deactivate

deactivate()

Reference-counted uninstall. Decrements _install_count, floored at 0.

Source code in src/bigfoot/_mock_plugin.py

def deactivate(self) -> None:
    """Reference-counted uninstall. Decrements _install_count, floored at 0."""
    with MockPlugin._install_lock:
        MockPlugin._install_count = max(0, MockPlugin._install_count - 1)

matches

matches(interaction, expected)

Return True if all expected fields match the interaction's details.

Source code in src/bigfoot/_mock_plugin.py

def matches(self, interaction: Interaction, expected: dict[str, Any]) -> bool:
    """Return True if all expected fields match the interaction's details."""
    try:
        for key, expected_val in expected.items():
            actual_val = interaction.details.get(key)
            if expected_val != actual_val:
                return False
        return True
    except Exception:
        return False

format_interaction

format_interaction(interaction)

One-line description: '[MockPlugin] MockName.method_name'.

Source code in src/bigfoot/_mock_plugin.py

def format_interaction(self, interaction: Interaction) -> str:
    """One-line description: '[MockPlugin] MockName.method_name'."""
    # source_id is "mock:MockName.method_name"
    readable = interaction.source_id.replace("mock:", "[MockPlugin] ", 1)
    return readable

format_mock_hint

format_mock_hint(interaction)

Copy-pasteable code to configure a mock for this interaction.

Source code in src/bigfoot/_mock_plugin.py

def format_mock_hint(self, interaction: Interaction) -> str:
    """Copy-pasteable code to configure a mock for this interaction."""
    mock_name = interaction.details.get("mock_name", "?")
    method_name = interaction.details.get("method_name", "?")
    return f'verifier.mock("{mock_name}").{method_name}.returns(<value>)'

format_unmocked_hint

format_unmocked_hint(source_id, args, kwargs)

Copy-pasteable code snippet for mocking a call that had no side effect.

Source code in src/bigfoot/_mock_plugin.py

def format_unmocked_hint(
    self,
    source_id: str,
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
) -> str:
    """Copy-pasteable code snippet for mocking a call that had no side effect."""
    # source_id = "mock:Name.method"
    without_prefix = source_id.replace("mock:", "", 1)
    parts = without_prefix.split(".", 1)
    mock_name = parts[0] if len(parts) > 0 else "?"
    method_name = parts[1] if len(parts) > 1 else "?"
    return (
        f"Unexpected call to {mock_name}.{method_name}\n\n"
        f"  Called with: args={args!r}, kwargs={kwargs!r}\n\n"
        f"  To mock this interaction, add before your sandbox:\n"
        f'    verifier.mock("{mock_name}").{method_name}.returns(<value>)\n\n'
        f"  Or to mark it optional:\n"
        f'    verifier.mock("{mock_name}").{method_name}.required(False).returns(<value>)'
    )

format_assert_hint

format_assert_hint(interaction)

Copy-pasteable code to assert this interaction.

Source code in src/bigfoot/_mock_plugin.py

def format_assert_hint(self, interaction: Interaction) -> str:
    """Copy-pasteable code to assert this interaction."""
    mock_name = interaction.details.get("mock_name", "?")
    method_name = interaction.details.get("method_name", "?")
    args = interaction.details.get("args", ())
    kwargs = interaction.details.get("kwargs", {})
    return (
        f'verifier.mock("{mock_name}").{method_name}.assert_call(\n'
        f"    args={args!r},\n"
        f"    kwargs={kwargs!r},\n"
        f")"
    )

assertable_fields

assertable_fields(interaction)

Return the field names required in **expected when asserting a mock interaction.

Source code in src/bigfoot/_mock_plugin.py

def assertable_fields(self, interaction: Interaction) -> frozenset[str]:
    """Return the field names required in **expected when asserting a mock interaction."""
    return frozenset({"args", "kwargs"})

get_unused_mocks

get_unused_mocks()

Return MockConfig objects that are required=True and still in the queue (never consumed).

Source code in src/bigfoot/_mock_plugin.py

def get_unused_mocks(self) -> list[MockConfig]:
    """Return MockConfig objects that are required=True and still in the queue (never
    consumed)."""
    unused: list[MockConfig] = []
    for proxy in self._proxies.values():
        methods = object.__getattribute__(proxy, "_methods")
        for method_proxy in methods.values():
            for config in method_proxy._config_queue:
                if config.required:
                    unused.append(config)
    return unused

format_unused_mock_hint

format_unused_mock_hint(mock_config)

Hint for an unused mock: show registration traceback and how to suppress.

Source code in src/bigfoot/_mock_plugin.py

def format_unused_mock_hint(self, mock_config: object) -> str:
    """Hint for an unused mock: show registration traceback and how to suppress."""
    assert isinstance(mock_config, MockConfig)
    return (
        f"mock:{mock_config.mock_name}.{mock_config.method_name}\n"
        f"    Mock registered at:\n"
        f"{mock_config.registration_traceback}\n"
        f"    Options:\n"
        f"      - Remove this mock if it's not needed\n"
        f'      - Mark it optional: verifier.mock("{mock_config.mock_name}")'
        f".{mock_config.method_name}.required(False).returns(...)"
    )