@olane/o-test 0.7.12

package/dist/src/test-environment.js

@@ -0,0 +1,260 @@
+/**
+ * TestEnvironment - Core test setup and lifecycle management for O-Network nodes
+ *
+ * Provides automatic cleanup, node factories, and common test utilities
+ * to eliminate boilerplate in O-Network package tests.
+ *
+ * @example
+ * ```typescript
+ * describe('MyTool', () => {
+ *   const env = new TestEnvironment();
+ *
+ *   afterEach(async () => {
+ *     await env.cleanup();
+ *   });
+ *
+ *   it('should work', async () => {
+ *     const { leader, tool } = await env.createToolWithLeader(MyTool);
+ *     expect(tool.state).to.equal(NodeState.RUNNING);
+ *   });
+ * });
+ * ```
+ */
+import { NodeState } from '@olane/o-core';
+/**
+ * Core test environment class for O-Network testing
+ *
+ * Manages node lifecycle, automatic cleanup, and provides
+ * factory methods for common test scenarios.
+ */
+export class TestEnvironment {
+    constructor() {
+        this.nodes = [];
+        this.cleanupCallbacks = [];
+    }
+    /**
+     * Create a leader node for testing
+     *
+     * @param LeaderClass - Leader node class (e.g., oLeaderNode)
+     * @param options - Configuration options
+     * @returns Started leader node instance
+     *
+     * @example
+     * ```typescript
+     * const leader = await env.createLeader(oLeaderNode);
+     * ```
+     */
+    async createLeader(LeaderClass, options = {}) {
+        const { autoStart = true, ...config } = options;
+        const leader = new LeaderClass({
+            parent: null,
+            leader: null,
+            ...config,
+        });
+        this.track(leader);
+        if (autoStart) {
+            await leader.start();
+        }
+        return leader;
+    }
+    /**
+     * Create a tool with a leader node
+     *
+     * Automatically handles:
+     * - Leader creation and startup
+     * - Tool creation with parent/leader references
+     * - Hook injection for child registration
+     * - Lifecycle tracking for cleanup
+     *
+     * @param ToolClass - Tool class to instantiate
+     * @param config - Tool configuration
+     * @param LeaderClass - Leader class (defaults to oLeaderNode if available)
+     * @returns Object with leader and tool instances
+     *
+     * @example
+     * ```typescript
+     * const { leader, tool } = await env.createToolWithLeader(MyTool, {
+     *   apiKey: 'test-key'
+     * });
+     * ```
+     */
+    async createToolWithLeader(ToolClass, config = {}, LeaderClass) {
+        // Dynamic import to avoid circular dependency
+        let leader;
+        if (LeaderClass) {
+            leader = await this.createLeader(LeaderClass);
+        }
+        else {
+            // Try to import oLeaderNode dynamically
+            try {
+                const { oLeaderNode } = await import('@olane/o-leader');
+                leader = await this.createLeader(oLeaderNode);
+            }
+            catch (error) {
+                throw new Error('LeaderClass not provided and @olane/o-leader not available. ' +
+                    'Please provide LeaderClass explicitly.');
+            }
+        }
+        const tool = new ToolClass({
+            ...config,
+            parent: leader.address,
+            leader: leader.address,
+        });
+        // Inject hook for parent-child registration
+        const originalHook = tool.hookInitializeFinished?.bind(tool);
+        tool.hookInitializeFinished = async () => {
+            leader.addChildNode(tool);
+            if (originalHook) {
+                await originalHook();
+            }
+        };
+        this.track(tool);
+        await tool.start();
+        return { leader, tool };
+    }
+    /**
+     * Create a simple node without leader
+     *
+     * @param NodeClass - Node class to instantiate
+     * @param config - Node configuration
+     * @param autoStart - Whether to start node automatically (default: true)
+     * @returns Node instance
+     *
+     * @example
+     * ```typescript
+     * const node = await env.createNode(MyTool, {
+     *   address: new oNodeAddress('o://test')
+     * });
+     * ```
+     */
+    async createNode(NodeClass, config = {}, autoStart = true) {
+        const node = new NodeClass({
+            parent: null,
+            leader: null,
+            ...config,
+        });
+        this.track(node);
+        if (autoStart) {
+            await node.start();
+        }
+        return node;
+    }
+    /**
+     * Track a node for automatic cleanup
+     *
+     * @param node - Node instance to track
+     *
+     * @example
+     * ```typescript
+     * const node = new MyNode({});
+     * env.track(node);
+     * await node.start();
+     * ```
+     */
+    track(node) {
+        this.nodes.push(node);
+    }
+    /**
+     * Register a cleanup callback
+     *
+     * Useful for cleaning up external resources (databases, files, etc.)
+     *
+     * @param callback - Async cleanup function
+     *
+     * @example
+     * ```typescript
+     * const db = await createTestDB();
+     * env.onCleanup(async () => {
+     *   await db.close();
+     * });
+     * ```
+     */
+    onCleanup(callback) {
+        this.cleanupCallbacks.push(callback);
+    }
+    /**
+     * Stop all tracked nodes and execute cleanup callbacks
+     *
+     * Stops nodes in reverse order (children before parents)
+     * Call this in afterEach hooks.
+     *
+     * @example
+     * ```typescript
+     * afterEach(async () => {
+     *   await env.cleanup();
+     * });
+     * ```
+     */
+    async cleanup() {
+        // Stop nodes in reverse order (children first)
+        const nodesToStop = [...this.nodes].reverse();
+        for (const node of nodesToStop) {
+            try {
+                if (node.state === NodeState.RUNNING) {
+                    await node.stop();
+                }
+            }
+            catch (error) {
+                console.error('Error stopping node:', error);
+            }
+        }
+        // Execute cleanup callbacks
+        for (const callback of this.cleanupCallbacks) {
+            try {
+                await callback();
+            }
+            catch (error) {
+                console.error('Error in cleanup callback:', error);
+            }
+        }
+        // Clear tracking
+        this.nodes = [];
+        this.cleanupCallbacks = [];
+    }
+    /**
+     * Get all tracked nodes
+     *
+     * @returns Array of tracked node instances
+     */
+    getNodes() {
+        return [...this.nodes];
+    }
+    /**
+     * Get count of tracked nodes
+     *
+     * @returns Number of tracked nodes
+     */
+    getNodeCount() {
+        return this.nodes.length;
+    }
+    /**
+     * Check if all tracked nodes are stopped
+     *
+     * @returns True if all nodes are stopped
+     */
+    allNodesStopped() {
+        return this.nodes.every(node => node.state === NodeState.STOPPED);
+    }
+    /**
+     * Wait for a condition to be true
+     *
+     * @param condition - Function that returns true when condition is met
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @param intervalMs - Check interval in milliseconds (default: 100)
+     * @returns Promise that resolves when condition is met or rejects on timeout
+     *
+     * @example
+     * ```typescript
+     * await env.waitFor(() => tool.isReady, 10000);
+     * ```
+     */
+    async waitFor(condition, timeoutMs = 5000, intervalMs = 100) {
+        const startTime = Date.now();
+        while (!condition()) {
+            if (Date.now() - startTime > timeoutMs) {
+                throw new Error(`Timeout waiting for condition after ${timeoutMs}ms`);
+            }
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+    }
+}

package/dist/src/utils/assertions.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Assertion helpers for O-Network testing
+ *
+ * Provides type-safe, expressive assertions for common test scenarios
+ */
+import { oResponse } from '@olane/o-core';
+import type { oNode } from '@olane/o-node';
+/**
+ * Assert that a tool response indicates success
+ *
+ * @param response - Tool method response (oResponse)
+ * @param message - Optional custom error message
+ * @throws Error if response is not successful
+ *
+ * @example
+ * ```typescript
+ * const response = await tool.use(address, { method: 'test', params: {} });
+ * assertSuccess(response);
+ * ```
+ */
+export declare function assertSuccess(response: oResponse, message?: string): asserts response is oResponse & {
+    result: {
+        success: true;
+    };
+};
+/**
+ * Assert that a tool response indicates failure
+ *
+ * @param response - Tool method response (oResponse)
+ * @param expectedError - Optional substring to match in error message
+ * @throws Error if response is successful or error doesn't match
+ *
+ * @example
+ * ```typescript
+ * const response = await tool.use(address, { method: 'test', params: {} });
+ * assertError(response, 'required');
+ * ```
+ */
+export declare function assertError(response: oResponse, expectedError?: string): asserts response is oResponse & {
+    result: {
+        success: false;
+    };
+};
+/**
+ * Assert that a node is in running state
+ *
+ * @param node - Node instance
+ * @param message - Optional custom error message
+ * @throws Error if node is not running
+ *
+ * @example
+ * ```typescript
+ * assertRunning(tool);
+ * ```
+ */
+export declare function assertRunning(node: oNode, message?: string): void;
+/**
+ * Assert that a node is in stopped state
+ *
+ * @param node - Node instance
+ * @param message - Optional custom error message
+ * @throws Error if node is not stopped
+ *
+ * @example
+ * ```typescript
+ * await tool.stop();
+ * assertStopped(tool);
+ * ```
+ */
+export declare function assertStopped(node: oNode, message?: string): void;
+/**
+ * Assert that response has data
+ *
+ * @param response - Tool method response (oResponse)
+ * @param message - Optional custom error message
+ * @throws Error if response doesn't have data
+ *
+ * @example
+ * ```typescript
+ * const response = await tool.use(address, { method: 'get_data', params: {} });
+ * assertHasData(response);
+ * const data = response.result.data;
+ * ```
+ */
+export declare function assertHasData(response: oResponse, message?: string): asserts response is oResponse & {
+    result: {
+        data: any;
+    };
+};
+/**
+ * Assert that a value is defined (not null or undefined)
+ *
+ * @param value - Value to check
+ * @param name - Name of the value for error message
+ * @throws Error if value is null or undefined
+ *
+ * @example
+ * ```typescript
+ * assertDefined(user, 'user');
+ * // Now TypeScript knows user is not null/undefined
+ * ```
+ */
+export declare function assertDefined<T>(value: T, name?: string): asserts value is NonNullable<T>;
+/**
+ * Assert that an array has expected length
+ *
+ * @param array - Array to check
+ * @param expectedLength - Expected length
+ * @param message - Optional custom error message
+ * @throws Error if length doesn't match
+ *
+ * @example
+ * ```typescript
+ * assertArrayLength(items, 5);
+ * ```
+ */
+export declare function assertArrayLength(array: any[], expectedLength: number, message?: string): void;
+/**
+ * Assert that an object has a property
+ *
+ * @param obj - Object to check
+ * @param property - Property name
+ * @param message - Optional custom error message
+ * @throws Error if property doesn't exist
+ *
+ * @example
+ * ```typescript
+ * assertHasProperty(response.result.data, 'userId');
+ * ```
+ */
+export declare function assertHasProperty<T extends object, K extends PropertyKey>(obj: T, property: K, message?: string): asserts obj is T & Record<K, unknown>;
+/**
+ * Assert that a value matches one of the expected values
+ *
+ * @param value - Value to check
+ * @param expectedValues - Array of expected values
+ * @param message - Optional custom error message
+ * @throws Error if value doesn't match any expected value
+ *
+ * @example
+ * ```typescript
+ * assertOneOf(status, ['pending', 'active', 'completed']);
+ * ```
+ */
+export declare function assertOneOf<T>(value: T, expectedValues: T[], message?: string): void;
+/**
+ * Create a custom assertion
+ *
+ * @param condition - Condition to check
+ * @param message - Error message if condition is false
+ * @throws Error if condition is false
+ *
+ * @example
+ * ```typescript
+ * assert(user.age >= 18, 'User must be 18 or older');
+ * ```
+ */
+export declare function assert(condition: boolean, message: string): asserts condition;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/src/utils/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../../src/utils/assertions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAa,SAAS,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,IAAI,SAAS,GAAG;IAAE,MAAM,EAAE;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAA;CAAE,CAK/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,SAAS,EACnB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,QAAQ,IAAI,SAAS,GAAG;IAAE,MAAM,EAAE;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAA;CAAE,CAchE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAKN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAKN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,IAAI,SAAS,GAAG;IAAE,MAAM,EAAE;QAAE,IAAI,EAAE,GAAG,CAAA;KAAE,CAAA;CAAE,CAK3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,IAAI,GAAE,MAAgB,GACrB,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAIjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,GAAG,EAAE,EACZ,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAMN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EACvE,GAAG,EAAE,CAAC,EACN,QAAQ,EAAE,CAAC,EACX,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAMvC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,CAAC,EACR,cAAc,EAAE,CAAC,EAAE,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAMN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAInB"}

package/dist/src/utils/assertions.js

@@ -0,0 +1,201 @@
+/**
+ * Assertion helpers for O-Network testing
+ *
+ * Provides type-safe, expressive assertions for common test scenarios
+ */
+import { NodeState } from '@olane/o-core';
+/**
+ * Assert that a tool response indicates success
+ *
+ * @param response - Tool method response (oResponse)
+ * @param message - Optional custom error message
+ * @throws Error if response is not successful
+ *
+ * @example
+ * ```typescript
+ * const response = await tool.use(address, { method: 'test', params: {} });
+ * assertSuccess(response);
+ * ```
+ */
+export function assertSuccess(response, message) {
+    if (!response.result.success) {
+        const errorMsg = message || `Expected success but got error: ${response.result.error}`;
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Assert that a tool response indicates failure
+ *
+ * @param response - Tool method response (oResponse)
+ * @param expectedError - Optional substring to match in error message
+ * @throws Error if response is successful or error doesn't match
+ *
+ * @example
+ * ```typescript
+ * const response = await tool.use(address, { method: 'test', params: {} });
+ * assertError(response, 'required');
+ * ```
+ */
+export function assertError(response, expectedError) {
+    if (response.result.success) {
+        throw new Error('Expected error but got success');
+    }
+    const errorMessage = typeof response.result.error === 'string'
+        ? response.result.error
+        : response.result.error?.message || JSON.stringify(response.result.error);
+    if (expectedError && !errorMessage?.includes(expectedError)) {
+        throw new Error(`Expected error to include "${expectedError}" but got: ${errorMessage}`);
+    }
+}
+/**
+ * Assert that a node is in running state
+ *
+ * @param node - Node instance
+ * @param message - Optional custom error message
+ * @throws Error if node is not running
+ *
+ * @example
+ * ```typescript
+ * assertRunning(tool);
+ * ```
+ */
+export function assertRunning(node, message) {
+    if (node.state !== NodeState.RUNNING) {
+        const errorMsg = message || `Expected node to be RUNNING but got ${node.state}`;
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Assert that a node is in stopped state
+ *
+ * @param node - Node instance
+ * @param message - Optional custom error message
+ * @throws Error if node is not stopped
+ *
+ * @example
+ * ```typescript
+ * await tool.stop();
+ * assertStopped(tool);
+ * ```
+ */
+export function assertStopped(node, message) {
+    if (node.state !== NodeState.STOPPED) {
+        const errorMsg = message || `Expected node to be STOPPED but got ${node.state}`;
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Assert that response has data
+ *
+ * @param response - Tool method response (oResponse)
+ * @param message - Optional custom error message
+ * @throws Error if response doesn't have data
+ *
+ * @example
+ * ```typescript
+ * const response = await tool.use(address, { method: 'get_data', params: {} });
+ * assertHasData(response);
+ * const data = response.result.data;
+ * ```
+ */
+export function assertHasData(response, message) {
+    if (!response.result?.data) {
+        const errorMsg = message || 'Expected response to have result.data';
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Assert that a value is defined (not null or undefined)
+ *
+ * @param value - Value to check
+ * @param name - Name of the value for error message
+ * @throws Error if value is null or undefined
+ *
+ * @example
+ * ```typescript
+ * assertDefined(user, 'user');
+ * // Now TypeScript knows user is not null/undefined
+ * ```
+ */
+export function assertDefined(value, name = 'value') {
+    if (value === null || value === undefined) {
+        throw new Error(`Expected ${name} to be defined but got ${value}`);
+    }
+}
+/**
+ * Assert that an array has expected length
+ *
+ * @param array - Array to check
+ * @param expectedLength - Expected length
+ * @param message - Optional custom error message
+ * @throws Error if length doesn't match
+ *
+ * @example
+ * ```typescript
+ * assertArrayLength(items, 5);
+ * ```
+ */
+export function assertArrayLength(array, expectedLength, message) {
+    if (array.length !== expectedLength) {
+        const errorMsg = message ||
+            `Expected array length ${expectedLength} but got ${array.length}`;
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Assert that an object has a property
+ *
+ * @param obj - Object to check
+ * @param property - Property name
+ * @param message - Optional custom error message
+ * @throws Error if property doesn't exist
+ *
+ * @example
+ * ```typescript
+ * assertHasProperty(response.result.data, 'userId');
+ * ```
+ */
+export function assertHasProperty(obj, property, message) {
+    if (!(property in obj)) {
+        const errorMsg = message ||
+            `Expected object to have property "${String(property)}"`;
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Assert that a value matches one of the expected values
+ *
+ * @param value - Value to check
+ * @param expectedValues - Array of expected values
+ * @param message - Optional custom error message
+ * @throws Error if value doesn't match any expected value
+ *
+ * @example
+ * ```typescript
+ * assertOneOf(status, ['pending', 'active', 'completed']);
+ * ```
+ */
+export function assertOneOf(value, expectedValues, message) {
+    if (!expectedValues.includes(value)) {
+        const errorMsg = message ||
+            `Expected one of [${expectedValues.join(', ')}] but got ${value}`;
+        throw new Error(errorMsg);
+    }
+}
+/**
+ * Create a custom assertion
+ *
+ * @param condition - Condition to check
+ * @param message - Error message if condition is false
+ * @throws Error if condition is false
+ *
+ * @example
+ * ```typescript
+ * assert(user.age >= 18, 'User must be 18 or older');
+ * ```
+ */
+export function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}