@michelabboud/visual-forge-mcp 0.5.5 → 0.6.0

package/docs/guides/development-testing.md

@@ -0,0 +1,338 @@
+# Visual Forge MCP - Testing Guide
+
+## Overview
+
+This guide explains how to write and run tests for Visual Forge MCP.
+
+## Test Infrastructure
+
+The project uses:
+- **Jest** - Testing framework
+- **ts-jest** - TypeScript support for Jest
+- **ES Modules** - Full ES module support
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- provider-factory.test.ts
+```
+
+## Writing Tests
+
+### Test Structure
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { YourModule } from '../src/your-module.js';
+
+describe('YourModule', () => {
+  beforeEach(() => {
+    // Setup before each test
+  });
+
+  afterEach(() => {
+    // Cleanup after each test
+  });
+
+  describe('yourMethod()', () => {
+    it('should do something specific', () => {
+      // Arrange
+      const input = 'test';
+
+      // Act
+      const result = yourMethod(input);
+
+      // Assert
+      expect(result).toBe('expected');
+    });
+  });
+});
+```
+
+### Using Test Helpers
+
+```typescript
+import {
+  createMockImageSpec,
+  createMockProviderConfig,
+  setTestEnv,
+  clearTestEnv,
+} from './test/helpers/test-utils.js';
+
+// Create test data
+const spec = createMockImageSpec({
+  prompt: 'Custom prompt',
+  aspectRatio: '16:9',
+});
+
+// Set environment variables
+setTestEnv({
+  GOOGLE_API_KEY: 'AIza-test-key-1234567890',
+});
+
+// Clean up
+clearTestEnv(['GOOGLE_API_KEY']);
+```
+
+### Mocking
+
+#### Mocking Modules
+
+```typescript
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+mockedAxios.post = jest.fn().mockResolvedValue({
+  data: { success: true },
+});
+```
+
+#### Mock Providers
+
+```typescript
+import { createMockProvider } from './test/helpers/mock-providers.js';
+
+const successProvider = createMockProvider('success');
+const failureProvider = createMockProvider('failure');
+const rateLimitedProvider = createMockProvider('rate-limited');
+```
+
+## Best Practices
+
+### 1. Test Isolation
+
+Each test should be independent:
+
+```typescript
+beforeEach(() => {
+  // Reset state before each test
+  jest.clearAllMocks();
+  clearTestEnv(['API_KEY']);
+});
+```
+
+### 2. Descriptive Test Names
+
+```typescript
+// Good
+it('should throw ConfigurationError when API key is missing', () => {});
+
+// Bad
+it('should fail', () => {});
+```
+
+### 3. AAA Pattern
+
+Use Arrange-Act-Assert:
+
+```typescript
+it('should calculate cost correctly', () => {
+  // Arrange
+  const spec = createMockImageSpec();
+  const provider = createMockProvider();
+
+  // Act
+  const cost = provider.estimateCost(spec);
+
+  // Assert
+  expect(cost).toBe(0.04);
+});
+```
+
+### 4. Test Both Success and Failure Paths
+
+```typescript
+describe('generate()', () => {
+  it('should successfully generate image', async () => {
+    // Test success path
+  });
+
+  it('should handle API errors gracefully', async () => {
+    // Test error path
+  });
+});
+```
+
+### 5. Mock External Dependencies
+
+Always mock:
+- HTTP clients (axios)
+- File system operations (fs/promises)
+- Image processing (sharp)
+- Environment variables
+
+```typescript
+jest.mock('fs/promises', () => ({
+  writeFile: jest.fn().mockResolvedValue(undefined),
+  mkdir: jest.fn().mockResolvedValue(undefined),
+}));
+```
+
+## Common Test Patterns
+
+### Testing Async Functions
+
+```typescript
+it('should generate image asynchronously', async () => {
+  const spec = createMockImageSpec();
+  const result = await provider.generate(spec);
+
+  expect(result).toBeDefined();
+  expect(result.filepath).toContain(spec.id);
+});
+```
+
+### Testing Error Handling
+
+```typescript
+it('should throw error when provider unavailable', () => {
+  const config = createMockProviderConfig({ apiKey: '' });
+  const provider = new Provider(config);
+
+  expect(() => provider.generate(spec)).rejects.toThrow();
+});
+```
+
+### Testing Environment Variables
+
+```typescript
+it('should use environment variable for API key', () => {
+  setTestEnv({ GOOGLE_API_KEY: 'test-key' });
+
+  const factory = new ProviderFactory();
+  factory.initialize();
+
+  expect(factory.isProviderAvailable('gemini')).toBe(true);
+
+  clearTestEnv(['GOOGLE_API_KEY']);
+});
+```
+
+## Coverage Goals
+
+Aim for:
+- **Branches**: 60%
+- **Functions**: 60%
+- **Lines**: 60%
+- **Statements**: 60%
+
+Critical paths should have higher coverage (80%+):
+- Provider initialization
+- Image generation
+- Error handling
+- State persistence
+
+## Debugging Tests
+
+### Run Single Test
+
+```bash
+npm test -- --testNamePattern="should initialize OpenAI"
+```
+
+### Enable Verbose Output
+
+```bash
+npm test -- --verbose
+```
+
+### Debug in VS Code
+
+Add to `.vscode/launch.json`:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Jest Debug",
+  "program": "${workspaceFolder}/node_modules/.bin/jest",
+  "args": ["--runInBand", "--no-cache"],
+  "console": "integratedTerminal",
+  "internalConsoleOptions": "neverOpen"
+}
+```
+
+## Common Issues
+
+### ES Module Issues
+
+If you see "Cannot use import statement outside a module":
+
+1. Ensure `package.json` has `"type": "module"`
+2. Use `.js` extensions in imports (even for `.ts` files)
+3. Check `jest.config.js` has correct ES module configuration
+
+### Type Errors in Tests
+
+If TypeScript complains about test types:
+
+1. Ensure `@types/jest` is installed
+2. Add `"jest"` to `types` in `tsconfig.json`
+3. Use proper Jest matchers
+
+### Mock Not Working
+
+If mocks aren't being applied:
+
+1. Call `jest.clearAllMocks()` in `beforeEach`
+2. Ensure mock is defined before importing module
+3. Use `jest.resetModules()` if needed
+
+## Test Organization
+
+```
+test/
+├── helpers/           # Shared test utilities
+│   ├── test-utils.ts
+│   └── mock-providers.ts
+├── providers/         # Provider tests
+│   └── provider-factory.test.ts
+├── state/             # State management tests (planned)
+├── workflow/          # Workflow tests (planned)
+└── README.md          # Test documentation
+```
+
+## CI/CD Integration
+
+Tests are designed to run in CI:
+- No external API calls (all mocked)
+- Fast execution (< 10 seconds)
+- Deterministic results
+- No file system dependencies
+
+Example GitHub Actions:
+
+```yaml
+name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '24'
+      - run: npm install
+      - run: npm test
+      - run: npm test -- --coverage
+```
+
+## Next Steps
+
+1. Add more provider tests
+2. Add StateManager tests
+3. Add WorkflowOrchestrator tests
+4. Add MarkdownParser tests
+5. Add QualityInspector tests
+6. Increase code coverage to 80%+