From ba42ed895b9edf4996224bd8a554cae04cf771c3 Mon Sep 17 00:00:00 2001
From: Lentil Hoffman <lentil@laddhoffman.com>
Date: Wed, 9 Jul 2025 16:21:11 -0500
Subject: [PATCH] test helper docs

---
 docs/test-helpers.md | 79 ++++++++++++++++++++++++++++++--------------
 1 file changed, 54 insertions(+), 25 deletions(-)

diff --git a/docs/test-helpers.md b/docs/test-helpers.md
index c1496cd..3325dd2 100644
--- a/docs/test-helpers.md
+++ b/docs/test-helpers.md
@@ -4,7 +4,7 @@ This document provides documentation for the test helper functions available in
 
 ## `testResolverWithPlugins`
 
-A helper function for testing custom resolvers with plugins and a sequence of deltas.
+An async helper function for testing custom resolvers with plugins and a sequence of deltas. Returns a Promise that resolves to the resolved entity.
 
 ### Import
 
@@ -16,28 +16,25 @@ import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver
 
 ```typescript
 function testResolverWithPlugins<T>({
-  entityId,
+  entityId = 'test-entity',
   plugins,
-  deltas,
-  expectedResult
+  deltas
 }: {
-  entityId: string;
+  entityId?: string;
   plugins: Record<string, ResolverPlugin>;
   deltas: Delta[];
-  expectedResult: (result: T) => void;
-}): Promise<void>;
+}): Promise<ResolvedEntity>;
 ```
 
 ### Parameters
 
-- `entityId`: The ID of the entity to test
+- `entityId` (optional): The ID of the entity to test (defaults to 'test-entity')
 - `plugins`: An object mapping property names to their respective resolver plugins
 - `deltas`: An array of `Delta` objects to process
-- `expectedResult`: A callback function that receives the resolved result for assertions
 
 ### Return Value
 
-A promise that resolves when the test is complete.
+A Promise that resolves to the resolved entity with all properties processed by the specified plugins.
 
 ### Example Usage
 
@@ -47,24 +44,28 @@ import { ConcatenationPlugin } from '@src/views/resolvers/custom-resolvers/built
 
 describe('MyCustomResolver', () => {
   test('should process deltas correctly', async () => {
+    // Define test data
+    const entityId = 'entity1';
+    
     // Run test with plugins and deltas
-    await testResolverWithPlugins({
-      entityId: 'entity1',
+    const result = await testResolverWithPlugins({
+      entityId,
       plugins: {
         myProperty: new ConcatenationPlugin()
       },
       deltas: [
         createTestDelta('user1', 'host1')
-          .setProperty('entity1', 'myProperty', 'value1')
+          .setProperty(entityId, 'myProperty', 'value1')
           .buildV1(),
         createTestDelta('user1', 'host1')
-          .setProperty('entity1', 'myProperty', 'value2')
+          .setProperty(entityId, 'myProperty', 'value2')
           .buildV1()
-      ],
-      expectedResult: (result) => {
-        expect(result.properties.myProperty).toBe('value1 value2');
-      }
+      ]
     });
+    
+    // Assert the results
+    expect(result).toBeDefined();
+    expect(result.properties.myProperty).toBe('value1 value2');
   });
 });
 ```
@@ -76,10 +77,22 @@ A helper function for creating test deltas with a fluent API.
 ### Example Usage
 
 ```typescript
+// Create a simple delta
 const delta = createTestDelta('user1', 'host1')
   .withTimestamp(1000)
   .setProperty('entity1', 'tags', 'red', 'color1')
   .buildV1();
+
+// Declare a transaction
+const transaction = createTestDelta('user1', 'host1')
+  .declareTransaction('tx123', 1)
+  .buildV1();
+
+// Create a delta in a transaction
+const deltaInTransaction = createTestDelta('user1', 'host1')
+  .inTransaction('tx123')
+  .setProperty('entity1', 'status', 'active', 'system')
+  .buildV1();
 ```
 
 ## How It Works
@@ -87,14 +100,30 @@ const delta = createTestDelta('user1', 'host1')
 1. Creates a new `Hyperview` instance for the test
 2. Sets up a `CustomResolver` with the provided plugins
 3. Ingests all provided deltas into the `Hyperview` instance
-4. Retrieves a view for the specified entity
-5. Processes the view through the resolver
-6. Calls the `expectedResult` callback with the resolved entity
+4. Retrieves and resolves the view for the specified entity
+5. Returns the resolved entity as a Promise
 
 ## Best Practices
 
-- Use this helper when testing custom resolvers with plugins
-- The helper handles all setup and teardown of test resources
-- Use `createTestDelta` for consistent delta creation in tests
-- The helper ensures type safety between the resolver and the expected result type
+### Test Structure
+- Use `async/await` for cleaner test code
+- Group related tests in `describe` blocks
+- Use clear, descriptive test names
+- Test edge cases like empty states and error conditions
+
+### Delta Creation
+- Use `createTestDelta` for consistent delta creation
+- Set appropriate timestamps for time-based tests
+- Include all necessary properties in test deltas
+- Use transactions when testing multi-delta operations
+
+### Assertions
+- Always check that the result is defined before accessing properties
+- Test both happy paths and error conditions
+- Consider testing with different plugin configurations
+- Verify the complete state of resolved entities, not just individual properties
+
+### Performance
 - Each test gets a fresh `Hyperview` instance automatically
+- For complex test scenarios, consider using helper functions to create test data
+- Keep test data minimal and focused on the specific behavior being tested