From cddd65723c156de9bbf9dbe78a1931bc562eee05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Breu=C3=9F?= <vbreuss@gmail.com>
Date: Fri, 30 Jan 2026 18:57:04 +0100
Subject: [PATCH 1/2] docs: add documentation for `Mock.Wrap`

## Changes

- Added "Wrapping Existing Instances" subsection to README.md and Docs/pages/01-create-mocks.md
- Documented that Mock.Wrap forwards calls to real instances while tracking interactions
- Clarified that only interface types can be wrapped
- Added example showing wrapping, invocation, and verification
---
 Docs/pages/01-create-mocks.md | 16 ++++++++++++++++
 README.md                     | 23 +++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/Docs/pages/01-create-mocks.md b/Docs/pages/01-create-mocks.md
index 76a28abe..30f1778e 100644
--- a/Docs/pages/01-create-mocks.md
+++ b/Docs/pages/01-create-mocks.md
@@ -72,3 +72,19 @@ var sut2 = factory.Create<ILemonadeDispenser>();
 
 Using a factory allows you to create multiple mocks with identical, centrally configured behavior. This is especially
 useful when you need consistent mock setups across multiple tests or for different types.
+
+## Wrapping Existing Instances
+
+You can wrap an existing instance with mock tracking using `Mock.Wrap<T>()`. This allows you to track interactions with
+a real object:
+
+```csharp
+var realDispenser = new ChocolateDispenser();
+var wrappedDispenser = Mock.Wrap<IChocolateDispenser>(realDispenser);
+
+// Calls are forwarded to the real instance
+wrappedDispenser.Dispense("Dark", 5);
+
+// But you can still verify interactions
+wrappedDispenser.VerifyMock.Invoked.Dispense(It.Is("Dark"), It.Is(5)).Once();
+```
diff --git a/README.md b/README.md
index 183d0a8e..e8d60b1d 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,29 @@ var sut2 = factory.Create<ILemonadeDispenser>();
 Using a factory allows you to create multiple mocks with identical, centrally configured behavior. This is especially
 useful when you need consistent mock setups across multiple tests or for different types.
 
+## Wrapping Existing Instances
+
+You can wrap an existing instance with mock tracking using `Mock.Wrap<T>()`. This allows you to track interactions with
+a real object:
+
+```csharp
+var realDispenser = new ChocolateDispenser();
+var wrappedDispenser = Mock.Wrap<IChocolateDispenser>(realDispenser);
+
+// Calls are forwarded to the real instance
+wrappedDispenser.Dispense("Dark", 5);
+
+// But you can still verify interactions
+wrappedDispenser.VerifyMock.Invoked.Dispense(It.Is("Dark"), It.Is(5)).Once();
+```
+
+**Notes:**
+
+- Only interface types can be wrapped with `Mock.Wrap<T>()`.
+- All calls are forwarded to the wrapped instance.
+- You can still set up custom behavior that overrides the wrapped instance's behavior.
+- Verification works the same as with regular mocks.
+
 ## Setup
 
 Set up return values or behaviors for methods, properties, and indexers on your mock. Control how the mock responds to

From 8d80d28699a0578fad760f534fabd1070fb773b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Valentin=20Breu=C3=9F?= <vbreuss@gmail.com>
Date: Fri, 30 Jan 2026 18:58:54 +0100
Subject: [PATCH 2/2] Fix review issue

---
 Docs/pages/01-create-mocks.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Docs/pages/01-create-mocks.md b/Docs/pages/01-create-mocks.md
index 30f1778e..ef083d7e 100644
--- a/Docs/pages/01-create-mocks.md
+++ b/Docs/pages/01-create-mocks.md
@@ -88,3 +88,10 @@ wrappedDispenser.Dispense("Dark", 5);
 // But you can still verify interactions
 wrappedDispenser.VerifyMock.Invoked.Dispense(It.Is("Dark"), It.Is(5)).Once();
 ```
+
+**Notes:**
+
+- Only interface types can be wrapped with `Mock.Wrap<T>()`.
+- All calls are forwarded to the wrapped instance.
+- You can still set up custom behavior that overrides the wrapped instance's behavior.
+- Verification works the same as with regular mocks.