@agentforge/testing 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,708 @@
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { BaseMessage } from '@langchain/core/messages';
+import { ChatResult } from '@langchain/core/outputs';
+import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import * as _agentforge_core from '@agentforge/core';
+import { ToolCategory, Tool } from '@agentforge/core';
+import { z } from 'zod';
+
+/**
+ * Configuration for MockLLM
+ */
+interface MockLLMConfig {
+    /**
+     * Predefined responses to return
+     */
+    responses?: string[];
+    /**
+     * Response generator function
+     */
+    responseGenerator?: (messages: BaseMessage[]) => string;
+    /**
+     * Delay in milliseconds before responding
+     */
+    delay?: number;
+    /**
+     * Whether to throw an error
+     */
+    shouldError?: boolean;
+    /**
+     * Error message to throw
+     */
+    errorMessage?: string;
+    /**
+     * Model name to report
+     */
+    modelName?: string;
+}
+/**
+ * Mock LLM for testing
+ *
+ * @example
+ * ```typescript
+ * const llm = createMockLLM({
+ *   responses: ['Hello!', 'How can I help?']
+ * });
+ *
+ * const result = await llm.invoke([new HumanMessage('Hi')]);
+ * console.log(result.content); // 'Hello!'
+ * ```
+ */
+declare class MockLLM extends BaseChatModel {
+    private responses;
+    private responseGenerator?;
+    private delay;
+    private shouldError;
+    private errorMessage;
+    private callCount;
+    _llmType(): string;
+    constructor(config?: MockLLMConfig);
+    _generate(messages: BaseMessage[], options?: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): Promise<ChatResult>;
+    /**
+     * Get the number of times the LLM has been called
+     */
+    getCallCount(): number;
+    /**
+     * Reset the call count
+     */
+    resetCallCount(): void;
+}
+/**
+ * Create a mock LLM for testing
+ */
+declare function createMockLLM(config?: MockLLMConfig): MockLLM;
+/**
+ * Create a mock LLM that echoes the last message
+ */
+declare function createEchoLLM(): MockLLM;
+/**
+ * Create a mock LLM that always errors
+ */
+declare function createErrorLLM(errorMessage?: string): MockLLM;
+
+/**
+ * Configuration for mock tool
+ */
+interface MockToolConfig<T extends z.ZodType = z.ZodType> {
+    /**
+     * Tool name
+     */
+    name?: string;
+    /**
+     * Tool description
+     */
+    description?: string;
+    /**
+     * Tool category
+     */
+    category?: ToolCategory;
+    /**
+     * Input schema
+     */
+    schema?: T;
+    /**
+     * Implementation function
+     */
+    implementation?: (input: z.infer<T>) => Promise<string> | string;
+    /**
+     * Whether to throw an error
+     */
+    shouldError?: boolean;
+    /**
+     * Error message to throw
+     */
+    errorMessage?: string;
+    /**
+     * Delay in milliseconds before responding
+     */
+    delay?: number;
+}
+/**
+ * Create a mock tool for testing
+ *
+ * @example
+ * ```typescript
+ * const tool = createMockTool({
+ *   name: 'test_tool',
+ *   schema: z.object({ input: z.string().describe('Input') }),
+ *   implementation: async ({ input }) => `Processed: ${input}`
+ * });
+ *
+ * const result = await tool.execute({ input: 'test' });
+ * console.log(result); // 'Processed: test'
+ * ```
+ */
+declare function createMockTool<T extends z.ZodType = any>(config?: MockToolConfig<T>): _agentforge_core.Tool<any, string>;
+/**
+ * Create a mock tool that echoes its input
+ */
+declare function createEchoTool(name?: string): _agentforge_core.Tool<any, string>;
+/**
+ * Create a mock tool that always errors
+ */
+declare function createErrorTool(name?: string, errorMessage?: string): _agentforge_core.Tool<any, string>;
+/**
+ * Create a mock tool with delay
+ */
+declare function createDelayedTool(name?: string, delay?: number): _agentforge_core.Tool<any, string>;
+/**
+ * Create a calculator mock tool
+ */
+declare function createCalculatorTool(): _agentforge_core.Tool<any, string>;
+
+/**
+ * Builder for creating test states
+ */
+declare class StateBuilder<T extends Record<string, any> = Record<string, any>> {
+    private state;
+    /**
+     * Set a field in the state
+     */
+    set<K extends keyof T>(key: K, value: T[K]): this;
+    /**
+     * Set multiple fields in the state
+     */
+    setMany(fields: Partial<T>): this;
+    /**
+     * Add a message to the messages array
+     */
+    addMessage(message: BaseMessage): this;
+    /**
+     * Add multiple messages
+     */
+    addMessages(messages: BaseMessage[]): this;
+    /**
+     * Add a human message
+     */
+    addHumanMessage(content: string): this;
+    /**
+     * Add an AI message
+     */
+    addAIMessage(content: string): this;
+    /**
+     * Add a system message
+     */
+    addSystemMessage(content: string): this;
+    /**
+     * Build the state
+     */
+    build(): T;
+    /**
+     * Reset the builder
+     */
+    reset(): this;
+}
+/**
+ * Create a state builder
+ */
+declare function createStateBuilder<T extends Record<string, any> = Record<string, any>>(): StateBuilder<T>;
+/**
+ * Create a simple conversation state
+ */
+declare function createConversationState(messages: string[]): {
+    messages: BaseMessage[];
+};
+/**
+ * Create a ReAct agent state
+ */
+declare function createReActState(config?: {
+    messages?: BaseMessage[];
+    thoughts?: string[];
+    toolCalls?: Array<{
+        name: string;
+        args: any;
+    }>;
+    toolResults?: Array<{
+        name: string;
+        result: string;
+    }>;
+    scratchpad?: string[];
+    iterations?: number;
+    maxIterations?: number;
+}): any;
+/**
+ * Create a planning agent state
+ */
+declare function createPlanningState(config?: {
+    messages?: BaseMessage[];
+    plan?: Array<{
+        step: string;
+        status: string;
+    }>;
+    currentStep?: number;
+    results?: Record<string, any>;
+}): any;
+
+/**
+ * Assert that a value is a message of a specific type
+ */
+declare function assertIsMessage(value: any, type?: 'human' | 'ai' | 'system'): asserts value is BaseMessage;
+/**
+ * Assert that messages array contains a message with specific content
+ */
+declare function assertMessageContains(messages: BaseMessage[], content: string): void;
+/**
+ * Assert that the last message contains specific content
+ */
+declare function assertLastMessageContains(messages: BaseMessage[], content: string): void;
+/**
+ * Assert that state has required fields
+ */
+declare function assertStateHasFields<T extends Record<string, any>>(state: T, fields: (keyof T)[]): void;
+/**
+ * Assert that a tool was called with specific arguments
+ */
+declare function assertToolCalled(toolCalls: Array<{
+    name: string;
+    args: any;
+}>, toolName: string, args?: Record<string, any>): void;
+/**
+ * Assert that execution completed within time limit
+ */
+declare function assertCompletesWithin(fn: () => Promise<any>, maxMs: number): Promise<void>;
+/**
+ * Assert that a function throws an error with specific message
+ */
+declare function assertThrowsWithMessage(fn: () => Promise<any>, message: string): Promise<void>;
+/**
+ * Assert that state matches a snapshot
+ */
+declare function assertStateSnapshot(state: any, snapshot: any): void;
+/**
+ * Assert that messages have alternating types (human, ai, human, ai, ...)
+ */
+declare function assertAlternatingMessages(messages: BaseMessage[]): void;
+/**
+ * Assert that an array is not empty
+ */
+declare function assertNotEmpty<T>(array: T[]): void;
+/**
+ * Assert that a value is within a range
+ */
+declare function assertInRange(value: number, min: number, max: number): void;
+/**
+ * Assert that agent iterations are within limit
+ */
+declare function assertIterationsWithinLimit(iterations: number, maxIterations: number): void;
+/**
+ * Assert that a result contains expected keys
+ */
+declare function assertHasKeys<T extends Record<string, any>>(obj: T, keys: string[]): void;
+
+/**
+ * Sample conversation: Simple greeting
+ */
+declare const simpleGreeting: BaseMessage[];
+/**
+ * Sample conversation: Multi-turn conversation
+ */
+declare const multiTurnConversation: BaseMessage[];
+/**
+ * Sample conversation: Tool usage
+ */
+declare const toolUsageConversation: BaseMessage[];
+/**
+ * Sample conversation: Error handling
+ */
+declare const errorHandlingConversation: BaseMessage[];
+/**
+ * Sample conversation: Complex reasoning
+ */
+declare const complexReasoningConversation: BaseMessage[];
+/**
+ * Sample conversation: Long context
+ */
+declare const longContextConversation: BaseMessage[];
+/**
+ * Create a custom conversation
+ */
+declare function createConversation(exchanges: Array<{
+    human: string;
+    ai: string;
+}>): BaseMessage[];
+/**
+ * Create a conversation with system message
+ */
+declare function createConversationWithSystem(systemPrompt: string, exchanges: Array<{
+    human: string;
+    ai: string;
+}>): BaseMessage[];
+/**
+ * Sample data for testing
+ */
+declare const sampleData: {
+    /**
+     * Sample user inputs
+     */
+    userInputs: string[];
+    /**
+     * Sample AI responses
+     */
+    aiResponses: string[];
+    /**
+     * Sample tool calls
+     */
+    toolCalls: ({
+        name: string;
+        args: {
+            operation: string;
+            a: number;
+            b: number;
+            query?: undefined;
+        };
+    } | {
+        name: string;
+        args: {
+            query: string;
+            operation?: undefined;
+            a?: undefined;
+            b?: undefined;
+        };
+    } | {
+        name: string;
+        args: {
+            operation?: undefined;
+            a?: undefined;
+            b?: undefined;
+            query?: undefined;
+        };
+    })[];
+    /**
+     * Sample tool results
+     */
+    toolResults: {
+        name: string;
+        result: string;
+    }[];
+};
+
+/**
+ * Sample calculator tool
+ */
+declare const calculatorTool: Tool<{
+    operation: "add" | "subtract" | "multiply" | "divide";
+    a: number;
+    b: number;
+}, string>;
+/**
+ * Sample search tool
+ */
+declare const searchTool: Tool<{
+    query: string;
+    limit?: number | undefined;
+}, string>;
+/**
+ * Sample time tool
+ */
+declare const timeTool: Tool<{
+    _dummy?: string | undefined;
+}, string>;
+/**
+ * Sample weather tool
+ */
+declare const weatherTool: Tool<{
+    location: string;
+    units?: "celsius" | "fahrenheit" | undefined;
+}, string>;
+/**
+ * Sample file reader tool
+ */
+declare const fileReaderTool: Tool<{
+    path: string;
+}, string>;
+/**
+ * Sample database query tool
+ */
+declare const databaseQueryTool: Tool<{
+    query: string;
+}, string>;
+/**
+ * All sample tools
+ */
+declare const sampleTools: (Tool<{
+    operation: "add" | "subtract" | "multiply" | "divide";
+    a: number;
+    b: number;
+}, string> | Tool<{
+    query: string;
+    limit?: number | undefined;
+}, string> | Tool<{
+    _dummy?: string | undefined;
+}, string> | Tool<{
+    location: string;
+    units?: "celsius" | "fahrenheit" | undefined;
+}, string> | Tool<{
+    path: string;
+}, string> | Tool<{
+    query: string;
+}, string>)[];
+/**
+ * Get tools by category
+ */
+declare function getToolsByCategory(category: ToolCategory): (Tool<{
+    operation: "add" | "subtract" | "multiply" | "divide";
+    a: number;
+    b: number;
+}, string> | Tool<{
+    query: string;
+    limit?: number | undefined;
+}, string> | Tool<{
+    _dummy?: string | undefined;
+}, string> | Tool<{
+    location: string;
+    units?: "celsius" | "fahrenheit" | undefined;
+}, string> | Tool<{
+    path: string;
+}, string> | Tool<{
+    query: string;
+}, string>)[];
+/**
+ * Get tool by name
+ */
+declare function getToolByName(name: string): Tool<{
+    operation: "add" | "subtract" | "multiply" | "divide";
+    a: number;
+    b: number;
+}, string> | Tool<{
+    query: string;
+    limit?: number | undefined;
+}, string> | Tool<{
+    _dummy?: string | undefined;
+}, string> | Tool<{
+    location: string;
+    units?: "celsius" | "fahrenheit" | undefined;
+}, string> | Tool<{
+    path: string;
+}, string> | Tool<{
+    query: string;
+}, string> | undefined;
+
+/**
+ * Configuration for agent test runner
+ */
+interface AgentTestConfig {
+    /**
+     * Maximum time to wait for agent response (ms)
+     */
+    timeout?: number;
+    /**
+     * Whether to capture intermediate steps
+     */
+    captureSteps?: boolean;
+    /**
+     * Whether to validate state after each step
+     */
+    validateState?: boolean;
+    /**
+     * Custom state validator
+     */
+    stateValidator?: (state: any) => boolean | Promise<boolean>;
+}
+/**
+ * Result from agent test run
+ */
+interface AgentTestResult {
+    /**
+     * Final state after execution
+     */
+    finalState: any;
+    /**
+     * Messages exchanged
+     */
+    messages: BaseMessage[];
+    /**
+     * Execution time in milliseconds
+     */
+    executionTime: number;
+    /**
+     * Intermediate steps (if captured)
+     */
+    steps?: any[];
+    /**
+     * Whether the test passed
+     */
+    passed: boolean;
+    /**
+     * Error if test failed
+     */
+    error?: Error;
+}
+/**
+ * Agent test runner for integration testing
+ *
+ * @example
+ * ```typescript
+ * const runner = new AgentTestRunner(agent, {
+ *   timeout: 5000,
+ *   captureSteps: true
+ * });
+ *
+ * const result = await runner.run({
+ *   messages: [new HumanMessage('Hello')]
+ * });
+ *
+ * expect(result.passed).toBe(true);
+ * expect(result.messages.length).toBeGreaterThan(1);
+ * ```
+ */
+declare class AgentTestRunner {
+    private agent;
+    private config;
+    constructor(agent: any, config?: AgentTestConfig);
+    /**
+     * Run the agent with given input
+     */
+    run(input: any): Promise<AgentTestResult>;
+    /**
+     * Run multiple test cases
+     */
+    runMany(inputs: any[]): Promise<AgentTestResult[]>;
+}
+/**
+ * Create an agent test runner
+ */
+declare function createAgentTestRunner(agent: any, config?: AgentTestConfig): AgentTestRunner;
+
+/**
+ * Configuration for conversation simulator
+ */
+interface ConversationSimulatorConfig {
+    /**
+     * Maximum number of turns
+     */
+    maxTurns?: number;
+    /**
+     * Delay between turns (ms)
+     */
+    turnDelay?: number;
+    /**
+     * Whether to log conversation
+     */
+    verbose?: boolean;
+    /**
+     * Stop condition
+     */
+    stopCondition?: (messages: BaseMessage[]) => boolean;
+}
+/**
+ * Result from conversation simulation
+ */
+interface ConversationResult {
+    /**
+     * All messages in the conversation
+     */
+    messages: BaseMessage[];
+    /**
+     * Number of turns
+     */
+    turns: number;
+    /**
+     * Total execution time (ms)
+     */
+    totalTime: number;
+    /**
+     * Whether conversation completed successfully
+     */
+    completed: boolean;
+    /**
+     * Reason for stopping
+     */
+    stopReason: 'max_turns' | 'stop_condition' | 'error';
+    /**
+     * Error if any
+     */
+    error?: Error;
+}
+/**
+ * Conversation simulator for testing multi-turn interactions
+ *
+ * @example
+ * ```typescript
+ * const simulator = new ConversationSimulator(agent, {
+ *   maxTurns: 5,
+ *   verbose: true
+ * });
+ *
+ * const result = await simulator.simulate([
+ *   'Hello',
+ *   'What can you do?',
+ *   'Help me calculate 2 + 2'
+ * ]);
+ *
+ * expect(result.turns).toBe(3);
+ * expect(result.completed).toBe(true);
+ * ```
+ */
+declare class ConversationSimulator {
+    private agent;
+    private config;
+    constructor(agent: any, config?: ConversationSimulatorConfig);
+    /**
+     * Simulate a conversation with predefined user inputs
+     */
+    simulate(userInputs: string[]): Promise<ConversationResult>;
+    /**
+     * Simulate a conversation with dynamic user input generation
+     */
+    simulateDynamic(inputGenerator: (messages: BaseMessage[]) => string | null, maxTurns?: number): Promise<ConversationResult>;
+}
+/**
+ * Create a conversation simulator
+ */
+declare function createConversationSimulator(agent: any, config?: ConversationSimulatorConfig): ConversationSimulator;
+
+/**
+ * Snapshot configuration
+ */
+interface SnapshotConfig {
+    /**
+     * Fields to include in snapshot
+     */
+    includeFields?: string[];
+    /**
+     * Fields to exclude from snapshot
+     */
+    excludeFields?: string[];
+    /**
+     * Whether to normalize timestamps
+     */
+    normalizeTimestamps?: boolean;
+    /**
+     * Whether to normalize IDs
+     */
+    normalizeIds?: boolean;
+    /**
+     * Custom normalizer function
+     */
+    normalizer?: (value: any) => any;
+}
+/**
+ * Create a snapshot of state
+ */
+declare function createSnapshot(state: any, config?: SnapshotConfig): any;
+/**
+ * Assert that state matches snapshot
+ */
+declare function assertMatchesSnapshot(state: any, config?: SnapshotConfig): void;
+/**
+ * Create a snapshot of messages
+ */
+declare function createMessageSnapshot(messages: BaseMessage[], config?: SnapshotConfig): any;
+/**
+ * Assert that messages match snapshot
+ */
+declare function assertMessagesMatchSnapshot(messages: BaseMessage[], config?: SnapshotConfig): void;
+/**
+ * Compare two states for equality
+ */
+declare function compareStates(state1: any, state2: any, config?: SnapshotConfig): boolean;
+/**
+ * Create a diff between two states
+ */
+declare function createStateDiff(state1: any, state2: any, config?: SnapshotConfig): any;
+/**
+ * Assert that state has changed
+ */
+declare function assertStateChanged(stateBefore: any, stateAfter: any, expectedChanges: string[], config?: SnapshotConfig): void;
+
+export { type AgentTestConfig, type AgentTestResult, AgentTestRunner, type ConversationResult, ConversationSimulator, type ConversationSimulatorConfig, MockLLM, type MockLLMConfig, type MockToolConfig, type SnapshotConfig, StateBuilder, assertAlternatingMessages, assertCompletesWithin, assertHasKeys, assertInRange, assertIsMessage, assertIterationsWithinLimit, assertLastMessageContains, assertMatchesSnapshot, assertMessageContains, assertMessagesMatchSnapshot, assertNotEmpty, assertStateChanged, assertStateHasFields, assertStateSnapshot, assertThrowsWithMessage, assertToolCalled, calculatorTool, compareStates, complexReasoningConversation, createAgentTestRunner, createCalculatorTool, createConversation, createConversationSimulator, createConversationState, createConversationWithSystem, createDelayedTool, createEchoLLM, createEchoTool, createErrorLLM, createErrorTool, createMessageSnapshot, createMockLLM, createMockTool, createPlanningState, createReActState, createSnapshot, createStateBuilder, createStateDiff, databaseQueryTool, errorHandlingConversation, fileReaderTool, getToolByName, getToolsByCategory, longContextConversation, multiTurnConversation, sampleData, sampleTools, searchTool, simpleGreeting, timeTool, toolUsageConversation, weatherTool };