feat(tests): enhance integration and unit tests for error handling and TLS config

Author: ihor-sokoliuk

__tests__/integration/index.test.ts

@@ -193,6 +193,20 @@ async function runTests() {
   }, results);
 
   await testFunction('Importing index.ts does not start the CLI server', () => {
+    // When this suite runs under a debugger (e.g. VS Code's JavaScript Debug
+    // Terminal / auto-attach), Node injects the inspector into child processes
+    // and prints banner lines like "Debugger attached." to stderr. That has
+    // nothing to do with the program under test, so:
+    //   1. strip the inspector env vars so the child never attaches, and
+    //   2. filter any residual debugger banner lines from the captured output.
+    const { NODE_OPTIONS: _n, VSCODE_INSPECTOR_OPTIONS: _v, ...cleanEnv } = process.env;
+
+    const stripDebuggerNoise = (output: string): string =>
+      output
+        .split('\n')
+        .filter(line => !/^(Debugger attached\.|Waiting for the debugger to disconnect\.\.\.|Debugger listening on |For help, see: https:\/\/nodejs\.org\/en\/docs\/inspector)/.test(line))
+        .join('\n');
+
     const result = spawnSync(
       process.execPath,
       [
@@ -204,7 +218,7 @@ async function runTests() {
       {
         cwd: process.cwd(),
         env: {
-          ...process.env,
+          ...cleanEnv,
           MCP_HTTP_PORT: '',
           SEARXNG_URL: '',
         },
@@ -214,8 +228,8 @@ async function runTests() {
     );
 
     assert.equal(result.status, 0, `Import process failed: ${result.stderr}`);
-    assert.equal(result.stdout, '');
-    assert.equal(result.stderr, '');
+    assert.equal(stripDebuggerNoise(result.stdout), '');
+    assert.equal(stripDebuggerNoise(result.stderr), '');
   }, results);
 
   await testFunction('Running cli.js responds to MCP initialize', () => {

__tests__/unit/error-handler.test.ts

@@ -22,7 +22,9 @@ import {
   createTimeoutError,
   createEmptyContentWarning,
   createUnexpectedError,
-  validateEnvironment
+  validateEnvironment,
+  handleUncaughtException,
+  handleUnhandledRejection
 } from '../../src/error-handler.js';
 import { testFunction, createTestResults, printTestSummary } from '../helpers/test-utils.js';
 import { EnvManager } from '../helpers/env-utils.js';
@@ -229,6 +231,45 @@ async function runTests() {
     assert.ok(result.message.includes('DEPTH_ZERO_SELF_SIGNED_CERT'), `Expected code in message, got: ${result.message}`);
   }, results);
 
+  // --- Process-level crash handlers ---
+  // process.exit / console.error are stubbed so the handlers can be exercised
+  // without killing the test process or printing to the real console.
+  function captureExitAndError(fn: () => void): { exitCode: number | undefined; calls: unknown[][] } {
+    const originalExit = process.exit;
+    const originalError = console.error;
+    let exitCode: number | undefined;
+    const calls: unknown[][] = [];
+    process.exit = ((code?: number) => { exitCode = code; }) as unknown as typeof process.exit;
+    console.error = (...args: unknown[]) => { calls.push(args); };
+    try {
+      fn();
+    } finally {
+      process.exit = originalExit;
+      console.error = originalError;
+    }
+    return { exitCode, calls };
+  }
+
+  await testFunction('handleUncaughtException logs the error and exits with code 1', () => {
+    const err = new Error('boom');
+    const { exitCode, calls } = captureExitAndError(() => handleUncaughtException(err));
+    assert.equal(exitCode, 1);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][0], 'Uncaught Exception:');
+    assert.equal(calls[0][1], err);
+  }, results);
+
+  await testFunction('handleUnhandledRejection logs the reason/promise and exits with code 1', () => {
+    const reason = new Error('nope');
+    const promise = Promise.reject(reason);
+    promise.catch(() => {}); // settle it so the test process sees no real unhandled rejection
+    const { exitCode, calls } = captureExitAndError(() => handleUnhandledRejection(reason, promise));
+    assert.equal(exitCode, 1);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][0], 'Unhandled Rejection at:');
+    assert.equal(calls[0][3], reason);
+  }, results);
+
   printTestSummary(results, 'Error Handler Module');
   return results;
 }

__tests__/unit/tls-config.test.ts

