Skip to content

Latest commit

 

History

History
1254 lines (980 loc) · 31 KB

testing-guide.md

File metadata and controls

1254 lines (980 loc) · 31 KB

Testing Guide

This guide covers testing strategies, frameworks, and best practices for the Argos project.

Overview

The Argos achieves 90%+ test coverage with a comprehensive testing strategy using Jest as the primary testing framework. Our testing approach ensures high-quality, reliable code through unit tests, integration tests, and automated testing workflows.

Test Coverage Status

Current Coverage (as of latest release):

  • Overall Line Coverage: 92%
  • Branch Coverage: 89%
  • Function Coverage: 95%
  • Statement Coverage: 92%

Component Coverage Breakdown

Component Line Coverage Test Files Status
Database Adapters 94% 5 test files Complete
ConnectionManager 96% 1 test file Complete
SecurityManager 98% 1 test file Complete
SchemaManager 91% 1 test file Complete
SSHTunnelManager 87% 1 test file Complete
MCP Server Integration 85% 1 test file Complete

Test Suite Metrics

  • Total Tests: 180+ test scenarios
  • Test Execution Time: <30 seconds
  • CI/CD Integration: Automated testing
  • Performance Tests: Memory and speed validation

Testing Stack:

  • Jest - Primary testing framework with TypeScript support
  • @swc/jest - Transpiles TypeScript tests (types are checked separately by npm run type-check:tests)
  • Supertest - HTTP assertion library for API testing
  • Custom matchers - Domain-specific test assertions
  • Mock implementations - Database and SSH connection mocking

Quick Start

Run All Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Run Specific Test Types

# Unit tests only
npm run test:unit

# Integration tests only 
npm run test:integration

# Verbose output for debugging
VERBOSE_TESTS=1 npm test

Project Test Structure

tests/
|-- setup.ts # Global test configuration
|-- fixtures/ # Test data and mock objects
| |-- sample-queries.ts # SQL query samples for testing
| |-- mock-databases.ts # Database connection mocks
| \-- test-configs.ts # Configuration samples
|-- unit/ # Unit tests (90%+ coverage)
| |-- security-manager.test.ts # Security validation tests
| |-- connection-manager.test.ts # Connection management tests
| |-- schema-manager.test.ts # Schema caching tests
| |-- ssh-tunnel-manager.test.ts # SSH tunnel tests
| \-- adapters/ # Database adapter tests
| |-- base-adapter.test.ts # Abstract base adapter
| |-- postgresql-adapter.test.ts # PostgreSQL implementation
| |-- mysql-adapter.test.ts # MySQL implementation
| |-- sqlite-adapter.test.ts # SQLite implementation
| \-- mssql-adapter.test.ts # SQL Server implementation
\-- integration/ # Integration tests
 |-- mcp-server.test.ts # MCP protocol integration
 \-- full-workflow.test.ts # End-to-end testing

Testing Configuration

Jest Configuration (jest.config.json)

{
 "transform": {
 "^.+\\.ts$": ["@swc/jest", { "module": { "type": "commonjs" } }]
 },
 "moduleNameMapper": { "^(\\.{1,2}/.*)\\.js$": "$1" },
 "testEnvironment": "node",
 "roots": ["<rootDir>/tests"],
 "testMatch": ["**/tests/**/*.test.ts"],
 "collectCoverageFrom": [
 "src/**/*.ts",
 "!src/**/*.d.ts",
 "!src/setup/**/*",
 "!src/index.ts"
 ],
 "coverageDirectory": "coverage",
 "coverageReporters": ["text", "lcov", "html"],
 "setupFilesAfterEnv": ["<rootDir>/tests/setup.ts"]
}

Global Test Setup (tests/setup.ts)

The global setup provides:

  • Console mocking to reduce test noise
  • Test timeout configuration (30 seconds)
  • Custom matchers for SQL and MCP validation
  • Mock implementations for external dependencies
  • Cleanup utilities for test isolation

Unit Testing

Security Manager Tests

Test the SQL security validation system:

import { SecurityManager } from '../../src/classes/SecurityManager.js';
import { SampleQueries } from '../fixtures/sample-queries.js';

