From 7fa06390fd6848b6dfb0efde30c2cb4616fc7c04 Mon Sep 17 00:00:00 2001
From: Chris Penny <chris.penny@gmail.com>
Date: Mon, 2 Oct 2023 09:27:22 +1300
Subject: [PATCH] Update documentation regarding unit testing with KFC

---
 README.md               |   5 ++
 docs/en/unit-testing.md | 103 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 108 insertions(+)
 create mode 100644 docs/en/unit-testing.md

diff --git a/README.md b/README.md
index 8dc1333..93b060a 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ preferred caching method (EG: partial caching).
     * [Queued jobs](#queued-jobs)
 * [Case Studies](docs/en/case-studies.md)
 * [Fluent support](docs/en/fluent.md)
+* [Unit testing](docs/en/unit-testing.md)
 * [License](license.md)
 * [Maintainers](#maintainers)
 * [Development and contribution](#development-and-contribution)
@@ -325,6 +326,10 @@ See: [Case studies](docs/en/case-studies.md)
 
 See: [Fluent support](docs/en/fluent.md)
 
+## Unit testing
+
+See: [Unit testing](docs/en/unit-testing.md)
+
 ## License
 
 See [License](license.md)
diff --git a/docs/en/unit-testing.md b/docs/en/unit-testing.md
new file mode 100644
index 0000000..dc4eb7e
--- /dev/null
+++ b/docs/en/unit-testing.md
@@ -0,0 +1,103 @@
+# Unit Testing
+
+- KFC includes a feature to make sure that it only updates the cache key for any unique record once per request. It
+  does this by keeping a local cache of what has been processed already.
+- One unit test case is considered to be "one request", which means that within a test case, KFC will only ever update
+  the cache key for a record once - even if you perform multiple changes and writes to that record.
+- A developer might want to create tests that check their cache key updates when they trigger a change on that record.
+
+Below is an example of a reasonable test that a developer might want to undertake. You would expect that the
+`LastEdited` and `getCacheKey()` values update with each `var_dump()`.
+
+```php
+class SiteConfigTest extends SapphireTest
+{
+
+    protected $usesDatabase = true;
+
+    public function testSiteConfigCacheKey(): void
+    {
+        $siteConfig = SiteConfig::current_site_config();
+        // Output intitial values
+        var_dump($siteConfig->LastEdited);
+        var_dump($siteConfig->getCacheKey());
+
+        // Sleep for a second to make sure our date changes
+        sleep(1);
+
+        // Make a change to SiteConfig
+        $siteConfig->Title = 'Updated Site Title 1';
+        $siteConfig->write();
+
+        // We would expect these values to change now
+        var_dump($siteConfig->LastEdited);
+        var_dump($siteConfig->getCacheKey());
+
+        // Sleep for a second to make sure our date changes
+        sleep(1);
+
+        // Make a change to SiteConfig
+        $siteConfig->Title = 'Updated Site Title 2';
+        $siteConfig->write();
+
+        // We would expect these values to change again now
+        var_dump($siteConfig->LastEdited);
+        var_dump($siteConfig->getCacheKey());
+    }
+
+}
+```
+
+**Actual:** `LastEdited` does update, but `getCacheKey()` does not.
+
+In order to get the expected outcome, developers need to add `ProcessedUpdatesService::singleton()->flush();` before
+they `write()` their record. This clears the local cache of processed records from KFC, and will mean that any new
+changes to your records will trigger their cache keys to be updated (even if they have done so previously in this
+request).
+
+EG:
+
+```php
+class SiteConfigTest extends SapphireTest
+{
+
+    protected $usesDatabase = true;
+
+    public function testSiteConfigCacheKey(): void
+    {
+        $siteConfig = SiteConfig::current_site_config();
+        // Output intitial values
+        var_dump($siteConfig->LastEdited);
+        var_dump($siteConfig->getCacheKey());
+
+        // Sleep for a second to make sure our date changes
+        sleep(1);
+
+        // Flush updates from KFC so that new writes invalidate cache keys
+        ProcessedUpdatesService::singleton()->flush();
+
+        // Make a change to SiteConfig
+        $siteConfig->Title = 'Updated Site Title 1';
+        $siteConfig->write();
+
+        // We would expect these values to change now
+        var_dump($siteConfig->LastEdited);
+        var_dump($siteConfig->getCacheKey());
+
+        // Sleep for a second to make sure our date changes
+        sleep(1);
+
+        // Flush updates from KFC so that new writes invalidate cache keys
+        ProcessedUpdatesService::singleton()->flush();
+
+        // Make a change to SiteConfig
+        $siteConfig->Title = 'Updated Site Title 2';
+        $siteConfig->write();
+
+        // We would expect these values to change again now
+        var_dump($siteConfig->LastEdited);
+        var_dump($siteConfig->getCacheKey());
+    }
+
+}
+```