autotel 2.1.0

package/src/testing.ts

@@ -0,0 +1,670 @@
+/**
+ * Testing Utilities
+ *
+ * Helpers for testing instrumented code and verifying telemetry.
+ * Perfect for integration tests and QA in production validation.
+ *
+ * @example Verify traces are created
+ * ```typescript
+ * import { assertTraceCreated, collectTraces } from '@your-org/otel-decorators/testing'
+ *
+ * describe('UserService', () => {
+ *   it('should create trace for user creation', async () => {
+ *     const collector = collectTraces()
+ *
+ *     const service = new UserService()
+ *     await service.createUser({ email: 'test@example.com' })
+ *
+ *     assertTraceCreated(collector, 'user.createUser')
+ *   })
+ * })
+ * ```
+ */
+
+import {
+  SpanStatusCode,
+  type SpanStatus,
+  type Attributes,
+  type AttributeValue,
+  context,
+  trace as otelTrace,
+  type Span,
+  type SpanContext,
+  type TimeInput,
+  type Exception,
+  type SpanOptions,
+  type Context as OtelContext,
+  type Tracer,
+} from '@opentelemetry/api';
+import { type Logger } from './logger';
+import { configure } from './config';
+
+// Re-export events testing utilities
+export {
+  createEventCollector,
+  assertEventTracked,
+  assertOutcomeTracked,
+  type EventCollector,
+  type EventData,
+  type EventsFunnelStep,
+  type EventsOutcome,
+  type EventsValue,
+} from './event-testing';
+
+/**
+ * Note: OpenTelemetry exporters and processors have moved to dedicated modules
+ * for better semantic clarity.
+ *
+ * For exporters (ConsoleSpanExporter, InMemorySpanExporter):
+ * @see {@link autotel/exporters}
+ *
+ * For processors (SimpleSpanProcessor, BatchSpanProcessor):
+ * @see {@link autotel/processors}
+ *
+ * This module focuses on high-level testing utilities with assertion helpers
+ * and trace collectors.
+ *
+ * @example High-level testing (recommended)
+ * ```typescript
+ * import { createTraceCollector, assertTraceCreated } from 'autotel/testing'
+ *
+ * const collector = createTraceCollector()
+ * await myService.doSomething()
+ * assertTraceCreated(collector, 'myService.doSomething')
+ * ```
+ *
+ * @example Low-level testing (when you need raw OTel spans)
+ * ```typescript
+ * import { InMemorySpanExporter } from 'autotel/exporters'
+ * import { SimpleSpanProcessor } from 'autotel/processors'
+ *
+ * const exporter = new InMemorySpanExporter()
+ * init({ service: 'test', spanProcessor: new SimpleSpanProcessor(exporter) })
+ * ```
+ */
+
+/**
+ * Simplified span representation for testing
+ */
+export interface TestSpan {
+  name: string;
+  status: SpanStatus;
+  attributes: Attributes;
+  startTime: number;
+  endTime: number;
+  duration: number;
+}
+
+/**
+ * In-memory trace collector for testing
+ */
+export interface TraceCollector {
+  /** Get all collected spans */
+  getSpans(): TestSpan[];
+  /** Get spans matching a name */
+  getSpansByName(name: string): TestSpan[];
+  /** Get spans matching attributes */
+  getSpansByAttributes(attributes: Record<string, unknown>): TestSpan[];
+  /** Clear all collected spans */
+  clear(): void;
+  /** Record a span (internal use) */
+  recordSpan(span: TestSpan): void;
+}
+
+/**
+ * Create an in-memory trace collector for testing
+ *
+ * IMPORTANT: This automatically configures the global tracer to record spans.
+ * Call this in your test's beforeEach() to ensure proper setup.
+ *
+ * @example
+ * ```typescript
+ * import { createTraceCollector } from 'autotel/testing'
+ *
+ * describe('MyService', () => {
+ *   let collector: TraceCollector
+ *
+ *   beforeEach(() => {
+ *     collector = createTraceCollector()
+ *   })
+ *
+ *   it('should trace operations', async () => {
+ *     await myService.doSomething()
+ *
+ *     const spans = collector.getSpansByName('myService.doSomething')
+ *     expect(spans).toHaveLength(1)
+ *   })
+ * })
+ * ```
+ */
+export function createTraceCollector(): TraceCollector {
+  const spans: TestSpan[] = [];
+
+  // Create mock span that captures data and implements full Span interface
+  const createMockSpan = (name: string, startTime: number): Span => {
+    const spanData: Partial<TestSpan> = {
+      name,
+      startTime,
+      attributes: {},
+      status: { code: SpanStatusCode.OK },
+    };
+
+    const spanContextData: SpanContext = {
+      traceId: '1234567890abcdef1234567890abcdef', // 128-bit trace ID (32 hex chars)
+      spanId: '1234567890abcdef', // 64-bit span ID (16 hex chars)
+      traceFlags: 1,
+      isRemote: false,
+    };
+
+    const mockSpan: Span = {
+      spanContext: () => spanContextData,
+
+      setStatus(status: SpanStatus) {
+        spanData.status = status;
+        return this;
+      },
+
+      setAttributes(attributes: Attributes) {
+        spanData.attributes = { ...spanData.attributes, ...attributes };
+        return this;
+      },
+
+      setAttribute(key: string, value: AttributeValue) {
+        spanData.attributes = spanData.attributes || {};
+        spanData.attributes[key] = value;
+        return this;
+      },
+
+      addEvent(
+        name: string,
+        attributesOrStartTime?: Attributes | TimeInput,
+        startTime?: TimeInput,
+      ) {
+        void name;
+        void attributesOrStartTime;
+        void startTime;
+        return this;
+      },
+
+      addLink(link: { context: SpanContext; attributes?: Attributes }) {
+        void link;
+        return this;
+      },
+
+      addLinks(
+        links: Array<{ context: SpanContext; attributes?: Attributes }>,
+      ) {
+        void links;
+        return this;
+      },
+
+      updateName(newName: string) {
+        spanData.name = newName;
+        return this;
+      },
+
+      isRecording() {
+        return true;
+      },
+
+      recordException(exception: Exception, time?: TimeInput) {
+        void exception;
+        void time;
+      },
+
+      end(endTimeArg?: TimeInput) {
+        void endTimeArg;
+        const endTime = performance.now();
+        spans.push({
+          name: spanData.name!,
+          status: spanData.status!,
+          attributes: spanData.attributes || {},
+          startTime: spanData.startTime!,
+          endTime,
+          duration: endTime - spanData.startTime!,
+        });
+      },
+    };
+
+    return mockSpan;
+  };
+
+  // Create mock tracer
+  const mockTracer: Tracer = {
+    startSpan(name: string, options?: SpanOptions, ctx?: OtelContext): Span {
+      void options;
+      void ctx;
+      const startTime = performance.now();
+      return createMockSpan(name, startTime);
+    },
+
+    startActiveSpan<F extends (span: Span) => unknown>(
+      name: string,
+      optionsOrFn: SpanOptions | F,
+      contextOrFn?: OtelContext | F,
+      fn?: F,
+    ): ReturnType<F> {
+      const callback = (() => {
+        if (typeof optionsOrFn === 'function') {
+          return optionsOrFn;
+        }
+        if (typeof contextOrFn === 'function') {
+          return contextOrFn;
+        }
+        if (fn) {
+          return fn;
+        }
+        throw new Error('startActiveSpan requires a callback');
+      })();
+
+      const startTime = performance.now();
+      const mockSpan = createMockSpan(name, startTime);
+
+      // Set span as active in context (makes otelTrace.getActiveSpan() work)
+      const ctx = otelTrace.setSpan(context.active(), mockSpan);
+      return context.with(ctx, () => callback(mockSpan)) as ReturnType<F>;
+    },
+  };
+
+  // Auto-configure global tracer
+  configure({ tracer: mockTracer });
+
+  return {
+    getSpans(): TestSpan[] {
+      return [...spans];
+    },
+
+    getSpansByName(name: string): TestSpan[] {
+      return spans.filter((span) => span.name === name);
+    },
+
+    getSpansByAttributes(attributes: Record<string, unknown>): TestSpan[] {
+      return spans.filter((span) => {
+        return Object.entries(attributes).every(
+          ([key, value]) => span.attributes[key] === value,
+        );
+      });
+    },
+
+    clear(): void {
+      spans.length = 0;
+    },
+
+    recordSpan(span: TestSpan): void {
+      spans.push(span);
+    },
+  };
+}
+
+/**
+ * Assert that a trace was created for an operation
+ *
+ * @param collector - Trace collector
+ * @param operationName - Expected operation name
+ * @param options - Optional assertion options
+ * @throws Error if trace was not found or doesn't match expectations
+ *
+ * @example
+ * ```typescript
+ * assertTraceCreated(collector, 'user.createUser')
+ * assertTraceCreated(collector, 'user.createUser', {
+ *   minCount: 1,
+ *   maxCount: 1,
+ *   status: SpanStatusCode.OK,
+ *   attributes: { 'user.email': 'test@example.com' }
+ * })
+ * ```
+ */
+export function assertTraceCreated(
+  collector: TraceCollector,
+  operationName: string,
+  options?: {
+    minCount?: number;
+    maxCount?: number;
+    status?: SpanStatusCode;
+    attributes?: Record<string, unknown>;
+  },
+): void {
+  const spans = collector.getSpansByName(operationName);
+
+  if (options?.minCount !== undefined && spans.length < options.minCount) {
+    throw new Error(
+      `Expected at least ${options.minCount} traces for ${operationName}, got ${spans.length}`,
+    );
+  }
+
+  if (options?.maxCount !== undefined && spans.length > options.maxCount) {
+    throw new Error(
+      `Expected at most ${options.maxCount} traces for ${operationName}, got ${spans.length}`,
+    );
+  }
+
+  if (spans.length === 0) {
+    throw new Error(`No traces found for operation: ${operationName}`);
+  }
+
+  if (options?.status !== undefined) {
+    const matchingSpans = spans.filter(
+      (span) => span.status.code === options.status,
+    );
+    if (matchingSpans.length === 0) {
+      throw new Error(
+        `No traces with status ${options.status} found for ${operationName}`,
+      );
+    }
+  }
+
+  if (options?.attributes) {
+    const matchingSpans = spans.filter((span) => {
+      return Object.entries(options.attributes!).every(
+        ([key, value]) => span.attributes[key] === value,
+      );
+    });
+    if (matchingSpans.length === 0) {
+      throw new Error(
+        `No traces with attributes ${JSON.stringify(options.attributes)} found for ${operationName}`,
+      );
+    }
+  }
+}
+
+/**
+ * Assert that no errors were logged
+ *
+ * Use this in smoke tests to verify critical paths don't have errors.
+ *
+ * @param collector - Trace collector
+ * @throws Error if any error traces are found
+ *
+ * @example
+ * ```typescript
+ * // Run critical user flows
+ * await runSmokeTests()
+ *
+ * // Verify no errors occurred
+ * assertNoErrors(collector)
+ * ```
+ */
+export function assertNoErrors(collector: TraceCollector): void {
+  const errorSpans = collector
+    .getSpans()
+    .filter((span) => span.status.code === SpanStatusCode.ERROR);
+
+  if (errorSpans.length > 0) {
+    const errorSummary = errorSpans
+      .map((span) => `${span.name}: ${span.status.message}`)
+      .join('\n');
+    throw new Error(`Found ${errorSpans.length} error spans:\n${errorSummary}`);
+  }
+}
+
+/**
+ * Assert that a trace was created and succeeded
+ *
+ * @param collector - Trace collector
+ * @param operationName - Expected operation name
+ *
+ * @example
+ * ```typescript
+ * assertTraceSucceeded(collector, 'user.createUser')
+ * ```
+ */
+export function assertTraceSucceeded(
+  collector: TraceCollector,
+  operationName: string,
+): void {
+  assertTraceCreated(collector, operationName, { status: SpanStatusCode.OK });
+}
+
+/**
+ * Assert that a trace was created and failed
+ *
+ * @param collector - Trace collector
+ * @param operationName - Expected operation name
+ * @param errorMessage - Optional expected error message
+ *
+ * @example
+ * ```typescript
+ * assertTraceFailed(collector, 'user.createUser', 'Invalid email')
+ * ```
+ */
+export function assertTraceFailed(
+  collector: TraceCollector,
+  operationName: string,
+  errorMessage?: string,
+): void {
+  const spans = collector.getSpansByName(operationName);
+
+  if (spans.length === 0) {
+    throw new Error(`No traces found for operation: ${operationName}`);
+  }
+
+  const errorSpans = spans.filter(
+    (span) => span.status.code === SpanStatusCode.ERROR,
+  );
+
+  if (errorSpans.length === 0) {
+    throw new Error(`No error traces found for operation: ${operationName}`);
+  }
+
+  if (errorMessage) {
+    const matchingSpans = errorSpans.filter(
+      (span) => span.status.message === errorMessage,
+    );
+    if (matchingSpans.length === 0) {
+      throw new Error(
+        `No error traces with message "${errorMessage}" found for ${operationName}`,
+      );
+    }
+  }
+}
+
+/**
+ * In-memory log collector for testing
+ */
+export interface LogCollector {
+  /** Get all collected logs */
+  getLogs(): LogEntry[];
+  /** Get logs by level */
+  getLogsByLevel(level: 'info' | 'warn' | 'error' | 'debug'): LogEntry[];
+  /** Get logs containing a message */
+  getLogsByMessage(message: string): LogEntry[];
+  /** Clear all collected logs */
+  clear(): void;
+}
+
+/**
+ * Log entry
+ */
+export interface LogEntry {
+  level: 'info' | 'warn' | 'error' | 'debug';
+  message: string;
+  extra?: Record<string, unknown>;
+  error?: Error;
+}
+
+/**
+ * Create an in-memory log collector for testing
+ *
+ * @example
+ * ```typescript
+ * const logger = createMockLogger()
+ *
+ * // Use logger in your code
+ * service.log = logger
+ * await service.doSomething()
+ *
+ * // Assert logs were created
+ * const logs = logger.getLogs()
+ * expect(logs).toHaveLength(2)
+ * expect(logs[0].message).toBe('Operation started')
+ * ```
+ */
+export function createMockLogger(): Logger & LogCollector {
+  const logs: LogEntry[] = [];
+
+  return {
+    info(message: string, extra?: Record<string, unknown>): void {
+      logs.push({ level: 'info', message, extra });
+    },
+
+    warn(message: string, extra?: Record<string, unknown>): void {
+      logs.push({ level: 'warn', message, extra });
+    },
+
+    error(
+      message: string,
+      error?: Error,
+      extra?: Record<string, unknown>,
+    ): void {
+      logs.push({ level: 'error', message, error, extra });
+    },
+
+    debug(message: string, extra?: Record<string, unknown>): void {
+      logs.push({ level: 'debug', message, extra });
+    },
+
+    getLogs(): LogEntry[] {
+      return [...logs];
+    },
+
+    getLogsByLevel(level: 'info' | 'warn' | 'error' | 'debug'): LogEntry[] {
+      return logs.filter((log) => log.level === level);
+    },
+
+    getLogsByMessage(message: string): LogEntry[] {
+      return logs.filter((log) => log.message.includes(message));
+    },
+
+    clear(): void {
+      logs.length = 0;
+    },
+  };
+}
+
+/**
+ * Assert that no error logs were created
+ *
+ * @param logger - Log collector
+ * @throws Error if any error logs are found
+ *
+ * @example
+ * ```typescript
+ * assertNoErrorsLogged(logger)
+ * ```
+ */
+export function assertNoErrorsLogged(logger: LogCollector): void {
+  const errorLogs = logger.getLogsByLevel('error');
+
+  if (errorLogs.length > 0) {
+    const errorSummary = errorLogs
+      .map(
+        (log) => `${log.message}${log.error ? ': ' + log.error.message : ''}`,
+      )
+      .join('\n');
+    throw new Error(`Found ${errorLogs.length} error logs:\n${errorSummary}`);
+  }
+}
+
+/**
+ * Wait for a specific trace to be created
+ *
+ * Useful for async operations where you need to wait for telemetry.
+ *
+ * @param collector - Trace collector
+ * @param operationName - Expected operation name
+ * @param timeoutMs - Timeout in milliseconds (default 5000)
+ * @returns Promise that resolves when trace is found
+ * @throws Error if timeout is reached
+ *
+ * @example
+ * ```typescript
+ * // Start async operation
+ * const promise = service.doAsyncWork()
+ *
+ * // Wait for trace
+ * await waitForTrace(collector, 'service.doAsyncWork', 1000)
+ *
+ * // Now you can assert on the trace
+ * assertTraceSucceeded(collector, 'service.doAsyncWork')
+ * ```
+ */
+export async function waitForTrace(
+  collector: TraceCollector,
+  operationName: string,
+  timeoutMs: number = 5000,
+): Promise<void> {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    const spans = collector.getSpansByName(operationName);
+    if (spans.length > 0) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+
+  throw new Error(
+    `Timeout waiting for trace ${operationName} after ${timeoutMs}ms`,
+  );
+}
+
+/**
+ * Get trace duration in milliseconds
+ *
+ * @param collector - Trace collector
+ * @param operationName - Operation name
+ * @returns Duration in milliseconds, or undefined if trace not found
+ *
+ * @example
+ * ```typescript
+ * const duration = getTraceDuration(collector, 'user.createUser')
+ * expect(duration).toBeLessThan(1000) // Should be < 1s
+ * ```
+ */
+export function getTraceDuration(
+  collector: TraceCollector,
+  operationName: string,
+): number | undefined {
+  const spans = collector.getSpansByName(operationName);
+  if (spans.length === 0) {
+    return undefined;
+  }
+
+  return spans[0]?.duration;
+}
+
+/**
+ * Assert that an operation completed within a time threshold
+ *
+ * Perfect for performance testing and SLO validation.
+ *
+ * @param collector - Trace collector
+ * @param operationName - Operation name
+ * @param maxDurationMs - Maximum allowed duration in milliseconds
+ * @throws Error if operation took too long
+ *
+ * @example
+ * ```typescript
+ * // Verify operation meets SLO
+ * await service.createUser({ email: 'test@example.com' })
+ * assertTraceDuration(collector, 'user.createUser', 500) // Must be < 500ms
+ * ```
+ */
+export function assertTraceDuration(
+  collector: TraceCollector,
+  operationName: string,
+  maxDurationMs: number,
+): void {
+  const duration = getTraceDuration(collector, operationName);
+
+  if (duration === undefined) {
+    throw new Error(`No trace found for operation: ${operationName}`);
+  }
+
+  if (duration > maxDurationMs) {
+    throw new Error(
+      `Operation ${operationName} took ${duration.toFixed(2)}ms, exceeding ${maxDurationMs}ms threshold`,
+    );
+  }
+}