@@ -3,19 +3,27 @@
 /**
  * Unit Tests: tls-config.ts
  *
- * Tests for system CA certificate loading
+ * Tests for system CA certificate loading.
+ *
+ * The real-system tests below exercise the default (no-dependency) code path,
+ * while the injected-dependency tests deterministically cover every branch —
+ * including the Windows and unreadable-bundle paths — on any host/OS.
  */
 
 import { strict as assert } from 'node:assert';
 import { fileURLToPath } from 'node:url';
 import { getSystemCACerts, getConnectOptions } from '../../src/tls-config.js';
 import { testFunction, createTestResults, printTestSummary } from '../helpers/test-utils.js';
 
+const PEM = '-----BEGIN CERTIFICATE-----\nMIIB\n-----END CERTIFICATE-----\n';
+
 const results = createTestResults();
 
 async function runTests() {
   console.log('🧪 Testing: tls-config.ts\n');
 
+  // --- Real-system path (covers the default platform/fs dependencies) ---
+
   await testFunction('getSystemCACerts returns string or null', () => {
     const certs = getSystemCACerts();
     assert.ok(certs === null || typeof certs === 'string');
@@ -56,6 +64,86 @@ async function runTests() {
     }
   }, results);
 
+  // --- Injected dependencies: deterministic branch coverage ---
+
+  await testFunction('getSystemCACerts returns null on win32 without touching the filesystem', () => {
+    let touched = false;
+    const certs = getSystemCACerts({
+      platformName: 'win32',
+      fileExists: () => { touched = true; return true; },
+      readFile: () => { touched = true; return PEM; },
+      caPaths: ['/should/not/be/read'],
+    });
+    assert.equal(certs, null);
+    assert.equal(touched, false, 'win32 short-circuits before any fs access');
+  }, results);
+
+  await testFunction('getSystemCACerts returns the first readable bundle', () => {
+    const reads: string[] = [];
+    const certs = getSystemCACerts({
+      platformName: 'linux',
+      fileExists: () => true,
+      readFile: (p) => { reads.push(p); return PEM; },
+      caPaths: ['/etc/ssl/first.crt', '/etc/ssl/second.crt'],
+    });
+    assert.equal(certs, PEM);
+    assert.deepEqual(reads, ['/etc/ssl/first.crt'], 'stops at the first readable bundle');
+  }, results);
+
+  await testFunction('getSystemCACerts skips an existing-but-unreadable bundle and tries the next', () => {
+    const certs = getSystemCACerts({
+      platformName: 'linux',
+      fileExists: () => true,
+      readFile: (p) => {
+        if (p === '/etc/ssl/locked.crt') {
+          throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+        }
+        return PEM;
+      },
+      caPaths: ['/etc/ssl/locked.crt', '/etc/ssl/readable.crt'],
+    });
+    assert.equal(certs, PEM, 'falls through the unreadable path to the readable one');
+  }, results);
+
+  await testFunction('getSystemCACerts returns null when no candidate path exists', () => {
+    const certs = getSystemCACerts({
+      platformName: 'linux',
+      fileExists: () => false,
+      readFile: () => { throw new Error('should not be called'); },
+      caPaths: ['/nope/a.crt', '/nope/b.crt'],
+    });
+    assert.equal(certs, null);
+  }, results);
+
+  await testFunction('getSystemCACerts returns null when every bundle is unreadable', () => {
+    const certs = getSystemCACerts({
+      platformName: 'linux',
+      fileExists: () => true,
+      readFile: () => { throw new Error('EACCES'); },
+      caPaths: ['/etc/ssl/a.crt', '/etc/ssl/b.crt'],
+    });
+    assert.equal(certs, null);
+  }, results);
+
+  await testFunction('getConnectOptions wraps the CA bundle when one is found', () => {
+    const opts = getConnectOptions({
+      platformName: 'linux',
+      fileExists: () => true,
+      readFile: () => PEM,
+      caPaths: ['/etc/ssl/found.crt'],
+    });
+    assert.deepEqual(opts, { ca: PEM });
+  }, results);
+
+  await testFunction('getConnectOptions returns empty object when no CA bundle is found', () => {
+    const opts = getConnectOptions({
+      platformName: 'linux',
+      fileExists: () => false,
+      caPaths: ['/nope.crt'],
+    });
+    assert.deepEqual(opts, {});
+  }, results);
+
   printTestSummary(results, 'TLS Config Module');
   return results;
 }

package.json

@@ -38,7 +38,7 @@
         "build": "tsc && shx chmod +x dist/*.js",
         "watch": "tsc --watch",
         "test": "cross-env SEARXNG_URL=https://test-searx.example.com tsx __tests__/run-all.ts",