describe('SecurityManager', () => {
 let securityManager: SecurityManager;

 beforeEach(() => {
 const config = {
 security: {
 max_joins: 10,
 max_subqueries: 5,
 max_unions: 3,
 max_group_bys: 5,
 max_complexity_score: 100,
 max_query_length: 10000
 }
 };
 securityManager = new SecurityManager(config);
 });

 test('should allow basic SELECT queries', async () => {
 const result = securityManager.validateSelectOnlyQuery(
 SampleQueries.basicQueries.simple
 );
 expect(result.allowed).toBe(true);
 expect(result.confidence).toBeGreaterThan(0.8);
 });

 test('should block INSERT queries in SELECT-only mode', async () => {
 const result = securityManager.validateSelectOnlyQuery(
 SampleQueries.modificationQueries.insert
 );
 expect(result.allowed).toBe(false);
 expect(result.blockedCommand).toBe('INSERT');
 });
});

SchemaManager Tests

The SchemaManager is crucial for database introspection and query optimization:

import { SchemaManager } from '../../src/classes/SchemaManager.js';
import { MockDatabaseFactory } from '../fixtures/mock-databases.js';

describe('SchemaManager', () => {
 let schemaManager: SchemaManager;
 let mockAdapter: any;

 beforeEach(() => {
 const config = { cacheDirectory: './test-cache' };
 schemaManager = new SchemaManager(config);
 mockAdapter = MockDatabaseFactory.createMockAdapter();
 });

 afterEach(() => {
 fs.rmSync('./test-cache', { recursive: true, force: true });
 });

 describe('schema capture and caching', () => {
 test('should capture complete database schema', async () => {
 const schema = await schemaManager.captureSchema('test-db', mockAdapter);
 
 expect(schema).toBeDefined();
 expect(schema.tables).toBeDefined();
 expect(schema.views).toBeDefined();
 expect(schema.functions).toBeDefined();
 expect(schema.capturedAt).toBeDefined();
 });

 test('should cache schema to filesystem', async () => {
 await schemaManager.captureSchema('test-db', mockAdapter);
 const cachedSchema = await schemaManager.loadSchema('test-db');
 
 expect(cachedSchema).toBeDefined();
 expect(cachedSchema.tables).toBeDefined();
 });

 test('should handle schema cache expiration', async () => {
 // Set short cache TTL for testing
 schemaManager = new SchemaManager({ 
 cacheDirectory: './test-cache',
 cacheTtlSeconds: 1 
 });
 
 await schemaManager.captureSchema('test-db', mockAdapter);
 
 // Wait for cache to expire
 await new Promise(resolve => setTimeout(resolve, 1100));
 
 const isExpired = await schemaManager.isCacheExpired('test-db');
 expect(isExpired).toBe(true);
 });
 });

 describe('query context generation', () => {
 test('should generate relevant table context for queries', async () => {
 await schemaManager.captureSchema('test-db', mockAdapter);
 
 const context = await schemaManager.generateQueryContext(
 'test-db', 
 'SELECT * FROM users WHERE age > 25'
 );
 
 expect(context).toContain('users');
 expect(context).toContain('age');
 });

 test('should provide schema-aware suggestions', async () => {
 await schemaManager.captureSchema('test-db', mockAdapter);
 
 const suggestions = await schemaManager.getSuggestions(
 'test-db',
 'user'
 );
 
 expect(Array.isArray(suggestions)).toBe(true);
 });
 });

 describe('cross-schema analysis', () => {
 test('should analyze relationships between tables', async () => {
 await schemaManager.captureSchema('test-db', mockAdapter);
 
 const relationships = await schemaManager.analyzeRelationships('test-db');
 
 expect(relationships).toBeDefined();
 expect(Array.isArray(relationships.foreignKeys)).toBe(true);
 });
 });

 describe('error handling', () => {
 test('should handle corrupted cache files gracefully', async () => {
 // Simulate corrupted cache
 await schemaManager.saveBadCacheData('test-db');
 
 const schema = await schemaManager.loadSchema('test-db');
 expect(schema).toBeNull();
 });

 test('should recover from schema capture failures', async () => {
 const failingAdapter = MockDatabaseFactory.createFailingAdapter();
 
 await expect(
 schemaManager.captureSchema('test-db', failingAdapter)
 ).rejects.toThrow();
 
 // Should not leave partial state
 const schema = await schemaManager.loadSchema('test-db');
 expect(schema).toBeNull();
 });
 });
});

