robotframework-mock 0.7.1__tar.gz → 0.9.0__tar.gz

{robotframework_mock-0.7.1/src/robotframework_mock.egg-info → robotframework_mock-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robotframework-mock
-Version: 0.7.1
+Version: 0.9.0
 Summary: A Robot Framework library for mocking keywords in unit tests
 Home-page: https://github.com/olesz/robotframework-mock
 Author: Lajos Olah
@@ -62,6 +62,7 @@ pip install -r requirements-dev.txt
 - Support for keywords with custom names via @keyword decorator
 - Verify keyword calls and call counts
 - Inspect and verify the arguments a mocked keyword was called with
+- Inspect the order in which mocked keywords were called
 - Measure resource-file keyword coverage with configurable thresholds
 - Simple API with three main keywords
 
@@ -434,6 +435,32 @@ Return how many times a mocked keyword was called.
 ${count}=    MockDB.Get Keyword Call Count    execute_sql
 ```
 
+### Get Keyword Call Order
+
+Return the mocked keywords in the order they were called, as a list of names.
+
+Covers keywords mocked through the same library instance. This is what
+establishes ordering *between* different mocks — an individual mock's call
+history cannot show how it interleaved with its siblings.
+
+A keyword called more than once appears once per call. Keywords that were mocked
+but never called do not appear, and calls made on a keyword's return value are
+not included.
+
+**Example:**
+```robot
+MockRes.Mock Keyword    Init Client    return_value=alias
+MockRes.Mock Keyword    Run Query      return_value=${rows}
+
+Fetch Data
+
+${order}=    MockRes.Get Keyword Call Order
+Should Be Equal    ${order}    ${{ ['Init Client', 'Run Query'] }}
+```
+
+Use this instead of wiring a `side_effect` that appends to a list, which is the
+only way to observe ordering otherwise.
+
 ## How It Works
 
 ### MockLibrary
@@ -444,9 +471,39 @@ MockLibrary dynamically replaces keyword implementations:
 3. Stores original methods before mocking
 4. Replaces methods with mock implementations using Python's unittest.mock.Mock
 5. Returns mocked values or executes side effects
-6. Tracks call counts for verification
+6. Tracks call counts and call arguments for verification
 7. Raises AttributeError if attempting to mock a non-existent keyword
 
+#### Mocks are installed on the library class
+
+Step 4 replaces the method on the target library's **class**, not on the
+instance. Two consequences are worth knowing, because neither is reported as an
+error:
+
+**A mock stays active until `Reset Mocks`, across tests and suites.** The mock
+is not scoped to the test that created it. A test that mocks a keyword and
+leaves without resetting hands the mock to everything that follows. Reset in a
+teardown rather than at the end of a test body, so the mock is also removed when
+the test fails midway.
+
+**Two `MockLibrary` instances wrapping the same library share one mock.** Last
+registration wins, and resetting *either* instance restores the real method:
+
+```robot
+Library    MockLibrary    DateTime    WITH NAME    MockA
+Library    MockLibrary    DateTime    WITH NAME    MockB
+...
+MockA.Mock Keyword    Convert Time    return_value=from-a
+MockB.Mock Keyword    Convert Time    return_value=from-b
+${result}=    Convert Time    12:00:00      # from-b: MockA's mock was overwritten
+MockB.Reset Mocks
+${result}=    Convert Time    12:00:00      # the real keyword, although MockA never reset
+```
+
+Use a single alias per library, and separate aliases only for *different*
+libraries. `MockResource` is not affected: it keys mocks per resource file, so
+instances for different resources are independent.
+
 ### MockResource
 
 MockResource patches Robot Framework's keyword execution:

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0}/README.md

@@ -38,6 +38,7 @@ pip install -r requirements-dev.txt
 - Support for keywords with custom names via @keyword decorator
 - Verify keyword calls and call counts
 - Inspect and verify the arguments a mocked keyword was called with
+- Inspect the order in which mocked keywords were called
 - Measure resource-file keyword coverage with configurable thresholds
 - Simple API with three main keywords
 
@@ -410,6 +411,32 @@ Return how many times a mocked keyword was called.
 ${count}=    MockDB.Get Keyword Call Count    execute_sql
 ```
 
+### Get Keyword Call Order
+
+Return the mocked keywords in the order they were called, as a list of names.
+
+Covers keywords mocked through the same library instance. This is what
+establishes ordering *between* different mocks — an individual mock's call
+history cannot show how it interleaved with its siblings.
+
+A keyword called more than once appears once per call. Keywords that were mocked
+but never called do not appear, and calls made on a keyword's return value are
+not included.
+
+**Example:**
+```robot
+MockRes.Mock Keyword    Init Client    return_value=alias
+MockRes.Mock Keyword    Run Query      return_value=${rows}
+
+Fetch Data
+
+${order}=    MockRes.Get Keyword Call Order
+Should Be Equal    ${order}    ${{ ['Init Client', 'Run Query'] }}
+```
+
+Use this instead of wiring a `side_effect` that appends to a list, which is the
+only way to observe ordering otherwise.
+
 ## How It Works
 
 ### MockLibrary
@@ -420,9 +447,39 @@ MockLibrary dynamically replaces keyword implementations:
 3. Stores original methods before mocking
 4. Replaces methods with mock implementations using Python's unittest.mock.Mock
 5. Returns mocked values or executes side effects
-6. Tracks call counts for verification
+6. Tracks call counts and call arguments for verification
 7. Raises AttributeError if attempting to mock a non-existent keyword
 
+#### Mocks are installed on the library class
+
+Step 4 replaces the method on the target library's **class**, not on the
+instance. Two consequences are worth knowing, because neither is reported as an
+error:
+
+**A mock stays active until `Reset Mocks`, across tests and suites.** The mock
+is not scoped to the test that created it. A test that mocks a keyword and
+leaves without resetting hands the mock to everything that follows. Reset in a
+teardown rather than at the end of a test body, so the mock is also removed when
+the test fails midway.
+
+**Two `MockLibrary` instances wrapping the same library share one mock.** Last
+registration wins, and resetting *either* instance restores the real method:
+
+```robot
+Library    MockLibrary    DateTime    WITH NAME    MockA
+Library    MockLibrary    DateTime    WITH NAME    MockB
+...
+MockA.Mock Keyword    Convert Time    return_value=from-a
+MockB.Mock Keyword    Convert Time    return_value=from-b
+${result}=    Convert Time    12:00:00      # from-b: MockA's mock was overwritten
+MockB.Reset Mocks
+${result}=    Convert Time    12:00:00      # the real keyword, although MockA never reset
+```
+
+Use a single alias per library, and separate aliases only for *different*
+libraries. `MockResource` is not affected: it keys mocks per resource file, so
+instances for different resources are independent.
+
 ### MockResource
 
 MockResource patches Robot Framework's keyword execution:

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = robotframework-mock
-version = 0.7.1
+version = 0.9.0
 author = Lajos Olah
 author_email = lajos.olah.jr@gmail.com
 description = A Robot Framework library for mocking keywords in unit tests

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0}/src/MockCoverage/__init__.py