-        "test:coverage": "cross-env SEARXNG_URL=https://test-searx.example.com c8 --reporter=text --exclude 'dist/**' --check-coverage --lines 80 tsx __tests__/run-all.ts",
+        "test:coverage": "cross-env SEARXNG_URL=https://test-searx.example.com c8 --reporter=text --include 'src/**' --check-coverage --lines 90 --branches 85 tsx __tests__/run-all.ts",
         "test:e2e": "node --env-file-if-exists=.env.e2e node_modules/.bin/tsx __tests__/e2e/run-e2e.ts",
         "bootstrap": "npm install && npm run build",
         "inspector": "DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector node dist/cli.js",

src/cli.ts

@@ -1,16 +1,10 @@
 #!/usr/bin/env node
 
 import { main } from "./index.js";
+import { handleUncaughtException, handleUnhandledRejection } from "./error-handler.js";
 
-process.on('uncaughtException', (error) => {
-  console.error('Uncaught Exception:', error);
-  process.exit(1);
-});
-
-process.on('unhandledRejection', (reason, promise) => {
-  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-  process.exit(1);
-});
+process.on('uncaughtException', handleUncaughtException);
+process.on('unhandledRejection', handleUnhandledRejection);
 
 main().catch((error) => {
   console.error("Failed to start server:", error);

src/error-handler.ts

@@ -154,6 +154,23 @@ export function createUnexpectedError(error: any, context: ErrorContext): MCPSea
   return new MCPSearXNGError(`❓ Unexpected Error: ${error.message || String(error)}`);
 }
 
+/**
+ * Process-level crash handlers, registered by the CLI entrypoint (cli.ts).
+ *
+ * Extracted here so the logic is unit-testable: cli.ts calls main() at import
+ * time (it must always start the server — see issue #91), so it cannot be
+ * imported to test these in place.
+ */
+export function handleUncaughtException(error: unknown): void {
+  console.error('Uncaught Exception:', error);
+  process.exit(1);
+}
+
+export function handleUnhandledRejection(reason: unknown, promise: Promise<unknown>): void {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  process.exit(1);
+}
+
 export function validateEnvironment(): string | null {
   const issues: string[] = [];
 

src/tls-config.ts

@@ -12,24 +12,44 @@ const CA_BUNDLE_PATHS = [
   "/etc/ssl/cert.pem",                    // Alpine, macOS
 ];
 
+/**
+ * Injectable dependencies for {@link getSystemCACerts}.
+ *
+ * These exist purely as a test seam: production callers pass nothing and the
+ * real platform / filesystem are used. Tests override them to exercise branches
+ * (e.g. Windows, unreadable bundles) deterministically on any host.
+ */
+export interface CACertDeps {
+  platformName?: NodeJS.Platform;
+  fileExists?: (path: string) => boolean;
+  readFile?: (path: string) => string;
+  caPaths?: readonly string[];
+}
+
 /**
  * Reads system CA certificates from well-known bundle paths.
  * Returns null on Windows (no universal file path) or if no bundle is found.
  *
  * On Windows, users should set NODE_EXTRA_CA_CERTS pointing to a PEM file.
  */
-export function getSystemCACerts(): string | null {
+export function getSystemCACerts(deps: CACertDeps = {}): string | null {
+  const {
+    platformName = platform,
+    fileExists = existsSync,
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    readFile = (path: string) => readFileSync(path, "utf8"),
+    caPaths = CA_BUNDLE_PATHS,
+  } = deps;
+
   // Windows has no universal CA bundle path; skip auto-detection
-  if (platform === "win32") {
+  if (platformName === "win32") {
     return null;
   }
 
-  for (const caPath of CA_BUNDLE_PATHS) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename
-    if (existsSync(caPath)) {
+  for (const caPath of caPaths) {
+    if (fileExists(caPath)) {
       try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename
-        return readFileSync(caPath, "utf8");
+        return readFile(caPath);
       } catch {
         // File exists but is unreadable (permissions); try next
         continue;
@@ -49,7 +69,7 @@ export function getSystemCACerts(): string | null {
  *   new Agent({ connect: getConnectOptions() })
  *   new ProxyAgent({ uri: proxyUrl, connect: getConnectOptions() })
  */
-export function getConnectOptions(): { ca: string } | Record<string, never> {
-  const ca = getSystemCACerts();
+export function getConnectOptions(deps: CACertDeps = {}): { ca: string } | Record<string, never> {
+  const ca = getSystemCACerts(deps);
   return ca !== null ? { ca } : {};
 }