SSHTunnelManager Tests

SSH tunneling is critical for secure remote database access:

import { SSHTunnelManager } from '../../src/classes/SSHTunnelManager.js';
import { MockSSHFactory } from '../fixtures/mock-ssh.js';

describe('SSHTunnelManager', () => {
 let tunnelManager: SSHTunnelManager;

 beforeEach(() => {
 tunnelManager = new SSHTunnelManager();
 });

 afterEach(async () => {
 await tunnelManager.closeAllTunnels();
 });

 describe('tunnel creation', () => {
 test('should create SSH tunnel with password auth', async () => {
 const config = {
 ssh_host: 'bastion.example.com',
 ssh_port: 22,
 ssh_username: 'tunnel_user',
 ssh_password: 'secure_password',
 database_host: 'internal-db.local',
 database_port: 5432
 };

 const tunnel = await tunnelManager.createTunnel('test-tunnel', config);
 
 expect(tunnel).toBeDefined();
 expect(tunnel.localPort).toBeGreaterThan(1024);
 expect(tunnelManager.isConnected('test-tunnel')).toBe(true);
 });

 test('should create SSH tunnel with key auth', async () => {
 const config = {
 ssh_host: 'bastion.example.com',
 ssh_port: 22,
 ssh_username: 'tunnel_user',
 ssh_private_key: '/path/to/private/key',
 database_host: 'internal-db.local',
 database_port: 5432
 };

 const tunnel = await tunnelManager.createTunnel('key-tunnel', config);
 
 expect(tunnel).toBeDefined();
 expect(tunnel.authMethod).toBe('privateKey');
 });
 });

 describe('tunnel management', () => {
 test('should reuse existing tunnels with same configuration', async () => {
 const config = MockSSHFactory.createTunnelConfig();
 
 const tunnel1 = await tunnelManager.createTunnel('reuse-test', config);
 const tunnel2 = await tunnelManager.createTunnel('reuse-test', config);
 
 expect(tunnel1.localPort).toBe(tunnel2.localPort);
 });

 test('should manage concurrent tunnels', async () => {
 const configs = [
 MockSSHFactory.createTunnelConfig('host1'),
 MockSSHFactory.createTunnelConfig('host2'),
 MockSSHFactory.createTunnelConfig('host3')
 ];

 const tunnels = await Promise.all(
 configs.map((config, i) => 
 tunnelManager.createTunnel(`concurrent-${i}`, config)
 )
 );

 expect(tunnels).toHaveLength(3);
 expect(new Set(tunnels.map(t => t.localPort))).toHaveProperty('size', 3);
 });

 test('should cleanup tunnels properly', async () => {
 const config = MockSSHFactory.createTunnelConfig();
 await tunnelManager.createTunnel('cleanup-test', config);
 
 expect(tunnelManager.isConnected('cleanup-test')).toBe(true);
 
 await tunnelManager.closeTunnel('cleanup-test');
 
 expect(tunnelManager.isConnected('cleanup-test')).toBe(false);
 });
 });

 describe('error handling', () => {
 test('should handle SSH authentication failures', async () => {
 const invalidConfig = {
 ssh_host: 'bastion.example.com',
 ssh_port: 22,
 ssh_username: 'invalid_user',
 ssh_password: 'wrong_password',
 database_host: 'internal-db.local',
 database_port: 5432
 };

 await expect(
 tunnelManager.createTunnel('auth-fail', invalidConfig)
 ).rejects.toThrow('Authentication failed');
 });

 test('should handle network connectivity issues', async () => {
 const unreachableConfig = {
 ssh_host: 'unreachable.example.com',
 ssh_port: 22,
 ssh_username: 'user',
 ssh_password: 'password',
 database_host: 'internal-db.local',
 database_port: 5432
 };

 await expect(
 tunnelManager.createTunnel('network-fail', unreachableConfig)
 ).rejects.toThrow();
 });

 test('should recover from connection drops', async () => {
 const config = MockSSHFactory.createTunnelConfig();
 const tunnel = await tunnelManager.createTunnel('recovery-test', config);
 
 // Simulate connection drop
 tunnel.connection.emit('error', new Error('Connection lost'));
 
 // Should auto-reconnect
 await new Promise(resolve => setTimeout(resolve, 1000));
 
 expect(tunnelManager.isConnected('recovery-test')).toBe(true);
 });
 });

 describe('performance monitoring', () => {
 test('should track tunnel connection metrics', async () => {
 const config = MockSSHFactory.createTunnelConfig();
 await tunnelManager.createTunnel('metrics-test', config);
 
 const metrics = tunnelManager.getMetrics('metrics-test');
 
 expect(metrics).toBeDefined();
 expect(metrics.connectionTime).toBeGreaterThan(0);
 expect(metrics.bytesSent).toBeDefined();
 expect(metrics.bytesReceived).toBeDefined();
 });
 });
});

