@seeka-labs/cli-apps 3.8.10 → 3.9.2

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

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