@@ -60,6 +60,8 @@ except ModuleNotFoundError:  # pragma: no cover - exercised only on <3.11
 from robot.api import get_resource_model
 from robot.api.parsing import ModelVisitor
 
+from _mock_core import is_keyword_mocked
+
 
 DEFAULT_CONFIG_PATH = "mock-coverage.toml"
 DEFAULT_OUTPUT_PATH = "coverage.json"
@@ -571,6 +573,10 @@ class ExecutionTracker:
     def record(self, owner: Optional[str], name: str) -> None:
         """Record a keyword execution if it belongs to a measured resource.
 
+        Keywords whose body is currently replaced by a ``MockResource`` mock are
+        ignored: the real body never ran, so counting them would credit the
+        resource with coverage it did not earn.
+
         Args:
             owner: Robot's owner name for the keyword (resource base name).
             name: The executed keyword's name.
@@ -579,7 +585,7 @@ class ExecutionTracker:
         if owner not in self._owner_names:
             return
         source = self._resolve_source(owner, name)
-        if source:
+        if source and not is_keyword_mocked(source, name):
             self._executed.setdefault(source, set()).add(name)
 
     def _resolve_source(self, owner: str, name: str) -> Optional[str]:

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0}/src/MockLibrary/__init__.py

@@ -160,6 +160,7 @@ class MockLibrary(CallInspectionMixin):
         # Create Mock object with specified behavior
         mock = Mock(return_value=return_value, side_effect=side_effect)
         self._mocks[method_name] = mock
+        self._track_call_order(keyword_name, mock)
 
         # Replace the method on the class or instance
         try:
@@ -194,6 +195,7 @@ class MockLibrary(CallInspectionMixin):
 
         # Clear all tracking dictionaries
         self._mocks.clear()
+        self._reset_call_order()
         self._original_methods.clear()
 
     @keyword

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0}/src/MockResource/__init__.py

@@ -1,5 +1,6 @@
 """Mock resource for Robot Framework keyword mocking in unit tests."""
 # pylint: disable=invalid-name
+import weakref
 from typing import Any, Callable
 from unittest.mock import Mock
 
@@ -9,7 +10,12 @@ from robot.running import Return
 from robot.running.namespace import Namespace
 from robot.utils import split_from_equals
 
-from _mock_core import CallInspectionMixin
+from _mock_core import (
+    CallInspectionMixin,
+    normalize_keyword_name,
+    register_mocked_keyword,
+    unregister_mocked_keyword,
+)
 
 # Robot resolves the values of a RETURN statement as variable expressions, so a
 # mocked return value cannot be embedded in one directly - anything that is not
@@ -18,6 +24,74 @@ from _mock_core import CallInspectionMixin
 # object (a query result set, a parsed JSON body, a list of pods...).
 RETURN_VARIABLE = '${__mock_resource_return__}'
 
+# Namespace.get_runner is patched once per process rather than once per
+# MockResource instance. Patching per instance chained a new wrapper around the
+# previous one for every library import, and nothing ever restored them, so
+# every keyword lookup in the run paid for each import. The single wrapper
+# consults the live instances below and is inert when none of them has mocks.
+_INSTANCES = []
+_ORIGINAL_GET_RUNNER = None
+
+
+def _live_instances():
+    """Return the MockResource instances that are still alive.
+
+    Instances are held weakly so a library instance going out of scope does not
+    keep its mocks alive, and dead references are pruned on access.
+
+    Returns:
+        The live instances, in the order they were created.
+    """
+    live = []
+    for reference in list(_INSTANCES):
+        instance = reference()
+        if instance is None:
+            _INSTANCES.remove(reference)
+        else:
+            live.append(instance)
+    return live
+
+
+def _install_shared_patch():
+    """Patch ``Namespace.get_runner`` once, routing to all live instances."""
+    global _ORIGINAL_GET_RUNNER  # pylint: disable=global-statement
+    if _ORIGINAL_GET_RUNNER is not None:
+        return
+    _ORIGINAL_GET_RUNNER = Namespace.get_runner
+    original_get_runner = _ORIGINAL_GET_RUNNER
+
+    def patched_get_runner(self, keyword_name, recommend_on_failure):
+        keyword_runner = original_get_runner(self, keyword_name, recommend_on_failure)
+        resource_file = getattr(keyword_runner.keyword, "source", None)
+
+        for instance in _live_instances():
+            if instance.source not in str(resource_file):
+                continue
+            mock = instance.mocks.get(normalize_keyword_name(keyword_name))
+            if not mock:
+                continue
+            original_run = keyword_runner.run
+
+            def patched_run(data, result, context, run,
+                            _mock=mock, _original_run=original_run):
+                args, kwargs = _resolve_arguments(
+                    keyword_runner.keyword, data, context
+                )
+                mock_result = _mock(*args, **kwargs)
+                # Test scope, so the value is visible to the keyword's own
+                # body even when the mocked keyword is called from inside
+                # another keyword rather than directly from the test.
+                context.variables.set_test(RETURN_VARIABLE, mock_result)
+                keyword_runner.keyword.body._items = [Return(values=[RETURN_VARIABLE])]  # pylint: disable=protected-access
+                return _original_run(data, result, context, run)
+
+            keyword_runner.run = patched_run
+            break
+
+        return keyword_runner
+
+    Namespace.get_runner = patched_get_runner
+
 
 def _resolve_arguments(keyword_obj, data, context):
     """Split a keyword call's raw arguments into resolved args and kwargs.