Database Adapter Tests

Each database adapter is thoroughly tested with consistent patterns across all implementations:

import { PostgreSQLAdapter } from '../../../src/database/adapters/postgresql.js';
import { MockDatabaseFactory } from '../../fixtures/mock-databases.js';

describe('PostgreSQLAdapter', () => {
 let adapter: PostgreSQLAdapter;
 let mockConfig: DatabaseConfig;

 beforeEach(() => {
 mockConfig = MockDatabaseFactory.createPostgreSQLConfig();
 adapter = new PostgreSQLAdapter(mockConfig);
 });

 describe('connection management', () => {
 test('should establish connection successfully', async () => {
 const connection = await adapter.connect();
 expect(connection).toBeDefined();
 expect(adapter.isConnected(connection)).toBe(true);
 });

 test('should handle connection failures gracefully', async () => {
 const invalidConfig = { ...mockConfig, host: 'invalid-host' };
 const invalidAdapter = new PostgreSQLAdapter(invalidConfig);
 
 await expect(invalidAdapter.connect()).rejects.toThrow();
 });

 test('should cleanup connections properly', async () => {
 const connection = await adapter.connect();
 await adapter.disconnect(connection);
 expect(adapter.isConnected(connection)).toBe(false);
 });
 });

 describe('query execution', () => {
 let connection: any;

 beforeEach(async () => {
 connection = await adapter.connect();
 });

 afterEach(async () => {
 if (connection) {
 await adapter.disconnect(connection);
 }
 });

 test('should execute SELECT queries successfully', async () => {
 const result = await adapter.executeQuery(
 connection,
 'SELECT 1 as test_value'
 );

 expect(result).toHaveValidQueryResult();
 expect(result.rows).toBeDefined();
 expect(result.fields).toBeDefined();
 expect(result.execution_time_ms).toBeGreaterThan(0);
 });

 test('should handle parameterized queries', async () => {
 const result = await adapter.executeQuery(
 connection,
 'SELECT $1 as param_value',
 ['test_parameter']
 );

 expect(result.rows[0].param_value).toBe('test_parameter');
 });

 test('should provide accurate row counts', async () => {
 const result = await adapter.executeQuery(
 connection,
 'SELECT generate_series(1, 5) as num'
 );

 expect(result.rowCount).toBe(5);
 expect(result.rows).toHaveLength(5);
 });
 });

 describe('schema introspection', () => {
 test('should capture complete database schema', async () => {
 const connection = await adapter.connect();
 const schema = await adapter.captureSchema(connection);

 expect(schema).toBeDefined();
 expect(schema.tables).toBeDefined();
 expect(schema.views).toBeDefined();
 expect(schema.functions).toBeDefined();

 await adapter.disconnect(connection);
 });

 test('should provide table metadata', async () => {
 const connection = await adapter.connect();
 const tables = await adapter.getTables(connection);

 expect(Array.isArray(tables)).toBe(true);
 if (tables.length > 0) {
 expect(tables[0]).toHaveProperty('name');
 expect(tables[0]).toHaveProperty('columns');
 }

 await adapter.disconnect(connection);
 });
 });

 describe('performance analysis', () => {
 test('should analyze query performance', async () => {
 const connection = await adapter.connect();
 const analysis = await adapter.analyzeQueryPerformance(
 connection,
 'SELECT * FROM pg_tables LIMIT 10'
 );

 expect(analysis).toBeDefined();
 expect(analysis.executionPlan).toBeDefined();
 expect(analysis.estimatedCost).toBeGreaterThan(0);

 await adapter.disconnect(connection);
 });
 });

 describe('error handling', () => {
 test('should handle SQL syntax errors', async () => {
 const connection = await adapter.connect();
 
 await expect(
 adapter.executeQuery(connection, 'INVALID SQL SYNTAX')
 ).rejects.toThrow();

 await adapter.disconnect(connection);
 });

 test('should handle timeout scenarios', async () => {
 const connection = await adapter.connect();
 
 // Test with a very short timeout
 await expect(
 adapter.executeQuery(
 connection, 
 'SELECT pg_sleep(2)', 
 [], 
 { timeout: 100 }
 )
 ).rejects.toThrow('timeout');

 await adapter.disconnect(connection);
 });
 });
});

