@joystick.js/db-canary 0.0.0-canary.2299 → 0.0.0-canary.2301

package/tests/common_test_utilities.js

@@ -0,0 +1,1008 @@
+/**
+ * @fileoverview Common test utilities to eliminate code duplication across test files.
+ * 
+ * Provides standardized patterns for server management, client creation, authentication,
+ * test data generation, and advanced test environment setup to improve test reliability
+ * and maintainability across the entire JoystickDB test suite.
+ */
+
+import joystickdb from '../src/client/index.js';
+import { create_server } from '../src/server/index.js';
+import { 
+  create_isolated_test_context, 
+  wait_for_condition, 
+  retry_operation,
+  allocate_test_port 
+} from './test_helpers.js';
+import { set_storage_engine, reset_auth_state } from '../src/server/lib/user_auth_manager.js';
+import { get_database, initialize_database } from '../src/server/lib/query_engine.js';
+import create_logger from '../src/server/lib/logger.js';
+
+const { create_context_logger } = create_logger('common_test_utilities');
+
+/**
+ * Default test configuration constants
+ */
+const TEST_CONFIG = {
+  DEFAULT_TIMEOUT: 10000,
+  CLIENT_CONNECT_TIMEOUT: 5000,
+  AUTH_TIMEOUT: 5000,
+  SERVER_READY_TIMEOUT: 3000,
+  CLEANUP_TIMEOUT: 5000,
+  DEFAULT_TEST_CREDENTIALS: {
+    username: 'admin',
+    password: 'admin123',
+    email: 'admin@test.com'
+  },
+  CLIENT_OPTIONS: {
+    reconnect: false,
+    timeout: 10000
+  }
+};
+
+// =============================================================================
+// SERVER MANAGEMENT UTILITIES
+// =============================================================================
+
+/**
+ * Ensures the storage engine is properly initialized for authentication operations.
+ * This prevents "storage_engine.get is not a function" errors in tests.
+ * @returns {Promise<void>}
+ */
+const ensure_storage_engine_initialized = async () => {
+  const log = create_context_logger();
+  
+  try {
+    // Get the database instance and set it as the storage engine
+    const db = get_database();
+    set_storage_engine(db);
+    log.debug('Storage engine initialized for authentication operations');
+  } catch (error) {
+    // If database isn't initialized yet, try to initialize it
+    try {
+      const test_database_path = `./test_data_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+      const db = await initialize_database(test_database_path);
+      set_storage_engine(db);
+      log.debug('Database and storage engine initialized for authentication operations', { 
+        database_path: test_database_path 
+      });
+    } catch (init_error) {
+      log.warn('Failed to initialize storage engine for authentication', { 
+        error: init_error.message 
+      });
+      throw init_error;
+    }
+  }
+};
+
+/**
+ * Creates and starts a test server with comprehensive options and health checking.
+ * @param {Object} [options={}] - Server creation options
+ * @param {number} [options.port] - Specific port to use (will allocate if not provided)
+ * @param {string} [options.test_name] - Test name for port allocation tracking
+ * @param {boolean} [options.wait_for_ready=true] - Wait for server readiness before returning
+ * @param {number} [options.ready_timeout=3000] - Timeout for server readiness check
+ * @param {Object} [options.server_config] - Server configuration overrides
+ * @param {boolean} [options.ensure_storage_engine=true] - Ensure storage engine is initialized
+ * @returns {Promise<Object>} Server context with server instance, port, and cleanup function
+ */
+const create_test_server = async (options = {}) => {
+  const log = create_context_logger();
+  const test_name = options.test_name || `server_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+  
+  // Allocate port if not provided
+  const port = options.port || await allocate_test_port(test_name);
+  
+  try {
+    // Set server configuration environment
+    if (options.server_config) {
+      process.env.JOYSTICK_DB_SETTINGS = JSON.stringify({
+        port: port,
+        ...options.server_config
+      });
+    }
+    
+    // Create server instance
+    const server = await create_server();
+    
+    // Ensure storage engine is initialized for authentication operations
+    if (options.ensure_storage_engine !== false) {
+      await ensure_storage_engine_initialized();
+    }
+    
+    // Start server
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`Server startup timeout after ${TEST_CONFIG.SERVER_READY_TIMEOUT}ms`));
+      }, TEST_CONFIG.SERVER_READY_TIMEOUT);
+      
+      server.listen(port, (error) => {
+        clearTimeout(timeout);
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    });
+    
+    // Wait for server readiness if requested
+    if (options.wait_for_ready !== false) {
+      const ready_timeout = options.ready_timeout || TEST_CONFIG.SERVER_READY_TIMEOUT;
+      await wait_for_server_ready(port, ready_timeout);
+    }
+    
+    // Create cleanup function
+    const cleanup = async () => {
+      await cleanup_test_server(server, port, test_name);
+    };
+    
+    const server_context = {
+      server,
+      port,
+      test_name,
+      cleanup
+    };
+    
+    log.debug('Test server created successfully', { 
+      test_name, 
+      port,
+      wait_for_ready: options.wait_for_ready !== false,
+      storage_engine_ensured: options.ensure_storage_engine !== false
+    });
+    
+    return server_context;
+    
+  } catch (error) {
+    log.error('Failed to create test server', {
+      test_name,
+      port,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+/**
+ * Waits for server to be ready by attempting to connect.
+ * More reliable than arbitrary timeouts.
+ * @param {number} port - Server port to check
+ * @param {number} [timeout=3000] - Maximum time to wait
+ * @returns {Promise<boolean>} True if server is ready
+ */
+const wait_for_server_ready = async (port, timeout = TEST_CONFIG.SERVER_READY_TIMEOUT) => {
+  const log = create_context_logger();
+  
+  const is_server_ready = async () => {
+    try {
+      const net = await import('net');
+      return new Promise((resolve) => {
+        const socket = net.createConnection({ port, host: '127.0.0.1' });
+        
+        socket.on('connect', () => {
+          socket.destroy();
+          resolve(true);
+        });
+        
+        socket.on('error', () => {
+          socket.destroy();
+          resolve(false);
+        });
+        
+        // Short timeout for individual connection attempts
+        setTimeout(() => {
+          socket.destroy();
+          resolve(false);
+        }, 200);
+      });
+    } catch (error) {
+      return false;
+    }
+  };
+  
+  const ready = await wait_for_condition(
+    is_server_ready,
+    timeout,
+    100,
+    `server readiness on port ${port}`
+  );
+  
+  if (ready) {
+    log.debug('Server ready', { port });
+  } else {
+    log.warn('Server readiness check timeout', { port, timeout });
+  }
+  
+  return ready;
+};
+
+/**
+ * Properly shuts down and cleans up a test server.
+ * @param {Object} server - Server instance to cleanup
+ * @param {number} port - Port to release
+ * @param {string} test_name - Test name for tracking
+ * @returns {Promise<void>}
+ */
+const cleanup_test_server = async (server, port, test_name) => {
+  const log = create_context_logger();
+  
+  try {
+    log.debug('Starting server cleanup', { test_name, port });
+    
+    // Close server with timeout
+    if (server && typeof server.close === 'function') {
+      await Promise.race([
+        new Promise((resolve) => {
+          server.close(resolve);
+        }),
+        new Promise((_, reject) => {
+          setTimeout(() => reject(new Error('Server close timeout')), TEST_CONFIG.CLEANUP_TIMEOUT);
+        })
+      ]);
+    }
+    
+    // Perform any additional server cleanup
+    if (server && typeof server.cleanup === 'function') {
+      await server.cleanup();
+    }
+    
+    log.debug('Server cleanup completed', { test_name, port });
+    
+  } catch (error) {
+    log.warn('Error during server cleanup', {
+      test_name,
+      port,
+      error: error.message
+    });
+  }
+};
+
+/**
+ * Checks server health by pinging it.
+ * @param {number} port - Server port
+ * @param {Object} [options={}] - Health check options
+ * @returns {Promise<Object>} Health status information
+ */
+const get_server_health = async (port, options = {}) => {
+  const log = create_context_logger();
+  const timeout = options.timeout || 2000;
+  
+  try {
+    const client = joystickdb.client({
+      port,
+      ...TEST_CONFIG.CLIENT_OPTIONS,
+      timeout
+    });
+    
+    // Wait for connection
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Connection timeout')), timeout);
+      client.on('connect', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      client.on('error', (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+    
+    // Perform ping
+    const ping_result = await client.ping();
+    client.disconnect();
+    
+    return {
+      healthy: true,
+      port,
+      ping_result,
+      checked_at: new Date().toISOString()
+    };
+    
+  } catch (error) {
+    log.debug('Server health check failed', { port, error: error.message });
+    return {
+      healthy: false,
+      port,
+      error: error.message,
+      checked_at: new Date().toISOString()
+    };
+  }
+};
+
+// =============================================================================
+// CLIENT HELPER FUNCTIONS
+// =============================================================================
+
+/**
+ * Creates a standardized test client with comprehensive options.
+ * @param {number} port - Server port to connect to
+ * @param {Object} [options={}] - Client creation options
+ * @param {Object} [options.authentication] - Authentication credentials
+ * @param {boolean} [options.auto_connect=true] - Whether to auto-connect
+ * @param {number} [options.connect_timeout] - Connection timeout
+ * @param {Object} [options.client_options] - Additional client options
+ * @returns {Promise<Object>} Client instance with metadata
+ */
+const create_test_client = async (port, options = {}) => {
+  const log = create_context_logger();
+  
+  const client_options = {
+    port,
+    ...TEST_CONFIG.CLIENT_OPTIONS,
+    ...options.client_options
+  };
+  
+  // Add authentication if provided
+  if (options.authentication) {
+    client_options.authentication = options.authentication;
+  }
+  
+  // Create client
+  const client = joystickdb.client(client_options);
+  
+  // Handle auto-connection
+  if (options.auto_connect !== false) {
+    const connect_timeout = options.connect_timeout || TEST_CONFIG.CLIENT_CONNECT_TIMEOUT;
+    
+    await Promise.race([
+      new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          reject(new Error(`Client connection timeout after ${connect_timeout}ms`));
+        }, connect_timeout);
+        
+        client.on('connect', () => {
+          clearTimeout(timer);
+          resolve();
+        });
+        
+        client.on('error', (error) => {
+          clearTimeout(timer);
+          reject(error);
+        });
+      })
+    ]);
+    
+    log.debug('Test client created and connected', { port });
+  } else {
+    log.debug('Test client created (no auto-connect)', { port });
+  }
+  
+  return {
+    client,
+    port,
+    options: client_options,
+    created_at: new Date().toISOString()
+  };
+};
+
+/**
+ * Creates a test client that's pre-authenticated and ready to use.
+ * @param {number} port - Server port to connect to
+ * @param {Object} [credentials] - Authentication credentials
+ * @param {Object} [options={}] - Additional options
+ * @returns {Promise<Object>} Authenticated client instance with metadata
+ */
+const create_authenticated_test_client = async (port, credentials = null, options = {}) => {
+  const log = create_context_logger();
+  const auth_credentials = credentials || TEST_CONFIG.DEFAULT_TEST_CREDENTIALS;
+  
+  const client_options = {
+    authentication: auth_credentials,
+    ...options
+  };
+  
+  const { client } = await create_test_client(port, client_options);
+  
+  // Wait for authentication
+  const auth_timeout = options.auth_timeout || TEST_CONFIG.AUTH_TIMEOUT;
+  
+  const authenticated = await wait_for_condition(
+    () => client.is_authenticated === true,
+    auth_timeout,
+    100,
+    'client authentication'
+  );
+  
+  if (!authenticated) {
+    client.disconnect();
+    throw new Error(`Client authentication timeout after ${auth_timeout}ms`);
+  }
+  
+  log.debug('Authenticated test client created', { 
+    port, 
+    username: auth_credentials.username 
+  });
+  
+  return {
+    client,
+    port,
+    credentials: auth_credentials,
+    authenticated_at: new Date().toISOString()
+  };
+};
+
+/**
+ * Waits for client to be ready (connected and optionally authenticated).
+ * @param {Object} client - Client instance
+ * @param {number} [timeout=5000] - Maximum time to wait
+ * @param {boolean} [require_auth=false] - Whether to require authentication
+ * @returns {Promise<boolean>} True if client is ready
+ */
+const wait_for_client_ready = async (client, timeout = TEST_CONFIG.CLIENT_CONNECT_TIMEOUT, require_auth = false) => {
+  const is_client_ready = () => {
+    const connected = client.socket && client.socket.readyState === 'open';
+    const authenticated = require_auth ? client.is_authenticated === true : true;
+    return connected && authenticated;
+  };
+  
+  return await wait_for_condition(
+    is_client_ready,
+    timeout,
+    100,
+    'client readiness'
+  );
+};
+
+/**
+ * Sets up initial authentication on a server using admin setup.
+ * @param {number} port - Server port
+ * @param {Object} [credentials] - Admin credentials to create
+ * @param {Object} [options={}] - Setup options
+ * @returns {Promise<Object>} Setup result
+ */
+const setup_test_authentication = async (port, credentials = null, options = {}) => {
+  const log = create_context_logger();
+  const auth_credentials = credentials || TEST_CONFIG.DEFAULT_TEST_CREDENTIALS;
+  
+  // Create unauthenticated client for setup
+  const { client } = await create_test_client(port, { 
+    auto_connect: true,
+    ...options.client_options
+  });
+  
+  try {
+    // Setup initial admin
+    const setup_result = await client.admin('setup_initial_admin', {
+      username: auth_credentials.username,
+      password: auth_credentials.password,
+      email: auth_credentials.email
+    });
+    
+    client.disconnect();
+    
+    if (setup_result.ok !== 1) {
+      throw new Error(`Authentication setup failed: ${setup_result.message || 'Unknown error'}`);
+    }
+    
+    log.debug('Test authentication setup completed', { 
+      port, 
+      username: auth_credentials.username 
+    });
+    
+    return {
+      success: true,
+      credentials: auth_credentials,
+      setup_result,
+      setup_at: new Date().toISOString()
+    };
+    
+  } catch (error) {
+    client.disconnect();
+    log.error('Test authentication setup failed', {
+      port,
+      username: auth_credentials.username,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+/**
+ * Properly disconnects and cleans up a test client.
+ * @param {Object} client - Client instance to cleanup
+ * @param {string} [test_name] - Test name for tracking
+ * @returns {Promise<void>}
+ */
+const cleanup_test_client = async (client, test_name = 'unknown') => {
+  const log = create_context_logger();
+  
+  try {
+    if (client && typeof client.disconnect === 'function') {
+      client.disconnect();
+      log.debug('Test client cleaned up', { test_name });
+    }
+  } catch (error) {
+    log.warn('Error cleaning up test client', {
+      test_name,
+      error: error.message
+    });
+  }
+};
+
+// =============================================================================
+// DATABASE AND TEST DATA UTILITIES
+// =============================================================================
+
+/**
+ * Generates a random test document with sensible defaults and optional overrides.
+ * @param {Object} [overrides={}] - Field overrides for the generated document
+ * @param {Object} [options={}] - Generation options
+ * @returns {Object} Generated test document
+ */
+const generate_test_document = (overrides = {}, options = {}) => {
+  const random_suffix = Math.random().toString(36).substring(2, 8);
+  const timestamp = Date.now();
+  
+  const base_document = {
+    name: `Test User ${random_suffix}`,
+    email: `test${random_suffix}@example.com`,
+    age: Math.floor(Math.random() * 50) + 20,
+    active: Math.random() > 0.5,
+    created_at: new Date().toISOString(),
+    test_id: `test_${timestamp}_${random_suffix}`,
+    metadata: {
+      test_run: true,
+      generated_at: timestamp
+    }
+  };
+  
+  // Apply any additional fields based on options
+  if (options.include_address) {
+    base_document.address = {
+      street: `${Math.floor(Math.random() * 9999) + 1} Test St`,
+      city: 'Test City',
+      zip: `${Math.floor(Math.random() * 90000) + 10000}`
+    };
+  }
+  
+  if (options.include_tags) {
+    base_document.tags = [`tag${random_suffix}`, 'test', 'generated'];
+  }
+  
+  // Apply overrides
+  return { ...base_document, ...overrides };
+};
+
+/**
+ * Creates bulk test data using a generator function.
+ * @param {number} count - Number of documents to generate
+ * @param {Function} [generator] - Custom generator function (uses generate_test_document if not provided)
+ * @param {Object} [options={}] - Generation options
+ * @returns {Array} Array of generated test documents
+ */
+const create_bulk_test_data = (count, generator = null, options = {}) => {
+  const log = create_context_logger();
+  const actual_generator = generator || ((index) => generate_test_document({ 
+    sequence: index,
+    batch_id: options.batch_id || `batch_${Date.now()}`
+  }, options));
+  
+  const documents = [];
+  
+  for (let i = 0; i < count; i++) {
+    try {
+      const document = actual_generator(i, options);
+      documents.push(document);
+    } catch (error) {
+      log.error('Error generating test document', {
+        index: i,
+        count,
+        error: error.message
+      });
+      throw error;
+    }
+  }
+  
+  log.debug('Bulk test data created', { count, batch_id: options.batch_id });
+  return documents;
+};
+
+/**
+ * Generates unique collection names for test isolation.
+ * @param {string} [prefix='test'] - Collection name prefix
+ * @param {Object} [options={}] - Naming options
+ * @returns {string} Unique collection name
+ */
+const get_test_collection_name = (prefix = 'test', options = {}) => {
+  const timestamp = Date.now();
+  const random_suffix = Math.random().toString(36).substring(2, 8);
+  
+  if (options.include_test_name && options.test_name) {
+    return `${prefix}_${options.test_name}_${timestamp}_${random_suffix}`;
+  }
+  
+  return `${prefix}_${timestamp}_${random_suffix}`;
+};
+
+/**
+ * Cleans up test collections from a database.
+ * @param {Object} client - Authenticated client instance
+ * @param {string} [database_name='default'] - Database name
+ * @param {Object} [options={}] - Cleanup options
+ * @returns {Promise<Object>} Cleanup results
+ */
+const cleanup_test_collections = async (client, database_name = 'default', options = {}) => {
+  const log = create_context_logger();
+  
+  try {
+    const database = client.db(database_name);
+    const collections_result = await database.list_collections();
+    
+    if (collections_result.ok !== 1) {
+      return { success: false, error: 'Failed to list collections' };
+    }
+    
+    const test_collections = collections_result.collections.filter(col => {
+      const name = col.name || '';
+      return name.startsWith('test_') || 
+             name.includes('_test') || 
+             (options.pattern && name.match(options.pattern));
+    });
+    
+    const cleanup_results = [];
+    
+    for (const collection of test_collections) {
+      try {
+        // For cleanup, we'll delete all documents in test collections
+        const delete_result = await database.collection(collection.name).delete_many({});
+        cleanup_results.push({
+          collection: collection.name,
+          success: true,
+          deleted_count: delete_result.deleted_count || 0
+        });
+      } catch (error) {
+        cleanup_results.push({
+          collection: collection.name,
+          success: false,
+          error: error.message
+        });
+      }
+    }
+    
+    const total_cleaned = cleanup_results.filter(r => r.success).length;
+    const total_failed = cleanup_results.length - total_cleaned;
+    
+    log.debug('Test collections cleanup completed', {
+      database_name,
+      total_collections: test_collections.length,
+      cleaned: total_cleaned,
+      failed: total_failed
+    });
+    
+    return {
+      success: true,
+      database_name,
+      total_collections: test_collections.length,
+      cleaned: total_cleaned,
+      failed: total_failed,
+      results: cleanup_results
+    };
+    
+  } catch (error) {
+    log.error('Test collections cleanup failed', {
+      database_name,
+      error: error.message
+    });
+    return {
+      success: false,
+      database_name,
+      error: error.message
+    };
+  }
+};
+
+/**
+ * Verifies that database cleanup was successful.
+ * @param {string} database_path - Path to database directory
+ * @returns {Promise<Object>} Verification results
+ */
+const verify_database_cleanup = async (database_path) => {
+  const log = create_context_logger();
+  
+  try {
+    const fs = await import('fs/promises');
+    const path = await import('path');
+    
+    let exists = false;
+    let size_info = null;
+    
+    try {
+      const stats = await fs.stat(database_path);
+      exists = true;
+      
+      if (stats.isDirectory()) {
+        const files = await fs.readdir(database_path);
+        size_info = {
+          type: 'directory',
+          files_count: files.length,
+          files: files
+        };
+      } else if (stats.isFile()) {
+        size_info = {
+          type: 'file',
+          size: stats.size
+        };
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        exists = false;
+      } else {
+        throw error;
+      }
+    }
+    
+    const verification_result = {
+      database_path,
+      exists,
+      size_info,
+      cleaned: !exists || (size_info && size_info.type === 'directory' && size_info.files_count === 0),
+      verified_at: new Date().toISOString()
+    };
+    
+    log.debug('Database cleanup verification completed', verification_result);
+    return verification_result;
+    
+  } catch (error) {
+    log.error('Database cleanup verification failed', {
+      database_path,
+      error: error.message
+    });
+    return {
+      database_path,
+      exists: null,
+      cleaned: false,
+      error: error.message,
+      verified_at: new Date().toISOString()
+    };
+  }
+};
+
+// =============================================================================
+// ADVANCED TEST ENVIRONMENT PATTERNS
+// =============================================================================
+
+/**
+ * Creates a complete test environment with server, authentication, and client.
+ * This is the highest-level helper for comprehensive test setups.
+ * @param {Object} [options={}] - Environment setup options
+ * @returns {Promise<Object>} Complete test environment context
+ */
+const create_complete_test_environment = async (options = {}) => {
+  const log = create_context_logger();
+  const test_name = options.test_name || `complete_env_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+  
+  try {
+    // Create test server
+    const server_context = await create_test_server({
+      test_name: `${test_name}_server`,
+      ...options.server_options
+    });
+    
+    // Setup authentication if requested
+    let auth_setup = null;
+    if (options.setup_auth !== false) {
+      auth_setup = await setup_test_authentication(
+        server_context.port,
+        options.credentials,
+        options.auth_options
+      );
+    }
+    
+    // Create authenticated client if authentication was set up
+    let client_context = null;
+    if (auth_setup) {
+      client_context = await create_authenticated_test_client(
+        server_context.port,
+        auth_setup.credentials,
+        options.client_options
+      );
+    } else if (options.create_client !== false) {
+      // Create unauthenticated client
+      client_context = await create_test_client(
+        server_context.port,
+        options.client_options
+      );
+    }
+    
+    // Create comprehensive cleanup function
+    const cleanup = async () => {
+      log.debug('Starting complete test environment cleanup', { test_name });
+      
+      // Cleanup client first
+      if (client_context && client_context.client) {
+        await cleanup_test_client(client_context.client, test_name);
+      }
+      
+      // Cleanup server
+      await server_context.cleanup();
+      
+      log.debug('Complete test environment cleanup completed', { test_name });
+    };
+    
+    const environment = {
+      test_name,
+      server: server_context,
+      auth_setup,
+      client: client_context,
+      port: server_context.port,
+      cleanup,
+      created_at: new Date().toISOString()
+    };
+    
+    log.info('Complete test environment created', {
+      test_name,
+      port: server_context.port,
+      has_auth: !!auth_setup,
+      has_client: !!client_context
+    });
+    
+    return environment;
+    
+  } catch (error) {
+    log.error('Failed to create complete test environment', {
+      test_name,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+/**
+ * Creates a specialized test environment for CRUD operations testing.
+ * @param {string} test_name - Name of the test
+ * @param {Object} [options={}] - Environment options
+ * @returns {Promise<Object>} CRUD test environment
+ */
+const create_crud_test_environment = async (test_name, options = {}) => {
+  const crud_options = {
+    test_name,
+    setup_auth: true,
+    create_client: true,
+    ...options
+  };
+  
+  const environment = await create_complete_test_environment(crud_options);
+  
+  // Add CRUD-specific helpers
+  const collection_name = options.collection_name || get_test_collection_name('crud', { test_name });
+  const collection = environment.client.client.db('default').collection(collection_name);
+  
+  // Create enhanced cleanup that includes test data cleanup
+  const original_cleanup = environment.cleanup;
+  environment.cleanup = async () => {
+    await cleanup_test_collections(environment.client.client, 'default', {
+      pattern: new RegExp(`^${collection_name}`)
+    });
+    await original_cleanup();
+  };
+  
+  return {
+    ...environment,
+    collection_name,
+    collection,
+    // Helper methods for common CRUD patterns
+    insert_test_document: (overrides) => collection.insert_one(generate_test_document(overrides)),
+    insert_bulk_test_data: (count, generator) => {
+      const documents = create_bulk_test_data(count, generator);
+      return collection.bulk_write(documents.map(doc => ({ insert_one: { document: doc } })));
+    },
+    find_test_documents: (filter = {}) => collection.find(filter),
+    cleanup_test_documents: () => collection.delete_many({})
+  };
+};
+
+/**
+ * Creates a specialized test environment for performance testing.
+ * @param {Object} [options={}] - Performance test options
+ * @returns {Promise<Object>} Performance test environment
+ */
+const create_performance_test_environment = async (options = {}) => {
+  const perf_options = {
+    test_name: options.test_name || `perf_test_${Date.now()}`,
+    setup_auth: true,
+    create_client: true,
+    server_options: {
+      server_config: {
+        // Performance-oriented server config
+        max_connections: options.max_connections || 100,
+        write_queue_size: options.write_queue_size || 10000,
+        ...options.server_config
+      }
+    },
+    client_options: {
+      timeout: options.client_timeout || 30000,
+      ...options.client_options
+    },
+    ...options
+  };
+  
+  const environment = await create_complete_test_environment(perf_options);
+  
+  // Add performance measurement helpers
+  const performance_metrics = {
+    start_time: null,
+    end_time: null,
+    operations: 0,
+    errors: 0
+  };
+  
+  return {
+    ...environment,
+    performance: {
+      start_timer: () => {
+        performance_metrics.start_time = process.hrtime.bigint();
+        performance_metrics.operations = 0;
+        performance_metrics.errors = 0;
+      },
+      end_timer: () => {
+        performance_metrics.end_time = process.hrtime.bigint();
+        const duration_ns = performance_metrics.end_time - performance_metrics.start_time;
+        const duration_ms = Number(duration_ns) / 1000000;
+        
+        return {
+          duration_ms,
+          duration_ns,
+          operations: performance_metrics.operations,
+          errors: performance_metrics.errors,
+          ops_per_second: performance_metrics.operations > 0 ? (performance_metrics.operations / duration_ms * 1000) : 0
+        };
+      },
+      record_operation: () => performance_metrics.operations++,
+      record_error: () => performance_metrics.errors++,
+      get_metrics: () => ({ ...performance_metrics })
+    }
+  };
+};
+
+/**
+ * Wraps a promise with a timeout to prevent hanging tests.
+ * @param {Promise} promise - Promise to wrap
+ * @param {number} timeout_ms - Timeout in milliseconds
+ * @param {string} [description] - Description for error messages
+ * @returns {Promise} Promise that rejects on timeout
+ */
+const with_test_timeout = async (promise, timeout_ms, description = 'operation') => {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Test timeout: ${description} exceeded ${timeout_ms}ms`));
+      }, timeout_ms);
+    })
+  ]);
+};
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export {
+  // Server Management Utilities
+  create_test_server,
+  wait_for_server_ready,
+  cleanup_test_server,
+  get_server_health,
+  
+  // Client Helper Functions
+  create_test_client,
+  create_authenticated_test_client,
+  wait_for_client_ready,
+  setup_test_authentication,
+  cleanup_test_client,
+  
+  // Database and Test Data Utilities
+  generate_test_document,
+  create_bulk_test_data,
+  get_test_collection_name,
+  cleanup_test_collections,
+  verify_database_cleanup,
+  
+  // Advanced Test Environment Patterns
+  create_complete_test_environment,
+  create_crud_test_environment,
+  create_performance_test_environment,
+  with_test_timeout,
+  
+  // Configuration Constants
+  TEST_CONFIG
+};