Enterprise-ready test database utilities for PostgreSQL and MongoDB
npm install @kitiumai/test-db> Enterprise-Grade Database Testing Infrastructure
A comprehensive, production-ready testing framework for PostgreSQL and MongoDB that matches the sophistication of big tech database testing infrastructure. Built for teams that need hermetic, observable, and scalable database testing at enterprise scale.
@kitiumai/test-db is a complete database testing ecosystem that provides:
- Hermetic Testing Environment: Docker-based isolated database instances
- Enterprise Observability: Distributed tracing, metrics, and alerting
- AI-Powered Data Generation: Realistic test data with business rule compliance
- Chaos Engineering: Failure injection and resilience testing
- Multi-Database Coordination: Cross-database transaction testing
- Performance Benchmarking: Load testing and performance analysis
- Cloud Integration: AWS RDS, Google Cloud SQL, Azure Database support
Traditional database testing approaches suffer from:
- Data Leakage: Tests contaminate each other with shared state
- Slow Setup: Manual database provisioning and seeding
- Inconsistent Environments: Different results across CI/local environments
- Limited Observability: No visibility into database performance or failures
- Manual Chaos Testing: No systematic way to test failure scenarios
- Poor Data Quality: Fake data that doesn't reflect real-world patterns
@kitiumai/test-db solves these problems with:
- Zero-Configuration Isolation: Automatic per-test database isolation
- Production-Grade Observability: Full tracing and metrics collection
- AI-Generated Realistic Data: Statistically valid test datasets
- Automated Chaos Engineering: Systematic failure injection testing
- Cloud-Native Architecture: Multi-region and cloud provider support
- Performance Intelligence: Automated benchmarking and optimization
| Feature | @kitiumai/test-db | testcontainers | mongodb-memory-server | pg-mem | database-cleaner |
|---------|------------------|----------------|----------------------|--------|------------------|
| PostgreSQL Support | ✅ Full | ✅ Container | ❌ | ✅ In-memory | ❌ |
| MongoDB Support | ✅ Full | ✅ Container | ✅ Memory | ❌ | ❌ |
| Hermetic Isolation | ✅ Docker + Per-test | ✅ Container | ✅ Memory | ✅ In-memory | ❌ |
| Enterprise Observability | ✅ Tracing + Metrics | ❌ | ❌ | ❌ | ❌ |
| AI Data Generation | ✅ Statistical models | ❌ | ❌ | ❌ | ❌ |
| Chaos Engineering | ✅ Failure injection | ❌ | ❌ | ❌ | ❌ |
| Cloud Integration | ✅ AWS/GCP/Azure | ❌ | ❌ | ❌ | ❌ |
| Performance Benchmarking | ✅ Load testing | ❌ | ❌ | ❌ | ❌ |
| Multi-DB Coordination | ✅ Saga patterns | ❌ | ❌ | ❌ | ❌ |
| Schema Migration Testing | ✅ Drift detection | ❌ | ❌ | ❌ | ❌ |
| Production Ready | ✅ Enterprise-grade | ⚠️ Dev-focused | ⚠️ Dev-focused | ⚠️ Limited | ⚠️ Basic |
``bash`
npm install @kitiumai/test-dbor
yarn add @kitiumai/test-dbor
pnpm add @kitiumai/test-db
`typescript
import { createPostgresTestDB } from '@kitiumai/test-db';
describe('User Service', () => {
let db: PostgresTestDB;
beforeAll(async () => {
db = createPostgresTestDB({
host: 'localhost',
port: 5432,
username: 'postgres',
password: 'password',
database: 'test_db',
});
await db.connect();
});
afterAll(async () => {
await db.disconnect();
});
it('should create and retrieve user', async () => {
// Create table
await db.query(\
CREATE TABLE users (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL
)
\);
// Insert user
await db.query(
'INSERT INTO users (name, email) VALUES ($1, $2)',
['John Doe', 'john@example.com']
);
// Retrieve user
const result = await db.query('SELECT * FROM users WHERE email = $1', ['john@example.com']);
expect(result.rows).toHaveLength(1);
expect(result.rows[0].name).toBe('John Doe');
});
});
`
`typescript
import { DockerContainerManager, HermeticDatabaseManager } from '@kitiumai/test-db/utils';
describe('Hermetic Database Tests', () => {
let hermeticDB: HermeticDatabaseManager;
beforeAll(async () => {
const dockerManager = new DockerContainerManager();
hermeticDB = new HermeticDatabaseManager(dockerManager);
await hermeticDB.startDatabase({
type: 'postgres',
version: '15',
port: 5433,
});
});
afterAll(async () => {
await hermeticDB.stopDatabase();
});
it('runs in complete isolation', async () => {
// Database is completely isolated - no conflicts with other tests
const db = hermeticDB.getClient();
// ... your tests
});
});
`
`typescript
import { generateRealisticTestData, generateEdgeCaseTestData } from '@kitiumai/test-db/utils';
describe('User API with Realistic Data', () => {
it('handles realistic user data', async () => {
const userData = await generateRealisticTestData({
table: 'users',
count: 100,
schema: {
id: { type: 'integer' },
name: { type: 'varchar', nullable: false },
email: { type: 'varchar', nullable: false },
age: { type: 'integer', nullable: true },
created_at: { type: 'timestamp' },
},
patterns: {
name: { type: 'realistic' },
email: { type: 'realistic' },
},
});
// userData.records contains 100 realistic user entries
expect(userData.records).toHaveLength(100);
expect(userData.metadata.aiEnhanced).toBe(true);
});
it('handles edge cases', async () => {
const edgeCaseData = await generateEdgeCaseTestData({
table: 'users',
count: 10,
schema: {
name: { type: 'varchar', nullable: true, constraints: ['max_length:255'] },
email: { type: 'varchar', nullable: false },
},
});
// Test with null values, empty strings, max lengths, etc.
// ... your edge case tests
});
});
`
`typescript
import { DatabaseChaosOrchestrator } from '@kitiumai/test-db/utils';
describe('Resilient User Service', () => {
let chaos: DatabaseChaosOrchestrator;
beforeEach(() => {
chaos = new DatabaseChaosOrchestrator(db);
});
it('handles connection failures', async () => {
// Inject connection failure
await chaos.injectFailure({
type: 'connection_drop',
duration: 5000, // 5 seconds
probability: 1.0,
});
// Your service should handle this gracefully
await expect(userService.getUser(1)).rejects.toThrow('Connection failed');
});
it('handles slow queries', async () => {
// Inject latency
await chaos.injectLatency({
operation: 'SELECT',
delay: 3000, // 3 second delay
jitter: 500,
});
const start = Date.now();
await userService.getUser(1);
const duration = Date.now() - start;
expect(duration).toBeGreaterThan(2500); // Allow for some jitter
});
});
`
`typescript
import { DatabaseBenchmarkSuite } from '@kitiumai/test-db/utils';
describe('Database Performance', () => {
let benchmark: DatabaseBenchmarkSuite;
beforeAll(() => {
benchmark = new DatabaseBenchmarkSuite(db);
});
it('meets performance requirements', async () => {
const results = await benchmark.runBenchmark({
name: 'user_queries',
operations: [
{
name: 'select_user_by_id',
query: 'SELECT * FROM users WHERE id = $1',
params: [1],
iterations: 1000,
},
{
name: 'select_users_paginated',
query: 'SELECT * FROM users LIMIT $1 OFFSET $2',
params: [50, 0],
iterations: 500,
},
],
});
// Assert performance requirements
expect(results.operations[0].avgLatency).toBeLessThan(10); // < 10ms
expect(results.operations[1].avgLatency).toBeLessThan(25); // < 25ms
expect(results.throughput).toBeGreaterThan(100); // > 100 ops/sec
});
});
`
`typescript
import { AdvancedObservabilityManager, createDatabaseMetrics } from '@kitiumai/test-db/utils';
describe('Observable Database Operations', () => {
let observability: AdvancedObservabilityManager;
let metrics: ReturnType
beforeAll(() => {
observability = new AdvancedObservabilityManager({
enableMetrics: true,
enableTracing: true,
enableLogging: true,
});
metrics = createDatabaseMetrics(observability);
});
it('tracks query performance', async () => {
// Automatically track metrics
metrics.recordQueryLatency(15.5, 'SELECT', 'users');
metrics.recordConnectionPoolUsage(8, 20, 'users');
const dashboard = await observability.getDashboardData();
expect(dashboard.metrics.queryLatency).toContainEqual(
expect.objectContaining({
name: 'query.latency',
value: 15.5,
tags: { queryType: 'SELECT', database: 'users' },
})
);
});
});
`
#### PostgreSQL
`typescript`
import {
createPostgresTestDB,
PostgresTestDB,
countRecords,
createTable,
deleteData,
dropTable,
fetchData,
insertData,
resetSequence,
updateData,
} from '@kitiumai/test-db';
#### MongoDB
`typescript`
import {
createMongoDBTestDB,
MongoDBTestDB,
aggregate,
clearCollection,
countDocuments,
createIndex,
deleteDocuments,
findDocuments,
findOneDocument,
insertDocuments,
updateDocuments,
} from '@kitiumai/test-db';
typescript
import {
createMongoPreset,
createPostgresPreset,
createTestDbConfigBuilder,
getMongoDBConfig,
getPostgresConfig,
sanitizeMongoDBConfig,
sanitizePostgresConfig,
TestDbConfigBuilder,
TestEnvironmentPreset,
validateMongoDBConfig,
validatePostgresConfig,
} from '@kitiumai/test-db/utils/config';
`$3
typescript
import {
installMongoTestHarness,
installPostgresTestHarness,
createPostgresTransactionalHarness,
withPerTestMongoDatabase,
withWorkerPostgresDatabase,
} from '@kitiumai/test-db/utils/frameworks';
`$3
typescript
import {
withTemporaryMongoDatabase,
withTemporaryPostgresDatabase,
} from '@kitiumai/test-db/utils/lifecycle';
`$3
typescript
import {
applyMongoFixtures,
applySqlFixtures,
snapshotTableSchema,
} from '@kitiumai/test-db/utils/fixtures';
`$3
typescript
import {
DockerContainerManager,
HermeticDatabaseManager,
} from '@kitiumai/test-db/utils/docker';
`$3
typescript
import {
SchemaMigrationTester,
} from '@kitiumai/test-db/utils/schema';
`$3
typescript
import {
DatabaseChaosOrchestrator,
} from '@kitiumai/test-db/utils/chaos';
`$3
typescript
import {
MultiDatabaseCoordinator,
} from '@kitiumai/test-db/utils/coordination';
`$3
typescript
import {
DatabaseBenchmarkSuite,
} from '@kitiumai/test-db/utils/benchmark';
`$3
typescript
import {
CloudDatabaseManager,
AWSRDSManager,
GoogleCloudSQLManager,
AzureDatabaseManager,
} from '@kitiumai/test-db/utils/cloud';
`$3
typescript
import {
AIDataGenerator,
generateRealisticTestData,
generateEdgeCaseTestData,
generatePerformanceTestData,
generateRelationalTestData,
learnDataPatterns,
} from '@kitiumai/test-db/utils/ai-data';
`$3
typescript
import {
AdvancedObservabilityManager,
createDatabaseMetrics,
createDatabaseTracing,
createDatabaseLogging,
defaultAlertingRules,
} from '@kitiumai/test-db/utils/observability';
`$3
typescript
import {
createLogger,
withSpan,
} from '@kitiumai/test-db/utils';
`Advanced Examples
$3
typescript
import {
HermeticDatabaseManager,
AIDataGenerator,
DatabaseChaosOrchestrator,
AdvancedObservabilityManager,
DatabaseBenchmarkSuite,
} from '@kitiumai/test-db/utils';describe('Complete User Service Test Suite', () => {
let hermeticDB: HermeticDatabaseManager;
let aiGenerator: AIDataGenerator;
let chaos: DatabaseChaosOrchestrator;
let observability: AdvancedObservabilityManager;
let benchmark: DatabaseBenchmarkSuite;
beforeAll(async () => {
// 1. Start hermetic database
hermeticDB = new HermeticDatabaseManager(new DockerContainerManager());
await hermeticDB.startDatabase({ type: 'postgres', version: '15' });
// 2. Set up observability
observability = new AdvancedObservabilityManager();
observability.setupAlertingRules(defaultAlertingRules);
// 3. Initialize AI data generator
aiGenerator = new AIDataGenerator();
// 4. Set up chaos engineering
chaos = new DatabaseChaosOrchestrator(hermeticDB.getClient());
// 5. Initialize benchmarking
benchmark = new DatabaseBenchmarkSuite(hermeticDB.getClient());
});
describe('Happy Path Tests', () => {
it('creates users with realistic data', async () => {
const testData = await aiGenerator.generateRealisticTestData({
table: 'users',
count: 1000,
schema: { / schema definition / },
});
// Insert test data and verify
for (const user of testData.records) {
await hermeticDB.getClient().query(/ insert query /);
}
const count = await hermeticDB.getClient().query('SELECT COUNT(*) FROM users');
expect(parseInt(count.rows[0].count)).toBe(1000);
});
});
describe('Resilience Tests', () => {
it('handles database failures gracefully', async () => {
// Inject chaos
await chaos.injectFailure({
type: 'connection_timeout',
duration: 2000,
});
// Test service behavior during failure
await expect(userService.createUser(testUser)).rejects.toThrow();
});
});
describe('Performance Tests', () => {
it('meets SLA requirements', async () => {
const results = await benchmark.runBenchmark({
name: 'user_operations',
operations: [
{ name: 'create_user', / ... / },
{ name: 'get_user', / ... / },
{ name: 'update_user', / ... / },
],
});
expect(results.operations.every(op => op.avgLatency < 50)).toBe(true);
});
});
afterAll(async () => {
await hermeticDB.stopDatabase();
observability.shutdown();
});
});
`$3
typescript
import { CloudDatabaseManager } from '@kitiumai/test-db/utils';describe('Multi-Region User Service', () => {
let primaryDB: CloudDatabaseManager;
let replicaDB: CloudDatabaseManager;
beforeAll(async () => {
// Primary in us-east-1
primaryDB = new CloudDatabaseManager({
provider: 'aws',
region: 'us-east-1',
instance: 'primary-db',
});
// Read replica in us-west-2
replicaDB = new CloudDatabaseManager({
provider: 'aws',
region: 'us-west-2',
instance: 'replica-db',
});
await Promise.all([
primaryDB.connect(),
replicaDB.connect(),
]);
});
it('replicates data across regions', async () => {
// Write to primary
await primaryDB.execute('INSERT INTO users (name) VALUES ($1)', ['John']);
// Wait for replication (in real scenario)
await new Promise(resolve => setTimeout(resolve, 5000));
// Read from replica
const result = await replicaDB.query('SELECT * FROM users WHERE name = $1', ['John']);
expect(result.rows).toHaveLength(1);
});
});
``We welcome contributions! Please see our Contributing Guide for details.
MIT © KitiumAI