@flink-app/test-utils 1.0.0 → 2.0.0-alpha.49

package/spec/ai/mockTool.spec.ts

@@ -0,0 +1,313 @@
+import { z } from "zod";
+import { mockTool } from "../../src/ai/mockTool";
+import { mockToolContext } from "../../src/ai/mockContext";
+
+describe("mockTool", () => {
+  describe("canned responses", () => {
+    it("should return canned success response", async () => {
+      const tool = mockTool({
+        name: "get_weather",
+        inputSchema: z.object({ city: z.string() }),
+        response: { temperature: 22, conditions: "sunny" },
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({
+        input: { city: "Stockholm" },
+        ctx,
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toEqual({ temperature: 22, conditions: "sunny" });
+      }
+    });
+
+    it("should return canned error response", async () => {
+      const tool = mockTool({
+        name: "failing_tool",
+        inputSchema: z.object({}),
+        error: { error: "Tool failed", code: "MOCK_ERROR" },
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({ input: {}, ctx });
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toBe("Tool failed");
+        expect(result.code).toBe("MOCK_ERROR");
+      }
+    });
+
+    it("should return empty object when no response configured", async () => {
+      const tool = mockTool({
+        name: "empty_tool",
+        inputSchema: z.object({}),
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({ input: {}, ctx });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toEqual({});
+      }
+    });
+  });
+
+  describe("custom functions", () => {
+    it("should execute custom function", async () => {
+      const tool = mockTool({
+        name: "calculate",
+        inputSchema: z.object({ a: z.number(), b: z.number() }),
+        fn: async ({ input }) => ({
+          success: true,
+          data: { result: input.a + input.b },
+        }),
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({
+        input: { a: 5, b: 3 },
+        ctx,
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.result).toBe(8);
+      }
+    });
+
+    it("should pass context to custom function", async () => {
+      const mockRepo = { findById: jasmine.createSpy("findById") };
+      const tool = mockTool({
+        name: "get_car",
+        inputSchema: z.object({ id: z.string() }),
+        fn: async ({ input, ctx }) => {
+          (ctx.repos as any).carRepo.findById(input.id);
+          return { success: true, data: { car: "data" } };
+        },
+      });
+
+      const ctx = mockToolContext({ repos: { carRepo: mockRepo as any } });
+      await tool.fn({ input: { id: "123" }, ctx });
+
+      expect(mockRepo.findById).toHaveBeenCalledWith("123");
+    });
+
+    it("should pass user to custom function", async () => {
+      const tool = mockTool({
+        name: "user_tool",
+        inputSchema: z.object({}),
+        fn: async ({ user }) => ({
+          success: true,
+          data: { userId: user?.id },
+        }),
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({
+        input: {},
+        ctx,
+        user: { id: "user-123" },
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.userId).toBe("user-123");
+      }
+    });
+  });
+
+  describe("invocation tracking", () => {
+    it("should track invocations", async () => {
+      const tool = mockTool({
+        name: "test_tool",
+        inputSchema: z.object({ value: z.string() }),
+        response: { ok: true },
+      });
+
+      const ctx = mockToolContext();
+      await tool.fn({ input: { value: "first" }, ctx });
+      await tool.fn({ input: { value: "second" }, ctx });
+      await tool.fn({ input: { value: "third" }, ctx });
+
+      expect(tool.invocations.length).toBe(3);
+      expect(tool.invocations[0].input).toEqual({ value: "first" });
+      expect(tool.invocations[1].input).toEqual({ value: "second" });
+      expect(tool.invocations[2].input).toEqual({ value: "third" });
+    });
+
+    it("should track user in invocations", async () => {
+      const tool = mockTool({
+        name: "test_tool",
+        inputSchema: z.object({}),
+        response: { ok: true },
+      });
+
+      const ctx = mockToolContext();
+      const user = { id: "user-123", permissions: ["admin"] };
+      await tool.fn({ input: {}, ctx, user });
+
+      expect(tool.invocations.length).toBe(1);
+      expect(tool.invocations[0].user).toEqual(user);
+    });
+
+    it("should get last invocation", async () => {
+      const tool = mockTool({
+        name: "test_tool",
+        inputSchema: z.object({ value: z.string() }),
+        response: { ok: true },
+      });
+
+      const ctx = mockToolContext();
+      await tool.fn({ input: { value: "first" }, ctx });
+      await tool.fn({ input: { value: "last" }, ctx });
+
+      const last = tool.getLastInvocation();
+      expect(last?.input).toEqual({ value: "last" });
+    });
+
+    it("should return undefined for last invocation when empty", () => {
+      const tool = mockTool({
+        name: "test_tool",
+        inputSchema: z.object({}),
+        response: {},
+      });
+
+      expect(tool.getLastInvocation()).toBeUndefined();
+    });
+
+    it("should reset invocations", async () => {
+      const tool = mockTool({
+        name: "test_tool",
+        inputSchema: z.object({}),
+        response: { ok: true },
+      });
+
+      const ctx = mockToolContext();
+      await tool.fn({ input: {}, ctx });
+      await tool.fn({ input: {}, ctx });
+
+      expect(tool.invocations.length).toBe(2);
+
+      tool.reset();
+
+      expect(tool.invocations.length).toBe(0);
+      expect(tool.getLastInvocation()).toBeUndefined();
+    });
+  });
+
+  describe("tool props", () => {
+    it("should create correct tool props", () => {
+      const inputSchema = z.object({ city: z.string() });
+      const outputSchema = z.object({ temp: z.number() });
+
+      const tool = mockTool({
+        name: "get_weather",
+        description: "Get weather for a city",
+        inputSchema,
+        outputSchema,
+        response: { temp: 22 },
+      });
+
+      expect(tool.props.id).toBe("get_weather");
+      expect(tool.props.description).toBe("Get weather for a city");
+      expect(tool.props.inputSchema).toBe(inputSchema);
+      expect(tool.props.outputSchema).toBe(outputSchema);
+    });
+
+    it("should use default description when not provided", () => {
+      const tool = mockTool({
+        name: "test_tool",
+        inputSchema: z.object({}),
+        response: {},
+      });
+
+      expect(tool.props.description).toBe("Mock tool: test_tool");
+    });
+
+    it("should include permissions in props", () => {
+      const tool = mockTool({
+        name: "admin_tool",
+        inputSchema: z.object({}),
+        permissions: "admin",
+        response: {},
+      });
+
+      expect(tool.props.permissions).toBe("admin");
+    });
+
+    it("should handle array permissions", () => {
+      const tool = mockTool({
+        name: "multi_perm_tool",
+        inputSchema: z.object({}),
+        permissions: ["admin", "moderator"],
+        response: {},
+      });
+
+      expect(tool.props.permissions).toEqual(["admin", "moderator"]);
+    });
+  });
+
+  describe("integration with custom function", () => {
+    it("should track invocations for custom function", async () => {
+      const tool = mockTool({
+        name: "custom_tool",
+        inputSchema: z.object({ value: z.number() }),
+        fn: async ({ input }) => ({
+          success: true,
+          data: { doubled: input.value * 2 },
+        }),
+      });
+
+      const ctx = mockToolContext();
+      await tool.fn({ input: { value: 5 }, ctx });
+      await tool.fn({ input: { value: 10 }, ctx });
+
+      expect(tool.invocations.length).toBe(2);
+      expect(tool.invocations[0].input.value).toBe(5);
+      expect(tool.invocations[1].input.value).toBe(10);
+    });
+
+    it("should prioritize custom function over canned response", async () => {
+      const tool = mockTool<{}, { canned?: boolean; custom?: boolean }>({
+        name: "priority_tool",
+        inputSchema: z.object({}),
+        response: { canned: true },
+        fn: async () => ({ success: true, data: { custom: true } }),
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({ input: {}, ctx });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toEqual({ custom: true });
+      }
+    });
+  });
+
+  describe("type inference", () => {
+    it("should infer input and output types", async () => {
+      const tool = mockTool({
+        name: "typed_tool",
+        inputSchema: z.object({
+          city: z.string(),
+          country: z.string().optional(),
+        }),
+        response: { temperature: 22, conditions: "sunny" },
+      });
+
+      const ctx = mockToolContext();
+      const result = await tool.fn({
+        input: { city: "Stockholm" },
+        ctx,
+      });
+
+      // TypeScript should enforce these types
+      expect(result.success).toBe(true);
+    });
+  });
+});

package/spec/support/jasmine.json

@@ -0,0 +1,7 @@
+{
+  "spec_dir": "spec",
+  "spec_files": ["**/*[sS]pec.ts"],
+  "helpers": ["helpers/**/*.ts"],
+  "stopSpecOnExpectationFailure": false,
+  "random": false
+}

package/src/ai/conversation.ts

@@ -0,0 +1,54 @@
+import type { Message, ToolCall } from "@flink-app/flink/ai";
+
+/**
+ * Fluent builder for multi-turn conversation testing
+ * Simplifies creating conversation histories
+ *
+ * @example
+ * const conversation = createConversation()
+ *   .user("Book a flight to Paris")
+ *   .assistant("When would you like to travel?")
+ *   .user("Next Monday")
+ *   .assistant("Let me search", [
+ *     { id: "1", name: "search_flights", input: { destination: "Paris" } }
+ *   ])
+ *   .tool("1", "search_flights", JSON.stringify({ flights: [...] }))
+ *   .assistant("I found these flights...")
+ *   .build();
+ */
+export interface ConversationBuilder {
+  user(content: string): ConversationBuilder;
+  assistant(content: string, toolCalls?: ToolCall[]): ConversationBuilder;
+  tool(toolCallId: string, toolName: string, result: string): ConversationBuilder;
+  build(): Message[];
+}
+
+class ConversationBuilderImpl implements ConversationBuilder {
+  private messages: Message[] = [];
+
+  user(content: string): ConversationBuilder {
+    this.messages.push({ role: "user", content });
+    return this;
+  }
+
+  assistant(content: string, toolCalls?: ToolCall[]): ConversationBuilder {
+    this.messages.push({ role: "assistant", content, toolCalls });
+    return this;
+  }
+
+  tool(toolCallId: string, toolName: string, result: string): ConversationBuilder {
+    this.messages.push({ role: "tool", toolCallId, toolName, result });
+    return this;
+  }
+
+  build(): Message[] {
+    return this.messages;
+  }
+}
+
+/**
+ * Creates a new conversation builder
+ */
+export function createConversation(): ConversationBuilder {
+  return new ConversationBuilderImpl();
+}

package/src/ai/index.ts

@@ -0,0 +1,4 @@
+export * from "./mockLLMAdapter";
+export * from "./mockTool";
+export * from "./mockContext";
+export * from "./conversation";

package/src/ai/mockContext.ts

@@ -0,0 +1,41 @@
+import { FlinkContext } from "@flink-app/flink";
+
+/**
+ * Creates a mock FlinkContext for tool testing
+ * Provides sensible defaults for all required properties
+ *
+ * @example
+ * const ctx = mockToolContext({
+ *   repos: { carRepo: mockCarRepo },
+ *   plugins: { email: mockEmailPlugin }
+ * });
+ *
+ * @example
+ * // Minimal usage with defaults
+ * const ctx = mockToolContext();
+ */
+export function mockToolContext<Ctx extends FlinkContext = FlinkContext>(overrides: Partial<Ctx> = {}): Ctx {
+    const defaultContext: FlinkContext = {
+        repos: {},
+        plugins: {},
+        agents: {},
+    };
+
+    return {
+        ...defaultContext,
+        ...overrides,
+        // Deep merge repos, plugins, and agents
+        repos: {
+            ...defaultContext.repos,
+            ...(overrides.repos || {}),
+        },
+        plugins: {
+            ...defaultContext.plugins,
+            ...(overrides.plugins || {}),
+        },
+        agents: {
+            ...(defaultContext.agents || {}),
+            ...((overrides as any).agents || {}),
+        },
+    } as Ctx;
+}

package/src/ai/mockLLMAdapter.ts

@@ -0,0 +1,238 @@
+import { LLMAdapter, LLMMessage, LLMStreamChunk } from "@flink-app/flink/ai";
+
+export interface MockLLMConfig {
+    // Simple single response
+    response?: string;
+
+    // Multiple responses for multi-turn (queued)
+    responses?: Array<{
+        text?: string;
+        toolCalls?: Array<{ id: string; name: string; input: any }>;
+        stopReason?: "end_turn" | "tool_use" | "max_tokens";
+        streamChunks?: LLMStreamChunk[]; // Explicitly define streaming chunks
+    }>;
+
+    // Error simulation
+    error?: Error;
+
+    // Token usage simulation
+    usage?: { inputTokens: number; outputTokens: number };
+
+    // Default stream chunks if not specified per response
+    defaultStreamChunks?: LLMStreamChunk[];
+}
+
+export interface MockLLMAdapterInvocation {
+    instructions: string;
+    messages: LLMMessage[];
+    tools: any[];
+    maxTokens: number;
+    temperature: number;
+}
+
+export interface MockLLMAdapter extends LLMAdapter {
+    // Automatic invocation tracking
+    invocations: MockLLMAdapterInvocation[];
+
+    // Utilities
+    reset(): void;
+    getLastInvocation(): MockLLMAdapterInvocation | undefined;
+    getInvocationCount(): number;
+}
+
+/**
+ * Creates a mock LLM adapter for testing agents without API calls
+ *
+ * Features:
+ * - Canned responses (single or multi-turn)
+ * - Tool call simulation
+ * - Error simulation
+ * - Automatic invocation tracking
+ * - Token usage simulation
+ *
+ * @example
+ * // Simple response
+ * const adapter = mockLLMAdapter({ response: "Hello!" });
+ *
+ * @example
+ * // Multi-turn with tool calls
+ * const adapter = mockLLMAdapter({
+ *   responses: [
+ *     {
+ *       text: "Let me check",
+ *       toolCalls: [{ id: "1", name: "get_weather", input: { city: "Stockholm" } }]
+ *     },
+ *     { text: "It's sunny and 22°C" }
+ *   ]
+ * });
+ *
+ * @example
+ * // Error simulation
+ * const adapter = mockLLMAdapter({
+ *   error: new Error("Rate limit exceeded")
+ * });
+ */
+export function mockLLMAdapter(config: MockLLMConfig = {}): MockLLMAdapter {
+    const invocations: MockLLMAdapterInvocation[] = [];
+    let responseQueue: Array<{
+        text?: string;
+        toolCalls?: Array<{ id: string; name: string; input: any }>;
+        stopReason?: "end_turn" | "tool_use" | "max_tokens";
+        streamChunks?: LLMStreamChunk[];
+    }> = [];
+    let currentResponseIndex = 0;
+
+    // Initialize response queue
+    if (config.response) {
+        responseQueue = [{ text: config.response, stopReason: "end_turn" }];
+    } else if (config.responses) {
+        responseQueue = config.responses;
+    }
+
+    const defaultUsage = config.usage || { inputTokens: 10, outputTokens: 20 };
+
+    const stream = async function* (params: {
+        instructions: string;
+        messages: LLMMessage[];
+        tools: any[];
+        maxTokens: number;
+        temperature: number;
+    }): AsyncGenerator<LLMStreamChunk> {
+        // Track invocation
+        invocations.push({
+            instructions: params.instructions,
+            messages: params.messages,
+            tools: params.tools,
+            maxTokens: params.maxTokens,
+            temperature: params.temperature,
+        });
+
+        // Simulate error if configured
+        if (config.error) {
+            throw config.error;
+        }
+
+        // Get next response from queue
+        const responseConfig = responseQueue[currentResponseIndex] || responseQueue[responseQueue.length - 1];
+        if (!responseConfig) {
+            throw new Error("No responses configured for mockLLMAdapter");
+        }
+
+        currentResponseIndex++;
+
+        // Use explicit stream chunks if provided
+        if (responseConfig.streamChunks) {
+            for (const chunk of responseConfig.streamChunks) {
+                yield chunk;
+            }
+            return;
+        }
+
+        // Use default stream chunks if provided
+        if (config.defaultStreamChunks) {
+            for (const chunk of config.defaultStreamChunks) {
+                yield chunk;
+            }
+            return;
+        }
+
+        // Otherwise, generate chunks from response
+        if (responseConfig.text) {
+            yield {
+                type: "text",
+                delta: responseConfig.text
+            };
+        }
+
+        for (const toolCall of responseConfig.toolCalls || []) {
+            yield { type: "tool_call", toolCall };
+        }
+
+        yield {
+            type: "usage",
+            usage: defaultUsage,
+        };
+
+        // Determine stop reason
+        let stopReason: "end_turn" | "tool_use" | "max_tokens" = "end_turn";
+        if (responseConfig.stopReason) {
+            stopReason = responseConfig.stopReason;
+        } else if (responseConfig.toolCalls && responseConfig.toolCalls.length > 0) {
+            stopReason = "tool_use";
+        }
+
+        yield {
+            type: "done",
+            stopReason,
+        };
+    };
+
+    const reset = (): void => {
+        invocations.length = 0;
+        currentResponseIndex = 0;
+    };
+
+    const getLastInvocation = (): MockLLMAdapterInvocation | undefined => {
+        return invocations[invocations.length - 1];
+    };
+
+    const getInvocationCount = (): number => {
+        return invocations.length;
+    };
+
+    return {
+        stream,
+        invocations,
+        reset,
+        getLastInvocation,
+        getInvocationCount,
+    };
+}
+
+/**
+ * Helper function to create streaming chunks for testing
+ *
+ * @example
+ * const chunks = createStreamingChunks({
+ *   text: "Hello world",
+ *   chunkText: true,
+ *   toolCalls: [{ id: "1", name: "search", input: { query: "test" } }]
+ * });
+ */
+export function createStreamingChunks(config: {
+    text?: string;
+    toolCalls?: Array<{ id: string; name: string; input: any }>;
+    chunkText?: boolean; // Split text into multiple deltas
+    usage?: { inputTokens: number; outputTokens: number };
+    stopReason?: "end_turn" | "tool_use" | "max_tokens";
+}): LLMStreamChunk[] {
+    const chunks: LLMStreamChunk[] = [];
+
+    if (config.text) {
+        if (config.chunkText) {
+            // Split into multiple text deltas (by words)
+            const words = config.text.split(' ');
+            for (const word of words) {
+                chunks.push({ type: "text", delta: word + ' ' });
+            }
+        } else {
+            chunks.push({ type: "text", delta: config.text });
+        }
+    }
+
+    for (const toolCall of config.toolCalls || []) {
+        chunks.push({ type: "tool_call", toolCall });
+    }
+
+    chunks.push({
+        type: "usage",
+        usage: config.usage || { inputTokens: 100, outputTokens: 50 },
+    });
+
+    chunks.push({
+        type: "done",
+        stopReason: config.stopReason || (config.toolCalls && config.toolCalls.length > 0 ? "tool_use" : "end_turn"),
+    });
+
+    return chunks;
+}