@@ -72,44 +146,37 @@ class MockResource(CallInspectionMixin):
 
     def __init__(self, source):
         self._source = source
-        self._original_get_runner = Namespace.get_runner
         self._original_items = {}
         self._original_setups = {}
         self._original_teardowns = {}
+        self._mocked_sources = {}
         self._mocks = {}
-        self._install_patch()
-
-    def _install_patch(self):
-        original_get_runner = self._original_get_runner
-        active_mocks = self._mocks
-        source = self._source
-
-        def patched_get_runner(self, keyword_name, recommend_on_failure):
-            keyword_runner = original_get_runner(self, keyword_name, recommend_on_failure)
-            resource_file = getattr(keyword_runner.keyword, "source", None)
-
-            if source not in str(resource_file):
-                return keyword_runner
-
-            mock = active_mocks.get(keyword_name)
-            if mock:
-                original_run = keyword_runner.run
-                def patched_run(data, result, context, run):
-                    args, kwargs = _resolve_arguments(
-                        keyword_runner.keyword, data, context
-                    )
-                    mock_result = mock(*args, **kwargs)
-                    # Test scope, so the value is visible to the keyword's own
-                    # body even when the mocked keyword is called from inside
-                    # another keyword rather than directly from the test.
-                    context.variables.set_test(RETURN_VARIABLE, mock_result)
-                    keyword_runner.keyword.body._items = [Return(values=[RETURN_VARIABLE])]  # pylint: disable=protected-access
-                    return original_run(data, result, context, run)
-                keyword_runner.run = patched_run
-
-            return keyword_runner
-
-        Namespace.get_runner = patched_get_runner
+        _INSTANCES.append(weakref.ref(self))
+        _install_shared_patch()
+
+    @property
+    def source(self):
+        """Return the resource file this instance mocks keywords from."""
+        return self._source
+
+    @property
+    def mocks(self):
+        """Return the active mocks, keyed by normalized keyword name."""
+        return self._mocks
+
+    def _mock_key(self, keyword_name: str) -> str:
+        """Return the ``self._mocks`` key for *keyword_name*.
+
+        Mocks are keyed the way Robot Framework matches keyword names, so
+        inspecting a call works whatever case or spacing the test used.
+
+        Args:
+            keyword_name: Keyword name as written in the test.
+
+        Returns:
+            The normalized name used as the mock key.
+        """
+        return normalize_keyword_name(keyword_name)
 
     @keyword
     def mock_keyword(
@@ -155,6 +222,7 @@ class MockResource(CallInspectionMixin):
             )
 
         self._original_items[keyword_name] = keyword_runner.keyword.body._items  # pylint: disable=protected-access