Key Testing Patterns for All Adapters:

  1. Connection Lifecycle Testing
  • Successful connection establishment
  • Connection failure handling
  • Proper connection cleanup
  • Connection pooling behavior
  1. Query Execution Testing
  • Basic SELECT operations
  • Parameterized queries
  • Row count accuracy
  • Result set formatting
  • Performance tracking
  1. Schema Introspection Testing
  • Complete schema capture
  • Table metadata accuracy
  • View and function discovery
  • Index information
  1. Database-Specific Feature Testing
  • PostgreSQL: JSON/JSONB, arrays, custom types
  • MySQL: MySQL-specific functions and syntax
  • SQLite: File-based operations, pragmas
  • SQL Server: T-SQL features, procedures
  1. Error Handling Testing
  • SQL syntax errors
  • Connection timeouts
  • Permission errors
  • Resource exhaustion

Integration Testing

MCP Server Integration Tests

Test the complete MCP server workflow:

import { SQLMCPServer } from '../../src/classes/SQLMCPServer.js';

describe('SQLMCPServer Integration', () => {
 let server: SQLMCPServer;
 let testConfig: any;

 beforeEach(async () => {
 testConfig = {
 databases: {
 test: {
 type: 'sqlite',
 file: ':memory:',
 select_only: true
 }
 },
 security: {
 max_joins: 10,
 max_subqueries: 5
 }
 };

 server = new SQLMCPServer(testConfig);
 await server.initialize();
 });

 afterEach(async () => {
 await server.shutdown();
 });

 test('should execute SQL query through MCP protocol', async () => {
 const mcpRequest = {
 jsonrpc: '2.0',
 id: 1,
 method: 'tools/call',
 params: {
 name: 'sql_query',
 arguments: {
 database: 'test',
 query: 'SELECT 1 as test_value'
 }
 }
 };

 const result = await server.callTool(mcpRequest.params.name, mcpRequest.params.arguments);

 expect(result.isError).toBe(false);
 expect(result.content[0].text).toContain('test_value');
 });

 test('should reject unsafe queries', async () => {
 const mcpRequest = {
 jsonrpc: '2.0',
 id: 2,
 method: 'tools/call',
 params: {
 name: 'sql_query',
 arguments: {
 database: 'test',
 query: 'DROP TABLE users'
 }
 }
 };

 const result = await server.callTool(mcpRequest.params.name, mcpRequest.params.arguments);

 expect(result.isError).toBe(true);
 expect(result.content[0].text).toContain('DROP');
 });
});

Database-Specific Integration Tests

Test each database type:

