@nlabs/reaktor 0.9.0 → 0.10.1

package/TEST_UTILITIES_GUIDE.md

@@ -0,0 +1,360 @@
+# Test Utilities Guide
+
+This guide explains how to use the test utilities in `src/utils/testUtils.ts` to optimize and consolidate your GraphQL query and mutation tests.
+
+## Overview
+
+The test utilities provide a standardized way to create tests for GraphQL resolvers, reducing code duplication and improving maintainability. They abstract common testing patterns into reusable functions.
+
+## Available Utilities
+
+### 1. Mock Context and Resolve Info
+
+```typescript
+import { createMockContext, createMockResolveInfo } from '../utils/testUtils';
+
+// Create a standard mock context
+const context = createMockContext();
+
+// Create a custom context with overrides
+const customContext = createMockContext({
+  databaseName: 'custom-db',
+  session: { userId: 'custom-user' }
+});
+
+// Create mock resolve info for GraphQL resolvers
+const resolveInfo = createMockResolveInfo('fieldName');
+```
+
+### 2. Mock Data Generators
+
+```typescript
+import {
+  createMockUser,
+  createMockPost,
+  createMockMessage,
+  createMockReaction,
+  createMockTag
+} from '../utils/testUtils';
+
+// Create mock data with defaults
+const user = createMockUser();
+const post = createMockPost();
+
+// Create mock data with custom values
+const customUser = createMockUser({
+  userId: 'custom-id',
+  email: 'custom@example.com'
+});
+```
+
+### 3. Mock Setup Utilities
+
+```typescript
+import { mockActionsModule, mockObjectType, setupCommonMocks } from '../utils/testUtils';
+
+// Mock actions module
+mockActionsModule('../actions/users', {
+  getUser: jest.fn(),
+  getSessionUser: jest.fn()
+});
+
+// Mock object types
+mockObjectType('../objectTypes/user', 'user');
+
+// Setup common mocks (auth utils, etc.)
+setupCommonMocks();
+```
+
+## Test Suite Creators
+
+### 1. Query Test Suite
+
+Use `createQueryTestSuite` for testing GraphQL query resolvers:
+
+```typescript
+import { createQueryTestSuite, createMockUser } from '../utils/testUtils';
+
+// Mock dependencies
+mockActionsModule('../actions/users', {
+  getUser: jest.fn(),
+  getSessionUser: jest.fn()
+});
+mockObjectType('../objectTypes/user', 'user');
+
+// Define test cases
+const testCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  },
+  {
+    name: 'getUserById',
+    actionName: 'getUser',
+    args: { userId: 'user1' },
+    expectedCall: (context: any, args: any) => ({ userId: args.userId }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  }
+];
+
+// Create the test suite
+createQueryTestSuite(
+  'User Queries',
+  '../actions/users',
+  '../objectTypes/user',
+  'user',
+  testCases
+);
+```
+
+### 2. Mutation Test Suite
+
+Use `createMutationTestSuite` for testing GraphQL mutation resolvers:
+
+```typescript
+import { createMutationTestSuite, createMockUser, setupCommonMocks } from '../utils/testUtils';
+
+// Setup common mocks
+setupCommonMocks();
+
+// Mock mutations module (complex setup)
+jest.mock('./users', () => ({
+  userMutations: {
+    getField: jest.fn((fieldName) => ({
+      resolve: jest.fn(async (context, args) => {
+        const actions = require('../actions/users');
+        return await actions[fieldName](context, args);
+      })
+    }))
+  }
+}));
+
+// Define test cases
+const testCases = [
+  {
+    name: 'addUser',
+    actionName: 'addUser',
+    args: { username: 'testuser', email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => args,
+    mockReturnValue: createMockUser()
+  },
+  {
+    name: 'deactivateUser',
+    actionName: 'deactivateUser',
+    args: { userId: 'user1' },
+    expectedCall: (context: any, args: any) => args,
+    mockReturnValue: createMockUser(),
+    requiresAuth: true,
+    authUserId: 'user1'
+  }
+];
+
+// Create the test suite
+createMutationTestSuite(
+  'User',
+  '../actions/users',
+  './users',
+  testCases
+);
+```
+
+### 3. Integration Test Suite
+
+Use `createIntegrationTestSuite` for testing integration scenarios:
+
+```typescript
+import { createIntegrationTestSuite, createMockUser } from '../utils/testUtils';
+
+// Define test cases
+const testCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    successReturnValue: createMockUser(),
+    errorReturnValue: null,
+    testErrorCase: true
+  }
+];
+
+// Create the integration test suite
+createIntegrationTestSuite(
+  'User',
+  '../actions/users',
+  '../objectTypes/user',
+  'user',
+  testCases
+);
+```
+
+## Test Case Configuration
+
+### Query Test Cases
+
+```typescript
+{
+  name: string;                    // Test name
+  actionName: string;              // Action function name
+  args: any;                       // Arguments to pass
+  expectedCall: (context: any, args: any) => any;  // Expected call parameters
+  mockReturnValue?: any;           // Mock return value
+  errorCase?: boolean;             // Whether to test error handling
+}
+```
+
+### Mutation Test Cases
+
+```typescript
+{
+  name: string;                    // Test name
+  actionName: string;              // Action function name
+  args: any;                       // Arguments to pass
+  expectedCall: (context: any, args: any) => any;  // Expected call parameters
+  mockReturnValue?: any;           // Mock return value
+  requiresAuth?: boolean;          // Whether authentication is required
+  authUserId?: string;             // User ID for auth check
+  errorCase?: boolean;             // Whether to test error handling
+}
+```
+
+### Integration Test Cases
+
+```typescript
+{
+  name: string;                    // Test name
+  actionName: string;              // Action function name
+  args: any;                       // Arguments to pass
+  expectedCall: (context: any, args: any) => any;  // Expected call parameters
+  successReturnValue?: any;        // Success case return value
+  errorReturnValue?: any;          // Error case return value
+  testErrorCase?: boolean;         // Whether to test error scenarios
+}
+```
+
+## Migration Guide
+
+### From Manual Tests to Utilities
+
+**Before (Manual):**
+```typescript
+describe('User Queries', () => {
+  const mockContext = {
+    databaseName: 'test',
+    session: { userId: 'user1', username: 'testuser', userAccess: 1 }
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getUserByEmail', () => {
+    it('should call getUser action with email parameter', async () => {
+      const mockUser = { userId: 'user1', email: 'test@example.com' };
+      const { getUser } = require('../actions/users');
+      getUser.mockResolvedValue(mockUser);
+
+      const result = await getUser(mockContext, { email: 'test@example.com' });
+
+      expect(getUser).toHaveBeenCalledWith(mockContext, { email: 'test@example.com' });
+      expect(result).toEqual(mockUser);
+    });
+  });
+});
+```
+
+**After (Using Utilities):**
+```typescript
+import { createQueryTestSuite, createMockUser } from '../utils/testUtils';
+
+const testCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    mockReturnValue: createMockUser()
+  }
+];
+
+createQueryTestSuite('User Queries', '../actions/users', '../objectTypes/user', 'user', testCases);
+```
+
+## Benefits
+
+1. **Reduced Code Duplication**: Common test patterns are abstracted into reusable functions
+2. **Consistent Testing**: All tests follow the same structure and patterns
+3. **Easier Maintenance**: Changes to test patterns only need to be made in one place
+4. **Better Readability**: Test intentions are clearer with declarative test case definitions
+5. **Faster Development**: New tests can be created quickly by defining test cases
+
+## Best Practices
+
+1. **Use Descriptive Names**: Make test case names clear and descriptive
+2. **Group Related Tests**: Use the suite name to group related functionality
+3. **Test Both Success and Error Cases**: Include error handling tests where appropriate
+4. **Use Mock Data Generators**: Use the provided mock data generators for consistent test data
+5. **Keep Test Cases Focused**: Each test case should test one specific scenario
+
+## Example: Complete Optimized Test File
+
+```typescript
+import {
+  createQueryTestSuite,
+  createMockUser,
+  mockActionsModule,
+  mockObjectType
+} from '../utils/testUtils';
+
+// Mock dependencies
+mockActionsModule('../actions/users', {
+  getUser: jest.fn(),
+  getSessionUser: jest.fn()
+});
+
+mockObjectType('../objectTypes/user', 'user');
+
+// Define test cases
+const userQueryTestCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  },
+  {
+    name: 'getUserById',
+    actionName: 'getUser',
+    args: { userId: 'user1' },
+    expectedCall: (context: any, args: any) => ({ userId: args.userId }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  },
+  {
+    name: 'getUserBySession',
+    actionName: 'getSessionUser',
+    args: {},
+    expectedCall: (context: any, args: any) => ({}),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  }
+];
+
+// Create the test suite
+createQueryTestSuite(
+  'User Queries',
+  '../actions/users',
+  '../objectTypes/user',
+  'user',
+  userQueryTestCases
+);
+```
+
+This approach reduces the original 130-line test file to just 40 lines while maintaining the same test coverage and functionality.

