autotel-subscribers 4.0.0

package/src/testing/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Testing utilities for subscriber authors.
+ *
+ * Use these to validate your custom subscribers work correctly.
+ *
+ * @example Test your subscriber
+ * ```typescript
+ * import { SubscriberTestHarness } from 'autotel-subscribers/testing';
+ *
+ * const harness = new SubscriberTestHarness(new MySubscriber());
+ * const results = await harness.runAll();
+ * SubscriberTestHarness.printResults(results);
+ * ```
+ *
+ * @example Test webhook subscriber
+ * ```typescript
+ * import { MockWebhookServer } from 'autotel-subscribers/testing';
+ *
+ * const server = new MockWebhookServer();
+ * const url = await server.start();
+ * const subscriber = new WebhookSubscriber({ url });
+ *
+ * await subscriber.trackEvent('test', {});
+ * expect(server.getRequestCount()).toBe(1);
+ *
+ * await server.stop();
+ * ```
+ */
+
+export { SubscriberTestHarness } from './subscriber-test-harness';
+export type { TestResult, TestSuiteResult } from './subscriber-test-harness';
+
+export { MockWebhookServer } from './mock-webhook-server';
+export type { RecordedRequest, MockServerOptions } from './mock-webhook-server';
+
+// Re-export MockEventSubscriber for convenience
+export { MockEventSubscriber } from '../mock-event-subscriber';

package/src/testing/mock-webhook-server.ts

