@nlabs/reaktor 0.10.6 → 0.10.7

package/TEST_UTILITIES_GUIDE.md

@@ -1,360 +0,0 @@
-# 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.