+        self._mocked_sources[keyword_name] = resource_file
         if skip_setup:
             self._original_setups[keyword_name] = keyword_runner.keyword.setup
             keyword_runner.keyword.setup = None
@@ -162,7 +230,11 @@ class MockResource(CallInspectionMixin):
             self._original_teardowns[keyword_name] = keyword_runner.keyword.teardown
             keyword_runner.keyword.teardown = None
         mock = Mock(return_value=return_value, side_effect=side_effect)
-        self._mocks[keyword_name] = mock
+        self._mocks[normalize_keyword_name(keyword_name)] = mock
+        self._track_call_order(keyword_name, mock)
+        # Tell MockCoverage this keyword's body no longer runs, so it is not
+        # credited with coverage it did not earn.
+        register_mocked_keyword(resource_file, keyword_name)
         return mock
 
     @keyword
@@ -176,6 +248,9 @@ class MockResource(CallInspectionMixin):
             | MockRes.Reset Mocks |
         """
         self._mocks.clear()
+        self._reset_call_order()
+        for keyword_name, source in self._mocked_sources.items():
+            unregister_mocked_keyword(source, keyword_name)
         for keyword_name, items in self._original_items.items():
             keyword_runner = BuiltIn()._namespace.get_runner(keyword_name, True)  # pylint: disable=protected-access
             keyword_runner.keyword.body._items = items  # pylint: disable=protected-access
@@ -188,6 +263,7 @@ class MockResource(CallInspectionMixin):
         self._original_items.clear()
         self._original_setups.clear()
         self._original_teardowns.clear()
+        self._mocked_sources.clear()
 
     @keyword
     def verify_keyword_called(self, keyword_name: str, times: int = None):
@@ -203,9 +279,6 @@ class MockResource(CallInspectionMixin):
         Example:
             | MockDB.Verify Keyword Called | Execute Sql | times=1 |
         """
-        if keyword_name not in self._mocks:
-            raise AssertionError(f"Keyword '{keyword_name}' was not mocked")
-
-        mock = self._mocks[keyword_name]
+        mock = self._get_mock(keyword_name)
         if times is not None and mock.call_count != times:
             raise AssertionError(f"Expected {times} calls, got {mock.call_count}")

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0}/src/_mock_core/__init__.py