package/coverage/index.html

@@ -23,30 +23,30 @@
         <div class='clearfix'>
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">60.63% </span>
+                <span class="strong">78.94% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>248/409</span>
+                <span class='fraction'>2414/3058</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">41.89% </span>
+                <span class="strong">64.96% </span>
                 <span class="quiet">Branches</span>
-                <span class='fraction'>31/74</span>
+                <span class='fraction'>777/1196</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">45.45% </span>
+                <span class="strong">75.51% </span>
                 <span class="quiet">Functions</span>
-                <span class='fraction'>55/121</span>
+                <span class='fraction'>512/678</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">56.74% </span>
+                <span class="strong">77.19% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>202/356</span>
+                <span class='fraction'>2126/2754</span>
             </div>
         
             
@@ -79,52 +79,67 @@
 </tr>
 </thead>
 <tbody><tr>
-	<td class="file medium" data-value="actions"><a href="actions/index.html">actions</a></td>
-	<td data-value="57.53" class="pic medium">
-	<div class="chart"><div class="cover-fill" style="width: 57%"></div><div class="cover-empty" style="width: 43%"></div></div>
+	<td class="file high" data-value="src"><a href="src/index.html">src</a></td>
+	<td data-value="100" class="pic high">
+	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
+	</td>
+	<td data-value="100" class="pct high">100%</td>
+	<td data-value="17" class="abs high">17/17</td>
+	<td data-value="86.66" class="pct high">86.66%</td>
+	<td data-value="15" class="abs high">13/15</td>
+	<td data-value="100" class="pct high">100%</td>
+	<td data-value="4" class="abs high">4/4</td>
+	<td data-value="100" class="pct high">100%</td>
+	<td data-value="17" class="abs high">17/17</td>
+	</tr>
+
+<tr>
+	<td class="file high" data-value="src/actions"><a href="src/actions/index.html">src/actions</a></td>
+	<td data-value="80.23" class="pic high">
+	<div class="chart"><div class="cover-fill" style="width: 80%"></div><div class="cover-empty" style="width: 20%"></div></div>
 	</td>
-	<td data-value="57.53" class="pct medium">57.53%</td>
-	<td data-value="292" class="abs medium">168/292</td>
-	<td data-value="33.33" class="pct low">33.33%</td>
-	<td data-value="21" class="abs low">7/21</td>
-	<td data-value="45.91" class="pct low">45.91%</td>
-	<td data-value="98" class="abs low">45/98</td>
-	<td data-value="53.78" class="pct medium">53.78%</td>
-	<td data-value="264" class="abs medium">142/264</td>
+	<td data-value="80.23" class="pct high">80.23%</td>
+	<td data-value="2181" class="abs high">1750/2181</td>
+	<td data-value="64.36" class="pct medium">64.36%</td>
+	<td data-value="623" class="abs medium">401/623</td>
+	<td data-value="78.57" class="pct medium">78.57%</td>
+	<td data-value="490" class="abs medium">385/490</td>
+	<td data-value="78.57" class="pct medium">78.57%</td>
+	<td data-value="2002" class="abs medium">1573/2002</td>
 	</tr>
 
 <tr>
-	<td class="file high" data-value="adapters"><a href="adapters/index.html">adapters</a></td>
-	<td data-value="93.75" class="pic high">
-	<div class="chart"><div class="cover-fill" style="width: 93%"></div><div class="cover-empty" style="width: 7%"></div></div>
+	<td class="file medium" data-value="src/adapters"><a href="src/adapters/index.html">src/adapters</a></td>
+	<td data-value="61.71" class="pic medium">
+	<div class="chart"><div class="cover-fill" style="width: 61%"></div><div class="cover-empty" style="width: 39%"></div></div>
 	</td>
-	<td data-value="93.75" class="pct high">93.75%</td>
-	<td data-value="32" class="abs high">30/32</td>
-	<td data-value="64" class="pct medium">64%</td>
-	<td data-value="25" class="abs medium">16/25</td>
-	<td data-value="75" class="pct medium">75%</td>
-	<td data-value="8" class="abs medium">6/8</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="19" class="abs high">19/19</td>
+	<td data-value="61.71" class="pct medium">61.71%</td>
+	<td data-value="431" class="abs medium">266/431</td>
+	<td data-value="62.26" class="pct medium">62.26%</td>
+	<td data-value="424" class="abs medium">264/424</td>
+	<td data-value="40" class="pct low">40%</td>
+	<td data-value="75" class="abs low">30/75</td>
+	<td data-value="58.99" class="pct medium">58.99%</td>
+	<td data-value="378" class="abs medium">223/378</td>
 	</tr>
 
 <tr>
-	<td class="file high" data-value="mocks"><a href="mocks/index.html">mocks</a></td>
+	<td class="file high" data-value="src/mocks"><a href="src/mocks/index.html">src/mocks</a></td>
 	<td data-value="100" class="pic high">
 	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
 	</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="10" class="abs high">10/10</td>
+	<td data-value="20" class="abs high">20/20</td>
 	<td data-value="100" class="pct high">100%</td>
 	<td data-value="0" class="abs high">0/0</td>
 	<td data-value="100" class="pct high">100%</td>
 	<td data-value="0" class="abs high">0/0</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="10" class="abs high">10/10</td>
+	<td data-value="20" class="abs high">20/20</td>
 	</tr>
 
 <tr>
-	<td class="file high" data-value="types"><a href="types/index.html">types</a></td>
+	<td class="file high" data-value="src/types"><a href="src/types/index.html">src/types</a></td>
 	<td data-value="100" class="pic high">
 	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
 	</td>
@@ -139,18 +154,18 @@
 	</tr>
 
 <tr>
-	<td class="file medium" data-value="utils"><a href="utils/index.html">utils</a></td>
-	<td data-value="52.7" class="pic medium">
-	<div class="chart"><div class="cover-fill" style="width: 52%"></div><div class="cover-empty" style="width: 48%"></div></div>
+	<td class="file high" data-value="src/utils"><a href="src/utils/index.html">src/utils</a></td>
+	<td data-value="88.23" class="pic high">
+	<div class="chart"><div class="cover-fill" style="width: 88%"></div><div class="cover-empty" style="width: 12%"></div></div>
 	</td>
-	<td data-value="52.7" class="pct medium">52.7%</td>
-	<td data-value="74" class="abs medium">39/74</td>
-	<td data-value="28.57" class="pct low">28.57%</td>
-	<td data-value="28" class="abs low">8/28</td>
-	<td data-value="26.66" class="pct low">26.66%</td>
-	<td data-value="15" class="abs low">4/15</td>
-	<td data-value="48.38" class="pct low">48.38%</td>
-	<td data-value="62" class="abs low">30/62</td>
+	<td data-value="88.23" class="pct high">88.23%</td>
+	<td data-value="408" class="abs high">360/408</td>
+	<td data-value="73.88" class="pct medium">73.88%</td>
+	<td data-value="134" class="abs medium">99/134</td>
+	<td data-value="85.32" class="pct high">85.32%</td>
+	<td data-value="109" class="abs high">93/109</td>
+	<td data-value="86.9" class="pct high">86.9%</td>
+	<td data-value="336" class="abs high">292/336</td>
 	</tr>
 
 </tbody>
@@ -161,7 +176,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2025-02-04T16:39:29.322Z
+                at 2025-07-02T05:49:37.404Z
             </div>
         <script src="prettify.js"></script>
         <script>