@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/common/guides/testing.md

@@ -0,0 +1,592 @@
+# Testing Seeka Apps
+
+This guide covers testing strategies and best practices for Seeka apps.
+
+## Testing Stack
+
+Seeka apps use the following testing tools:
+
+| Tool | Purpose |
+|------|---------|
+| Jest | Test runner and assertion library |
+| ts-jest | TypeScript support for Jest |
+
+## Test Structure
+
+```
+app/
+├── server/
+│   └── src/
+│       └── app/
+│           └── services/
+│               ├── myService.ts
+│               └── __tests__/
+│                   └── myService.test.ts
+└── lib/
+    └── src/
+        ├── validation/
+        │   ├── index.ts
+        │   └── __tests__/
+        │       └── index.test.ts
+        └── models/
+            └── __tests__/
+                └── index.test.ts
+```
+
+## Unit Testing
+
+### Testing Services
+
+```typescript
+// services/__tests__/externalPlatform.test.ts
+import { ExternalPlatformService } from '../externalPlatform';
+
+// Mock logger
+const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn()
+} as any;
+
+describe('ExternalPlatformService', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('sendEvent', () => {
+        it('should send event successfully', async () => {
+            // Arrange
+            global.fetch = jest.fn().mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({ success: true })
+            });
+
+            const service = new ExternalPlatformService({
+                apiKey: 'test-api-key',
+                accountId: 'test-account'
+            }, mockLogger);
+
+            // Act
+            const result = await service.sendEvent({
+                event_name: 'Purchase',
+                value: 100
+            });
+
+            // Assert
+            expect(result).toBe(true);
+            expect(fetch).toHaveBeenCalledWith(
+                expect.stringContaining('/events'),
+                expect.objectContaining({
+                    method: 'POST',
+                    headers: expect.objectContaining({
+                        'Authorization': 'Bearer test-api-key'
+                    })
+                })
+            );
+        });
+
+        it('should handle API errors', async () => {
+            // Arrange
+            global.fetch = jest.fn().mockResolvedValue({
+                ok: false,
+                status: 400,
+                text: () => Promise.resolve('Bad request')
+            });
+
+            const service = new ExternalPlatformService({
+                apiKey: 'test-api-key',
+                accountId: 'test-account'
+            }, mockLogger);
+
+            // Act & Assert
+            await expect(service.sendEvent({ event_name: 'Test' }))
+                .rejects.toThrow('API error');
+
+            expect(mockLogger.error).toHaveBeenCalled();
+        });
+
+        it('should handle network errors', async () => {
+            // Arrange
+            global.fetch = jest.fn().mockRejectedValue(new Error('Network error'));
+
+            const service = new ExternalPlatformService({
+                apiKey: 'test-api-key',
+                accountId: 'test-account'
+            }, mockLogger);
+
+            // Act & Assert
+            await expect(service.sendEvent({ event_name: 'Test' }))
+                .rejects.toThrow('Network error');
+        });
+    });
+});
+```
+
+### Testing Validation
+
+```typescript
+// validation/__tests__/index.test.ts
+import { validateInstallationSettings } from '../index';
+
+const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn()
+} as any;
+
+describe('validateInstallationSettings', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return null for valid settings', async () => {
+        const settings = {
+            apiKey: 'valid-api-key',
+            accountId: 'valid-account-id'
+        };
+
+        const result = await validateInstallationSettings(settings, mockLogger);
+
+        expect(result).toBeNull();
+    });
+
+    it('should return error for missing apiKey', async () => {
+        const settings = {
+            accountId: 'valid-account-id'
+        };
+
+        const result = await validateInstallationSettings(settings as any, mockLogger);
+
+        expect(result).toBe('API Key is required');
+    });
+
+    it('should return error for missing accountId', async () => {
+        const settings = {
+            apiKey: 'valid-api-key'
+        };
+
+        const result = await validateInstallationSettings(settings as any, mockLogger);
+
+        expect(result).toBe('Account ID is required');
+    });
+});
+```
+
+### Testing Data Transformations
+
+```typescript
+// services/__tests__/dataMapper.test.ts
+import { mapActivityToPlatformEvent } from '../dataMapper';
+
+describe('mapActivityToPlatformEvent', () => {
+    it('should map activity to platform event format', () => {
+        const activity = {
+            activity: {
+                activityId: 'act-123',
+                activityName: 'Purchase',
+                timestamp: '2024-01-15T10:30:00Z',
+                properties: {
+                    currency: 'USD',
+                    value: 99.99
+                }
+            },
+            person: {
+                personId: 'person-123',
+                emailHashed: 'abc123hash',
+                phoneHashed: 'def456hash'
+            }
+        };
+
+        const result = mapActivityToPlatformEvent(activity);
+
+        expect(result).toEqual({
+            event_name: 'Purchase',
+            event_time: expect.any(Number),
+            user_data: {
+                em: ['abc123hash'],
+                ph: ['def456hash']
+            },
+            custom_data: {
+                currency: 'USD',
+                value: 99.99,
+                content_ids: undefined
+            }
+        });
+    });
+
+    it('should handle missing person data', () => {
+        const activity = {
+            activity: {
+                activityId: 'act-123',
+                activityName: 'PageView',
+                timestamp: '2024-01-15T10:30:00Z'
+            }
+        };
+
+        const result = mapActivityToPlatformEvent(activity);
+
+        expect(result.user_data.em).toBeUndefined();
+        expect(result.user_data.ph).toBeUndefined();
+    });
+
+    it('should map activity names correctly', () => {
+        const testCases = [
+            { input: 'PageView', expected: 'ViewContent' },
+            { input: 'Purchase', expected: 'Purchase' },
+            { input: 'AddToCart', expected: 'AddToCart' },
+            { input: 'CustomEvent', expected: 'CustomEvent' }
+        ];
+
+        testCases.forEach(({ input, expected }) => {
+            const activity = {
+                activity: {
+                    activityId: 'act-123',
+                    activityName: input,
+                    timestamp: '2024-01-15T10:30:00Z'
+                }
+            };
+
+            const result = mapActivityToPlatformEvent(activity);
+            expect(result.event_name).toBe(expected);
+        });
+    });
+});
+```
+
+## Integration Testing
+
+### Testing Webhook Handlers
+
+```typescript
+// functions/__tests__/seekaAppWebhook.test.ts
+import { seekaAppWebhook } from '../seekaAppWebhook';
+import { InvocationContext } from '@azure/functions';
+
+// Mock SDK functions
+jest.mock('@seeka-labs/sdk-apps-server', () => ({
+    throwOnInvalidWebhookSignature: jest.fn(),
+    SeekaWebhookCallType: {
+        Probe: 'Probe',
+        AppInstalled: 'AppInstalled',
+        ActivityAccepted: 'ActivityAccepted'
+    }
+}));
+
+jest.mock('@seeka-labs/sdk-apps-server-host', () => ({
+    tryGetInstallation: jest.fn(),
+    createOrUpdateInstallation: jest.fn(),
+    startServices: jest.fn(),
+    webhookLogger: jest.fn(() => mockLogger),
+    childLogger: jest.fn(() => mockLogger)
+}));
+
+const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    verbose: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    profile: jest.fn()
+};
+
+describe('seekaAppWebhook', () => {
+    const mockContext = {
+        invocationId: 'test-invocation-id'
+    } as InvocationContext;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return 204 for probe requests', async () => {
+        const req = createMockRequest({
+            type: 'Probe'
+        });
+
+        const result = await seekaAppWebhook(req, mockContext);
+
+        expect(result.status).toBe(204);
+    });
+
+    it('should return 400 for missing body', async () => {
+        const req = createMockRequest(null);
+
+        const result = await seekaAppWebhook(req, mockContext);
+
+        expect(result.status).toBe(400);
+    });
+
+    it('should return 401 for invalid signature', async () => {
+        const { throwOnInvalidWebhookSignature } = require('@seeka-labs/sdk-apps-server');
+        throwOnInvalidWebhookSignature.mockImplementation(() => {
+            throw new Error('Invalid signature');
+        });
+
+        const req = createMockRequest({
+            type: 'AppInstalled',
+            context: { applicationInstallId: 'test-id' }
+        });
+
+        const result = await seekaAppWebhook(req, mockContext);
+
+        expect(result.status).toBe(401);
+    });
+});
+
+function createMockRequest(body: any) {
+    return {
+        text: () => Promise.resolve(body ? JSON.stringify(body) : ''),
+        headers: new Map([
+            ['x-seeka-signature', 'test-signature']
+        ])
+    } as any;
+}
+```
+
+### Testing Queue Handlers
+
+```typescript
+// functions/__tests__/trackActivityQueueHandler.test.ts
+import { processQueueItem } from '../trackActivityQueueHandler';
+
+jest.mock('@seeka-labs/sdk-apps-server-host', () => ({
+    tryGetInstallation: jest.fn(),
+    startServices: jest.fn(),
+    childLogger: jest.fn(() => mockLogger)
+}));
+
+jest.mock('../../app/services/activities', () => ({
+    processActivity: jest.fn()
+}));
+
+const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    error: jest.fn()
+};
+
+describe('trackActivityQueueHandler', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should process activity successfully', async () => {
+        const { tryGetInstallation } = require('@seeka-labs/sdk-apps-server-host');
+        const { processActivity } = require('../../app/services/activities');
+
+        tryGetInstallation.mockResolvedValue({
+            applicationInstallId: 'test-install-id',
+            installationState: {
+                installationSettings: { apiKey: 'test-key' }
+            }
+        });
+
+        const queueItem = {
+            payload: { activity: { activityId: 'act-123' } },
+            applicationInstallId: 'test-install-id'
+        };
+
+        await processQueueItem(queueItem, mockLogger);
+
+        expect(processActivity).toHaveBeenCalled();
+    });
+
+    it('should handle missing installation', async () => {
+        const { tryGetInstallation } = require('@seeka-labs/sdk-apps-server-host');
+        tryGetInstallation.mockResolvedValue(null);
+
+        const queueItem = {
+            payload: { activity: { activityId: 'act-123' } },
+            applicationInstallId: 'unknown-id'
+        };
+
+        await processQueueItem(queueItem, mockLogger);
+
+        expect(mockLogger.error).toHaveBeenCalledWith(
+            'Installation not found',
+            expect.any(Object)
+        );
+    });
+});
+```
+
+## Mocking Patterns
+
+### Mocking External APIs
+
+```typescript
+// __mocks__/externalApi.ts
+export const mockExternalApi = {
+    sendEvent: jest.fn().mockResolvedValue({ success: true }),
+    getAccount: jest.fn().mockResolvedValue({ id: 'account-123' })
+};
+
+// In test file
+jest.mock('../services/externalApi', () => mockExternalApi);
+```
+
+### Mocking Fetch
+
+```typescript
+// Global fetch mock
+beforeEach(() => {
+    global.fetch = jest.fn();
+});
+
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+
+// Success response
+(fetch as jest.Mock).mockResolvedValue({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve({ data: 'test' })
+});
+
+// Error response
+(fetch as jest.Mock).mockResolvedValue({
+    ok: false,
+    status: 500,
+    text: () => Promise.resolve('Server error')
+});
+
+// Network error
+(fetch as jest.Mock).mockRejectedValue(new Error('Network error'));
+```
+
+### Mocking SDK Functions
+
+```typescript
+jest.mock('@seeka-labs/sdk-apps-server-host', () => ({
+    getInstallation: jest.fn().mockResolvedValue({
+        applicationInstallId: 'test-id',
+        installationState: {
+            installationSettings: {
+                apiKey: 'test-key'
+            }
+        }
+    }),
+    createOrUpdateInstallation: jest.fn().mockResolvedValue(undefined),
+    triggerBackgroundJob: jest.fn().mockResolvedValue(undefined)
+}));
+```
+
+## Running Tests
+
+### Commands
+
+```bash
+# Run all tests
+yarn test
+
+# Run tests in watch mode
+yarn test --watch
+
+# Run specific test file
+yarn test myService.test.ts
+
+# Run with coverage
+yarn test --coverage
+
+# Run tests matching pattern
+yarn test --testNamePattern="should send event"
+```
+
+### Jest Configuration
+
+```javascript
+// jest.config.js
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    roots: ['<rootDir>/src'],
+    testMatch: ['**/__tests__/**/*.test.ts'],
+    collectCoverageFrom: [
+        'src/**/*.ts',
+        '!src/**/*.d.ts',
+        '!src/**/__tests__/**'
+    ],
+    coverageThreshold: {
+        global: {
+            branches: 80,
+            functions: 80,
+            lines: 80,
+            statements: 80
+        }
+    }
+};
+```
+
+## Best Practices
+
+### 1. Test Organization
+
+- Place tests in `__tests__` directories next to source files
+- Name test files with `.test.ts` suffix
+- Group related tests with `describe` blocks
+- Use clear, descriptive test names
+
+### 2. Test Independence
+
+```typescript
+// Each test should be independent
+beforeEach(() => {
+    jest.clearAllMocks();
+    // Reset any shared state
+});
+```
+
+### 3. Arrange-Act-Assert Pattern
+
+```typescript
+it('should do something', async () => {
+    // Arrange - set up test data and mocks
+    const input = { data: 'test' };
+    mockService.process.mockResolvedValue({ success: true });
+
+    // Act - execute the code under test
+    const result = await myFunction(input);
+
+    // Assert - verify the results
+    expect(result.success).toBe(true);
+    expect(mockService.process).toHaveBeenCalledWith(input);
+});
+```
+
+### 4. Test Edge Cases
+
+```typescript
+describe('edge cases', () => {
+    it('should handle empty input', async () => { /* ... */ });
+    it('should handle null values', async () => { /* ... */ });
+    it('should handle very large inputs', async () => { /* ... */ });
+    it('should handle special characters', async () => { /* ... */ });
+});
+```
+
+### 5. Error Testing
+
+```typescript
+it('should throw on invalid input', async () => {
+    await expect(myFunction(null))
+        .rejects.toThrow('Input is required');
+});
+
+it('should handle API errors gracefully', async () => {
+    mockApi.call.mockRejectedValue(new Error('API error'));
+
+    const result = await myFunction(input);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('API error');
+});
+```
+
+## See Also
+
+- `getting-started.md` - Initial setup guide
+- `common-patterns.md` - Implementation patterns
+- Jest documentation: https://jestjs.io/docs/getting-started