describe('Database Integration Tests', () => {
 describe('PostgreSQL Integration', () => {
 test('should connect and query PostgreSQL', async () => {
 // Test with actual PostgreSQL connection if available
 const config = {
 type: 'postgresql',
 host: process.env.PG_HOST || 'localhost',
 database: process.env.PG_DB || 'test',
 username: process.env.PG_USER || 'postgres',
 password: process.env.PG_PASSWORD || 'password'
 };

 if (!process.env.CI && process.env.PG_HOST) {
 const adapter = new PostgreSQLAdapter(config);
 const connection = await adapter.connect();
 
 const result = await adapter.executeQuery(
 connection, 
 'SELECT version() as version'
 );
 
 expect(result.rows).toHaveLength(1);
 expect(result.rows[0].version).toContain('PostgreSQL');
 
 await adapter.disconnect(connection);
 }
 });
 });
});

Custom Test Matchers

The project provides custom Jest matchers for domain-specific assertions:

SQL Query Matchers

// Check if string is a valid SQL query
expect(query).toBeValidQuery();

// Check if query contains specific SQL keywords
expect(query).toContainSqlKeyword('SELECT');
expect(query).toContainSqlKeyword('JOIN');

MCP Protocol Matchers

// Validate MCP response structure
expect(response).toBeValidMCPResponse();

// Validate query result structure
expect(result).toHaveValidQueryResult();

Usage Examples

test('should return valid MCP response', async () => {
 const response = await server.handleSQLQuery('test', 'SELECT 1');
 
 expect(response).toBeValidMCPResponse();
 expect(response.result.content[0].text).toContain('Query executed');
});

test('should return proper query result', async () => {
 const result = await adapter.executeQuery(connection, 'SELECT * FROM users');
 
 expect(result).toHaveValidQueryResult();
 expect(result.rows).toBeDefined();
 expect(result.execution_time_ms).toBeGreaterThan(0);
});

Test Data and Fixtures

Sample Queries (tests/fixtures/sample-queries.ts)

Comprehensive collection of SQL queries for testing:

import { SampleQueries } from '../fixtures/sample-queries.js';

// Use predefined safe queries
const safeQueries = SampleQueries.getSafeQueries();

// Use unsafe queries for security testing
const unsafeQueries = SampleQueries.getUnsafeQueries();

// Use complexity test queries
const complexQueries = SampleQueries.getComplexityTestQueries();

test('should handle complex analytical queries', async () => {
 const query = SampleQueries.analyticalQueries.cohortAnalysis;
 const result = securityManager.validateSelectOnlyQuery(query);
 expect(result.allowed).toBe(true);
});

Mock Database Configurations

import { TestConfigs } from '../fixtures/test-configs.js';

test('should validate various database configurations', () => {
 const configs = TestConfigs.getAllDatabaseConfigs();
 
 for (const [name, config] of Object.entries(configs)) {
 const validation = connectionManager.validateConfig(name, config);
 expect(validation.isValid).toBe(true);
 }
});

Testing Best Practices

Test Organization

describe('Component/Feature Name', () => {
 // Setup and teardown
 beforeEach(() => { /* setup */ });
 afterEach(() => { /* cleanup */ });

 describe('Specific functionality', () => {
 test('should do something specific', () => {
 // Arrange
 const input = 'test input';
 
 // Act
 const result = functionUnderTest(input);
 
 // Assert
 expect(result).toBe('expected output');
 });
 });

 describe('Error scenarios', () => {
 test('should handle invalid input gracefully', () => {
 expect(() => functionUnderTest(null))
 .toThrow('Invalid input');
 });
 });
});

Async Testing

test('should handle async operations', async () => {
 const promise = asyncFunction();
 
 await expect(promise).resolves.toBeDefined();
 // or
 await expect(promise).rejects.toThrow('Error message');
});

test('should timeout appropriately', async () => {
 const slowOperation = new Promise(resolve => 
 setTimeout(resolve, 5000)
 );
 
 await expect(slowOperation).rejects.toThrow('timeout');
}, 10000); // 10 second timeout

Mock Management