@@ -8,10 +8,75 @@ implemented once here and mixed into both libraries, so the two cannot drift
 apart.
 """
 # pylint: disable=invalid-name
+import os
 from typing import Any, Dict, List
-from unittest.mock import call
+from unittest.mock import call, Mock
 
 from robot.api.deco import keyword
+from robot.utils import normalize
+
+
+def normalize_keyword_name(name) -> str:
+    """Return a keyword name in the form Robot Framework matches on.
+
+    Robot treats keyword names as case-, space- and underscore-insensitive, so
+    mocks have to be keyed the same way. Without this, mocking ``Fetch Rows``
+    and calling ``fetch rows`` would silently run the real keyword.
+
+    Args:
+        name: Keyword name as written anywhere.
+
+    Returns:
+        The canonical comparison key for that name.
+    """
+    return normalize(str(name), ignore='_')
+
+
+# Keywords whose body is currently replaced by a mock, as
+# ``(absolute source path, normalized keyword name)`` pairs.
+#
+# MockCoverage consults this so a keyword that was only ever mocked is not
+# counted as covered: its real body never ran, and counting it would inflate the
+# reported coverage of the resource it lives in.
+MOCKED_KEYWORDS = set()
+
+
+def mocked_keyword_key(source, keyword_name) -> tuple:
+    """Build the registry key for a keyword in a resource file.
+
+    Args:
+        source: Path of the resource file defining the keyword.
+        keyword_name: Keyword name as written.
+
+    Returns:
+        The ``(source key, normalized name)`` tuple used by the registry.
+    """
+    return (os.path.normcase(os.path.abspath(str(source))),
+            normalize_keyword_name(keyword_name))
+
+
+def register_mocked_keyword(source, keyword_name) -> None:
+    """Record that a keyword's body is replaced by a mock."""
+    MOCKED_KEYWORDS.add(mocked_keyword_key(source, keyword_name))
+
+
+def unregister_mocked_keyword(source, keyword_name) -> None:
+    """Record that a keyword's body is restored."""
+    MOCKED_KEYWORDS.discard(mocked_keyword_key(source, keyword_name))
+
+
+def is_keyword_mocked(source_key: str, keyword_name) -> bool:
+    """Return whether a keyword is currently mocked.
+
+    Args:
+        source_key: Source path already normalised with ``os.path.normcase`` and
+            ``os.path.abspath``, as :func:`mocked_keyword_key` produces.
+        keyword_name: Keyword name as reported at execution time.
+
+    Returns:
+        ``True`` when the keyword's body is currently a mock.
+    """
+    return (source_key, normalize_keyword_name(keyword_name)) in MOCKED_KEYWORDS
 
 
 class CallInspectionMixin:
@@ -22,10 +87,37 @@ class CallInspectionMixin:
     - ``self._mocks``: mapping of mock key -> :class:`unittest.mock.Mock`
     - ``self._mock_key(keyword_name)``: the ``self._mocks`` key for a keyword
       name, in case the library does not key by the name as written
+    - ``self._call_manager`` / ``self._display_names``: created on first use by
+      :meth:`_track_call_order`, which the host calls for each new mock
     """
 
     _mocks: Dict[str, Any]
 
+    def _track_call_order(self, keyword_name: str, mock) -> None:
+        """Attach a mock so its calls are ordered against its siblings.
+
+        ``unittest.mock`` records calls to attached children on the parent in
+        invocation order, which is the only way to establish the relative order
+        of calls to *different* mocks - each mock's own ``call_args_list`` knows
+        nothing about the others.
+
+        Args:
+            keyword_name: Keyword name as written when mocking.
+            mock: The mock backing that keyword.
+        """
+        if not hasattr(self, '_call_manager'):
+            self._call_manager = Mock()
+            self._display_names = {}
+        key = normalize_keyword_name(keyword_name)
+        self._display_names[key] = keyword_name
+        self._call_manager.attach_mock(mock, key)
+
+    def _reset_call_order(self) -> None:
+        """Forget the recorded call order, called when mocks are reset."""
+        if hasattr(self, '_call_manager'):
+            del self._call_manager
+            del self._display_names
+
     def _mock_key(self, keyword_name: str) -> str:
         """Return the ``self._mocks`` key for *keyword_name*.
 
@@ -79,6 +171,40 @@ class CallInspectionMixin:
             )
         return calls[index]
 