@@ -0,0 +1,242 @@
+/**
+ * MockWebhookServer - In-Memory HTTP Server for Testing
+ *
+ * Perfect for testing webhook subscribers without real HTTP calls.
+ * Records all requests for easy assertions in tests.
+ *
+ * @example
+ * ```typescript
+ * import { MockWebhookServer } from 'autotel-subscribers/testing';
+ *
+ * const server = new MockWebhookServer();
+ * const url = await server.start();
+ *
+ * // Test your webhook subscriber
+ * const subscriber = new WebhookSubscriber({ url });
+ * await subscriber.trackEvent('test.event', { foo: 'bar' });
+ *
+ * // Assert
+ * const requests = server.getRequests();
+ * expect(requests).toHaveLength(1);
+ * expect(requests[0].body.event).toBe('test.event');
+ *
+ * await server.stop();
+ * ```
+ */
+
+import * as http from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export interface RecordedRequest {
+  method: string;
+  path: string;
+  headers: http.IncomingHttpHeaders;
+  body: any;
+  timestamp: number;
+}
+
+export interface MockServerOptions {
+  /** Port to listen on (0 = random port) */
+  port?: number;
+  /** Response status code (default: 200) */
+  responseStatus?: number;
+  /** Response delay in ms (default: 0) */
+  responseDelay?: number;
+  /** Response body (default: 'OK') */
+  responseBody?: string;
+  /** Log requests to console (default: false) */
+  logRequests?: boolean;
+}
+
+/**
+ * In-memory HTTP server for testing webhook subscribers.
+ *
+ * Records all incoming requests so you can assert on them in tests.
+ */
+export class MockWebhookServer {
+  private server?: http.Server;
+  private requests: RecordedRequest[] = [];
+  private options: Required<MockServerOptions>;
+
+  constructor(options: MockServerOptions = {}) {
+    this.options = {
+      port: options.port ?? 0,
+      responseStatus: options.responseStatus ?? 200,
+      responseDelay: options.responseDelay ?? 0,
+      responseBody: options.responseBody ?? 'OK',
+      logRequests: options.logRequests ?? false,
+    };
+  }
+
+  /**
+   * Start the mock server and return its URL.
+   *
+   * @returns Promise resolving to the server URL (e.g., "http://localhost:3000")
+   */
+  async start(): Promise<string> {
+    if (this.server) {
+      throw new Error('Server already started');
+    }
+
+    this.server = http.createServer((req, res) => {
+      let body = '';
+
+      req.on('data', (chunk) => {
+        body += chunk.toString();
+      });
+
+      req.on('end', () => {
+        const parsedBody = this.parseBody(body, req.headers['content-type']);
+
+        const request: RecordedRequest = {
+          method: req.method || 'GET',
+          path: req.url || '/',
+          headers: req.headers,
+          body: parsedBody,
+          timestamp: Date.now(),
+        };
+
+        this.requests.push(request);
+
+        if (this.options.logRequests) {
+          console.log('[MockWebhookServer]', request.method, request.path, parsedBody);
+        }
+
+        // Simulate response delay
+        setTimeout(() => {
+          res.writeHead(this.options.responseStatus, {
+            'Content-Type': 'text/plain',
+          });
+          res.end(this.options.responseBody);
+        }, this.options.responseDelay);
+      });
+    });
+
+    await new Promise<void>((resolve) => {
+      this.server!.listen(this.options.port, () => {
+        resolve();
+      });
+    });
+
+    const address = this.server.address() as AddressInfo;
+    return `http://localhost:${address.port}`;
+  }
+
+  /**
+   * Stop the mock server.
+   */
+  async stop(): Promise<void> {
+    if (!this.server) {
+      return;
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      this.server!.close((err) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+
+    this.server = undefined;
+  }
+
+  /**
+   * Get all recorded requests.
+   */
+  getRequests(): RecordedRequest[] {
+    return [...this.requests];
+  }
+
+  /**
+   * Get requests matching a filter.
+   */
+  getRequestsWhere(filter: Partial<RecordedRequest>): RecordedRequest[] {
+    return this.requests.filter((req) => {
+      return Object.entries(filter).every(([key, value]) => {
+        return (req as any)[key] === value;
+      });
+    });
+  }
+
+  /**
+   * Get the last recorded request.
+   */
+  getLastRequest(): RecordedRequest | undefined {
+    return this.requests.at(-1);
+  }
+
+  /**
+   * Get the first recorded request.
+   */
+  getFirstRequest(): RecordedRequest | undefined {
+    return this.requests[0];
+  }
+
+  /**
+   * Clear all recorded requests.
+   */
+  reset(): void {
+    this.requests = [];
+  }
+
+  /**
+   * Get the number of recorded requests.
+   */
+  getRequestCount(): number {
+    return this.requests.length;
+  }
+
+  /**
+   * Wait for a specific number of requests.
+   *
+   * Useful when testing async subscribers.
+   *
+   * @example
+   * ```typescript
+   * await subscriber.trackEvent('event1', {});
+   * await subscriber.trackEvent('event2', {});
+   * await server.waitForRequests(2, 1000); // Wait max 1 second
+   * ```
+   */
+  async waitForRequests(count: number, timeoutMs: number = 5000): Promise<void> {
+    const startTime = Date.now();
+
+    while (this.requests.length < count) {
+      if (Date.now() - startTime > timeoutMs) {
+        throw new Error(
+          `Timeout waiting for ${count} requests (got ${this.requests.length})`
+        );
+      }
+
+      // Wait 10ms before checking again
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  /**
+   * Parse request body based on Content-Type.
+   */
+  private parseBody(body: string, contentType?: string): any {
+    if (!body) {
+      return null;
+    }
+
+    try {
+      if (contentType?.includes('application/json')) {
+        return JSON.parse(body);
+      }
+
+      if (contentType?.includes('application/x-www-form-urlencoded')) {
+        return Object.fromEntries(new URLSearchParams(body));
+      }
+
+      return body;
+    } catch {
+      // If parsing fails, return raw string
+      return body;
+    }
+  }
+}

package/src/testing/subscriber-test-harness.ts

@@ -0,0 +1,365 @@
+/**
+ * SubscriberTestHarness - Validate Your Custom Subscriber
+ *
+ * Use this to test that your custom subscriber implements the EventSubscriber
+ * interface correctly. It runs a suite of tests covering:
+ * - Basic tracking (all 4 methods)
+ * - Concurrent requests
+ * - Error handling
+ * - Graceful shutdown
+ *
+ * @example
+ * ```typescript
+ * import { SubscriberTestHarness } from 'autotel-subscribers/testing';
+ * import { MyCustomSubscriber } from './my-adapter';
+ *
+ * const harness = new SubscriberTestHarness(new MyCustomSubscriber());
+ * const results = await harness.runAll();
+ *
+ * if (results.passed) {
+ *   console.log('✅ All tests passed!');
+ * } else {
+ *   console.error('❌ Tests failed:', results.failures);
+ * }
+ * ```
+ */
+
+import type {
+  EventSubscriber,
+  FunnelStatus,
+  OutcomeStatus,
+} from '../event-subscriber-base';
+
+export interface TestResult {
+  name: string;
+  passed: boolean;
+  duration: number;
+  error?: Error;
+  details?: string;
+}
+
+export interface TestSuiteResult {
+  passed: boolean;
+  total: number;
+  passed_count: number;
+  failed_count: number;
+  duration: number;
+  results: TestResult[];
+  failures: TestResult[];
+}
+
+/**
+ * Test harness for validating custom subscribers.
+ *
+ * Runs a comprehensive suite of tests to ensure your subscriber:
+ * 1. Implements all required methods
+ * 2. Handles concurrent requests
+ * 3. Deals with errors gracefully
+ * 4. Shuts down cleanly
+ */
+export class SubscriberTestHarness {
+  constructor(private subscriber: EventSubscriber) {}
+
+  /**
+   * Run all tests and return a comprehensive report.
+   */
+  async runAll(): Promise<TestSuiteResult> {
+    const startTime = performance.now();
+    const results: TestResult[] = [];
+
+    // Run all test methods
+    const testResults = await Promise.all([
+      this.testBasicTracking(),
+      this.testFunnelTracking(),
+      this.testOutcomeTracking(),
+      this.testValueTracking(),
+      this.testConcurrency(),
+      this.testErrorHandling(),
+      this.testShutdown(),
+    ]);
+    results.push(...testResults);
+
+    const duration = performance.now() - startTime;
+    const passed_count = results.filter((r) => r.passed).length;
+    const failed_count = results.filter((r) => !r.passed).length;
+    const failures = results.filter((r) => !r.passed);
+
+    return {
+      passed: failed_count === 0,
+      total: results.length,
+      passed_count,
+      failed_count,
+      duration,
+      results,
+      failures,
+    };
+  }
+
+  /**
+   * Test basic event tracking.
+   */
+  async testBasicTracking(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      await this.subscriber.trackEvent('test.event', {
+        userId: 'test-user',
+        testAttribute: 'test-value',
+      });
+
+      return {
+        name: 'Basic Event Tracking',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Successfully tracked event',
+      };
+    } catch (error) {
+      return {
+        name: 'Basic Event Tracking',
+        passed: false,
+        duration: performance.now() - startTime,
+        error: error as Error,
+      };
+    }
+  }
+
+  /**
+   * Test funnel step tracking.
+   */
+  async testFunnelTracking(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      await this.subscriber.trackFunnelStep('test_funnel', 'started' as FunnelStatus, {
+        cartValue: 99.99,
+      });
+
+      await this.subscriber.trackFunnelStep('test_funnel', 'completed' as FunnelStatus, {
+        cartValue: 99.99,
+      });
+
+      return {
+        name: 'Funnel Tracking',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Successfully tracked funnel steps',
+      };
+    } catch (error) {
+      return {
+        name: 'Funnel Tracking',
+        passed: false,
+        duration: performance.now() - startTime,
+        error: error as Error,
+      };
+    }
+  }
+
+  /**
+   * Test outcome tracking.
+   */
+  async testOutcomeTracking(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      await this.subscriber.trackOutcome('test_operation', 'success' as OutcomeStatus, {
+        duration: 100,
+      });
+
+      await this.subscriber.trackOutcome('test_operation', 'failure' as OutcomeStatus, {
+        error: 'Test error',
+      });
+
+      return {
+        name: 'Outcome Tracking',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Successfully tracked outcomes',
+      };
+    } catch (error) {
+      return {
+        name: 'Outcome Tracking',
+        passed: false,
+        duration: performance.now() - startTime,
+        error: error as Error,
+      };
+    }
+  }
+
+  /**
+   * Test value tracking.
+   */
+  async testValueTracking(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      await this.subscriber.trackValue('test_metric', 42, {
+        unit: 'ms',
+      });
+
+      await this.subscriber.trackValue('revenue', 99.99, {
+        currency: 'USD',
+      });
+
+      return {
+        name: 'Value Tracking',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Successfully tracked values',
+      };
+    } catch (error) {
+      return {
+        name: 'Value Tracking',
+        passed: false,
+        duration: performance.now() - startTime,
+        error: error as Error,
+      };
+    }
+  }
+
+  /**
+   * Test concurrent requests (sends 50 events simultaneously).
+   */
+  async testConcurrency(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      const promises = Array.from({ length: 50 }, (_, i) =>
+        this.subscriber.trackEvent(`concurrent_event_${i}`, {
+          index: i,
+          timestamp: Date.now(),
+        })
+      );
+
+      await Promise.all(promises);
+
+      return {
+        name: 'Concurrency',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Successfully handled 50 concurrent requests',
+      };
+    } catch (error) {
+      return {
+        name: 'Concurrency',
+        passed: false,
+        duration: performance.now() - startTime,
+        error: error as Error,
+      };
+    }
+  }
+
+  /**
+   * Test error handling (passes invalid data).
+   */
+  async testErrorHandling(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      // Test with empty event name
+      await this.subscriber.trackEvent('', {});
+
+      // Test with undefined attributes
+      await this.subscriber.trackEvent('test');
+
+      // Test with null-ish values
+      await this.subscriber.trackValue('test', 0, {});
+
+      return {
+        name: 'Error Handling',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Handled edge cases gracefully',
+      };
+    } catch {
+      // Some subscribers might throw on invalid input - that's OK
+      return {
+        name: 'Error Handling',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Subscriber throws on invalid input (acceptable)',
+      };
+    }
+  }
+
+  /**
+   * Test graceful shutdown.
+   */
+  async testShutdown(): Promise<TestResult> {
+    const startTime = performance.now();
+
+    try {
+      // Start some long-running operations
+      const promises = [
+        this.subscriber.trackEvent('shutdown_test_1', {}),
+        this.subscriber.trackEvent('shutdown_test_2', {}),
+        this.subscriber.trackEvent('shutdown_test_3', {}),
+      ];
+
+      // Call shutdown
+      await this.subscriber.shutdown?.();
+
+      // Wait for operations to complete
+      const results = await Promise.allSettled(promises);
+
+      const allSettled = results.every(
+        (r) => r.status === 'fulfilled' || r.status === 'rejected'
+      );
+
+      if (!allSettled) {
+        throw new Error('Some promises never settled');
+      }
+
+      return {
+        name: 'Graceful Shutdown',
+        passed: true,
+        duration: performance.now() - startTime,
+        details: 'Shutdown completed, all requests settled',
+      };
+    } catch (error) {
+      return {
+        name: 'Graceful Shutdown',
+        passed: false,
+        duration: performance.now() - startTime,
+        error: error as Error,
+      };
+    }
+  }
+
+  /**
+   * Pretty-print test results to console.
+   */
+  static printResults(results: TestSuiteResult): void {
+    console.log('\n' + '='.repeat(60));
+    console.log('📊 Subscriber Test Results');
+    console.log('='.repeat(60));
+    console.log(`\nTotal Tests: ${results.total}`);
+    console.log(`✅ Passed: ${results.passed_count}`);
+    console.log(`❌ Failed: ${results.failed_count}`);
+    console.log(`⏱️  Duration: ${results.duration.toFixed(2)}ms`);
+    console.log('\n' + '-'.repeat(60));
+
+    for (const result of results.results) {
+      const icon = result.passed ? '✅' : '❌';
+      const duration = result.duration.toFixed(2);
+      console.log(`${icon} ${result.name} (${duration}ms)`);
+
+      if (result.details) {
+        console.log(`   ${result.details}`);
+      }
+
+      if (result.error) {
+        console.log(`   Error: ${result.error.message}`);
+      }
+    }
+
+    console.log('='.repeat(60));
+
+    if (results.passed) {
+      console.log('\n🎉 All tests passed! Your subscriber is ready to use.');
+    } else {
+      console.log('\n⚠️  Some tests failed. Review the errors above.');
+    }
+
+    console.log('\n');
+  }
+}