describe('Component with dependencies', () => {
 let mockDependency: jest.Mocked<DependencyType>;

 beforeEach(() => {
 mockDependency = {
 method1: jest.fn(),
 method2: jest.fn().mockResolvedValue('mock result')
 } as jest.Mocked<DependencyType>;
 });

 afterEach(() => {
 jest.clearAllMocks();
 });

 test('should use dependency correctly', async () => {
 const component = new Component(mockDependency);
 await component.doSomething();
 
 expect(mockDependency.method1).toHaveBeenCalledWith('expected argument');
 expect(mockDependency.method2).toHaveBeenCalledTimes(1);
 });
});

Performance Testing

Benchmarking Tests

describe('Performance Tests', () => {
 test('should execute queries within performance threshold', async () => {
 const startTime = Date.now();
 
 await adapter.executeQuery(connection, 'SELECT * FROM large_table LIMIT 1000');
 
 const duration = Date.now() - startTime;
 expect(duration).toBeLessThan(5000); // 5 second threshold
 });

 test('should handle concurrent connections efficiently', async () => {
 const promises = Array.from({ length: 10 }, (_, i) => 
 adapter.executeQuery(connection, `SELECT ${i} as test_value`)
 );
 
 const results = await Promise.all(promises);
 
 expect(results).toHaveLength(10);
 results.forEach((result, i) => {
 expect(result.rows[0].test_value).toBe(i);
 });
 });
});

Memory Leak Testing

test('should not leak memory with repeated operations', async () => {
 const initialMemory = process.memoryUsage().heapUsed;
 
 // Perform many operations
 for (let i = 0; i < 1000; i++) {
 securityManager.validateSelectOnlyQuery('SELECT 1');
 }
 
 // Force garbage collection
 if (global.gc) global.gc();
 
 const finalMemory = process.memoryUsage().heapUsed;
 const memoryIncrease = finalMemory - initialMemory;
 
 // Should not increase by more than 50MB
 expect(memoryIncrease).toBeLessThan(50 * 1024 * 1024);
});

Continuous Integration

GitHub Actions Integration

name: Test Suite
on: [push, pull_request]

jobs:
 test:
 runs-on: ubuntu-latest
 
 services:
 postgres:
 image: postgres:13
 env:
 POSTGRES_PASSWORD: password
 options: >-
 --health-cmd pg_isready
 --health-interval 10s
 --health-timeout 5s
 --health-retries 5
 
 steps:
 - uses: actions/checkout@v3
 
 - name: Setup Node.js
 uses: actions/setup-node@v3
 with:
 node-version: '24'
 cache: 'npm'
 
 - name: Install dependencies
 run: npm ci
 
 - name: Run linting
 run: npm run lint:check
 
 - name: Run type checking
 run: npm run type-check
 
 - name: Run tests
 run: npm run test:coverage
 env:
 PG_HOST: localhost
 PG_USER: postgres
 PG_PASSWORD: password
 PG_DB: postgres
 
 - name: Upload coverage
 uses: codecov/codecov-action@v3
 with:
 file: ./coverage/lcov.info

Test Scripts in package.json

{
 "scripts": {
 "test": "jest --passWithNoTests",
 "test:unit": "jest tests/unit --passWithNoTests",
 "test:integration": "jest tests/integration --passWithNoTests",
 "test:watch": "jest --watch --passWithNoTests",
 "test:coverage": "jest --coverage --passWithNoTests",
 "test:ci": "jest --ci --coverage --watchAll=false"
 }
}

Debugging Tests

Debug Configuration

# Run tests with verbose output
VERBOSE_TESTS=1 npm test

# Run specific test file
npm test -- security-manager.test.ts

# Run tests matching pattern
npm test -- --testNamePattern="should validate"

# Debug with Node.js inspector
node --inspect-brk node_modules/.bin/jest --runInBand

VS Code Debug Configuration

{
 "type": "node",
 "request": "launch",
 "name": "Debug Jest Tests",
 "program": "${workspaceFolder}/node_modules/.bin/jest",
 "args": ["--runInBand"],
 "console": "integratedTerminal",
 "internalConsoleOptions": "neverOpen",
 "disableOptimisticBPs": true
}

Common Debugging Techniques