+    @keyword
+    def get_keyword_call_order(self) -> List[str]:
+        """Return the mocked keywords in the order they were called.
+
+        Covers keywords mocked through *this* library instance, which is what
+        establishes ordering between different mocks - an individual mock's
+        call history cannot show how it interleaved with its siblings.
+
+        A keyword called more than once appears once per call. Keywords mocked
+        but never called do not appear at all.
+
+        Returns:
+            Keyword names, as written when mocking, in invocation order.
+
+        Example:
+            | MockRes.Mock Keyword | Init Client | return_value=alias |
+            | MockRes.Mock Keyword | Run Query | return_value=${rows} |
+            | Fetch Data |
+            | ${order}= | MockRes.Get Keyword Call Order |
+            | Should Be Equal | ${order} | ${{ ['Init Client', 'Run Query'] }} |
+        """
+        if not hasattr(self, '_call_manager'):
+            return []
+        order = []
+        for recorded in self._call_manager.mock_calls:
+            name = recorded[0]
+            # Skip nested calls such as "run_query().json()", which belong to
+            # the returned object rather than to a mocked keyword.
+            if not name or '.' in name:
+                continue
+            if name in self._display_names:
+                order.append(self._display_names[name])
+        return order
+
     @keyword
     def get_keyword_call_count(self, keyword_name: str) -> int:
         """Return how many times a mocked keyword was called.

{robotframework_mock-0.7.1 → robotframework_mock-0.9.0/src/robotframework_mock.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robotframework-mock
-Version: 0.7.1
+Version: 0.9.0
 Summary: A Robot Framework library for mocking keywords in unit tests
 Home-page: https://github.com/olesz/robotframework-mock
 Author: Lajos Olah
@@ -62,6 +62,7 @@ pip install -r requirements-dev.txt
 - Support for keywords with custom names via @keyword decorator
 - Verify keyword calls and call counts
 - Inspect and verify the arguments a mocked keyword was called with
+- Inspect the order in which mocked keywords were called
 - Measure resource-file keyword coverage with configurable thresholds
 - Simple API with three main keywords
 
@@ -434,6 +435,32 @@ Return how many times a mocked keyword was called.
 ${count}=    MockDB.Get Keyword Call Count    execute_sql
 ```
 
+### Get Keyword Call Order
+
+Return the mocked keywords in the order they were called, as a list of names.
+
+Covers keywords mocked through the same library instance. This is what
+establishes ordering *between* different mocks — an individual mock's call
+history cannot show how it interleaved with its siblings.
+
+A keyword called more than once appears once per call. Keywords that were mocked
+but never called do not appear, and calls made on a keyword's return value are
+not included.
+
+**Example:**
+```robot
+MockRes.Mock Keyword    Init Client    return_value=alias
+MockRes.Mock Keyword    Run Query      return_value=${rows}
+
+Fetch Data
+
+${order}=    MockRes.Get Keyword Call Order
+Should Be Equal    ${order}    ${{ ['Init Client', 'Run Query'] }}
+```
+
+Use this instead of wiring a `side_effect` that appends to a list, which is the
+only way to observe ordering otherwise.
+
 ## How It Works
 
 ### MockLibrary
@@ -444,9 +471,39 @@ MockLibrary dynamically replaces keyword implementations:
 3. Stores original methods before mocking
 4. Replaces methods with mock implementations using Python's unittest.mock.Mock
 5. Returns mocked values or executes side effects
-6. Tracks call counts for verification
+6. Tracks call counts and call arguments for verification
 7. Raises AttributeError if attempting to mock a non-existent keyword
 
+#### Mocks are installed on the library class
+
+Step 4 replaces the method on the target library's **class**, not on the
+instance. Two consequences are worth knowing, because neither is reported as an
+error:
+
+**A mock stays active until `Reset Mocks`, across tests and suites.** The mock
+is not scoped to the test that created it. A test that mocks a keyword and
+leaves without resetting hands the mock to everything that follows. Reset in a
+teardown rather than at the end of a test body, so the mock is also removed when
+the test fails midway.
+
+**Two `MockLibrary` instances wrapping the same library share one mock.** Last
+registration wins, and resetting *either* instance restores the real method:
+
+```robot
+Library    MockLibrary    DateTime    WITH NAME    MockA
+Library    MockLibrary    DateTime    WITH NAME    MockB
+...
+MockA.Mock Keyword    Convert Time    return_value=from-a
+MockB.Mock Keyword    Convert Time    return_value=from-b
+${result}=    Convert Time    12:00:00      # from-b: MockA's mock was overwritten
+MockB.Reset Mocks
+${result}=    Convert Time    12:00:00      # the real keyword, although MockA never reset
+```
+
+Use a single alias per library, and separate aliases only for *different*
+libraries. `MockResource` is not affected: it keys mocks per resource file, so
+instances for different resources are independent.
+
 ### MockResource
 
 MockResource patches Robot Framework's keyword execution: