From 8580952f1774e51f425900e9fb6241740e747647 Mon Sep 17 00:00:00 2001
From: Suraj Pillai <85.suraj@gmail.com>
Date: Sat, 4 Nov 2023 09:26:13 -0400
Subject: [PATCH] Update Readme

---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index d82c3f5..9abc372 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,35 @@ A universal mocking class for Apex, built using the [Apex Stub API](https://deve
   AccountDBService mockDBService = (AccountDBService)mockInstance.createStub();
   ```
 
+#### Sequential Mocks
+
+There might be instances where you may need the same method to mock different return values within the same test when
+testing utility methods or selector classes and such. You can specify different return values based on the call count
+in such cases
+
+- Basic example
+
+```java
+  mockInstance.when('getOneAccount').thenReturnUntil(3,mockAccountOne).thenReturn(mockAccountTwo);
+```
+
+Here, `mockAccountOne` is returned the first 3 times `getOneAccount` is called. All subsequent calls to `getOneAccount`
+will return `mockAccountTwo`
+
+- You can also pair it with param types or to mock exceptions
+
+```java
+  mockInstance.when('getOneAccount').withParamTypes(new List<Type>{Id.class})
+    .thenReturnUntil(1,mockAccountOne)
+    .thenThrowUntil(3,mockException)
+    .thenReturn(mockAccountTwo);
+```
+
+Refer to the [relevant unit tests](force-app/main/default/classes/example/AccountDomainTest.cls#L265) for further
+clarity
+
+**Note**: It is recommended that you end all setup method call chains with `thenReturn` or `thenThrow`
+
 #### Mutating arguments
 
 There might be instances where you need to modify the original arguments passed into the function. A typical example