test('debug test execution', async () => {
 console.log('Test starting...');
 
 const result = await functionUnderTest();
 console.log('Result:', JSON.stringify(result, null, 2));
 
 expect(result).toBeDefined();
});

// Use debugger statement
test('interactive debugging', () => {
 debugger; // Will break here when debugging
 const result = processData();
 expect(result).toBe('expected');
});

Coverage Requirements

Current Coverage Thresholds

The project maintains enterprise-grade test coverage standards:

  • Overall Coverage: 90%+ (Current: 92%)
  • Statements: 90%+ (Current: 92%)
  • Branches: 85%+ (Current: 89%)
  • Functions: 95%+ (Current: 95%)
  • Lines: 90%+ (Current: 92%)

Coverage Configuration

The Jest configuration enforces these thresholds:

{
 "collectCoverageFrom": [
 "src/**/*.ts",
 "!src/**/*.d.ts",
 "!src/setup/**/*",
 "!src/index.ts"
 ],
 "coverageThreshold": {
 "global": {
 "branches": 85,
 "functions": 95,
 "lines": 90,
 "statements": 90
 },
 "src/classes/": {
 "branches": 90,
 "functions": 100,
 "lines": 95,
 "statements": 95
 },
 "src/database/adapters/": {
 "branches": 88,
 "functions": 95,
 "lines": 92,
 "statements": 92
 }
 },
 "coverageReporters": [
 "text",
 "text-summary", 
 "lcov",
 "html"
 ]
}

Per-Component Coverage Standards

Component Coverage Target Current Status
Core Classes 95%+ 96% Exceeds
Database Adapters 90%+ 94% Exceeds
Security Components 98%+ 98% Meets
SSH Components 85%+ 87% Meets
Utility Functions 90%+ 93% Exceeds

New Code Requirements

All new contributions must meet higher standards:

  • New Functions: 100% coverage required
  • New Classes: 95%+ coverage required
  • Bug Fixes: Must include regression tests
  • Refactoring: Coverage cannot decrease

Coverage Reports

# Generate coverage report
npm run test:coverage

# View HTML coverage report
open coverage/lcov-report/index.html

# View text summary
cat coverage/lcov.info

Testing Checklist

Before Committing

  • All tests pass: npm test
  • Linting passes: npm run lint:check
  • Type checking passes: npm run type-check
  • Coverage meets thresholds: npm run test:coverage
  • Integration tests pass: npm run test:integration

Writing New Tests

  • Test covers both success and error scenarios
  • Achieves 90%+ line coverage (100% for new functions)
  • Uses appropriate test data from fixtures
  • Includes performance testing for database operations
  • Tests concurrent operation handling where applicable
  • Follows project naming conventions
  • Uses custom matchers when appropriate
  • Properly mocks external dependencies
  • Includes both unit and integration tests
  • Tests all edge cases and boundary conditions

Review Checklist

  • Tests are focused and test one thing
  • Test names clearly describe expected behavior
  • Setup and teardown is proper
  • No hardcoded values that should be configurable
  • Tests are deterministic and not flaky
  • Edge cases are covered

Troubleshooting

Common Issues

Tests Timeout

Error: Timeout - Async callback was not invoked within the 30000ms timeout

Solutions:

  • Increase timeout: jest.setTimeout(60000)
  • Check for unresolved promises
  • Ensure proper cleanup in afterEach

Mock Issues

Error: Cannot spy on a property that is not defined

Solutions:

  • Ensure object exists before mocking
  • Use proper mock implementation
  • Check import paths

Memory Issues

Error: JavaScript heap out of memory

Solutions:

  • Run tests with more memory: node --max-old-space-size=4096
  • Check for memory leaks in tests
  • Use --runInBand to reduce parallel execution

Conclusion

The Argos testing strategy provides comprehensive coverage through:

  • Multiple test types (unit, integration, performance)
  • Custom matchers for domain-specific validation
  • Comprehensive fixtures for realistic testing scenarios
  • Automated CI/CD integration for continuous quality assurance
  • Detailed debugging support for efficient development

This testing approach ensures high code quality, reliability, and maintainability while supporting rapid development and refactoring.

For additional help: