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

package/src/ai/mockTool.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { FlinkContext } from "@flink-app/flink";
+import type { FlinkTool, FlinkToolProps, ToolResult } from "@flink-app/flink/ai";
+
+export interface MockToolConfig<Input, Output> {
+  name: string;
+  description?: string;
+  inputSchema: z.ZodType<Input>;
+  outputSchema?: z.ZodType<Output>;
+
+  // Response strategies
+  response?: Output; // Canned success response
+  error?: { error: string; code?: string }; // Canned error response
+  fn?: FlinkTool<any, Input, Output>; // Custom function
+
+  // Permissions
+  permissions?: FlinkToolProps["permissions"];
+}
+
+export interface MockToolInvocation<Input> {
+  input: Input;
+  user?: any;
+}
+
+export interface MockToolResult<Input, Output> {
+  props: FlinkToolProps;
+  fn: FlinkTool<any, Input, Output>;
+
+  // Invocation tracking
+  invocations: MockToolInvocation<Input>[];
+  getLastInvocation(): MockToolInvocation<Input> | undefined;
+  reset(): void;
+}
+
+/**
+ * Creates a mock tool with tracking and canned responses
+ *
+ * Features:
+ * - Simple canned responses
+ * - Error simulation
+ * - Custom function support
+ * - Automatic invocation tracking
+ * - Validation helpers
+ *
+ * @example
+ * // Simple canned response
+ * const weatherTool = mockTool({
+ *   name: "get_weather",
+ *   inputSchema: z.object({ city: z.string() }),
+ *   response: { temperature: 22, conditions: "sunny" }
+ * });
+ *
+ * @example
+ * // Custom function with tracking
+ * const calculatorTool = mockTool({
+ *   name: "calculate",
+ *   inputSchema: z.object({ a: z.number(), b: z.number() }),
+ *   fn: async ({ input }) => ({
+ *     success: true,
+ *     data: { result: input.a + input.b }
+ *   })
+ * });
+ *
+ * @example
+ * // Error simulation
+ * const failingTool = mockTool({
+ *   name: "fail",
+ *   inputSchema: z.object({}),
+ *   error: { error: "Tool failed", code: "MOCK_ERROR" }
+ * });
+ */
+export function mockTool<Input = any, Output = any>(
+  config: MockToolConfig<Input, Output>
+): MockToolResult<Input, Output> {
+  const invocations: MockToolInvocation<Input>[] = [];
+
+  // Create the tool props
+  const props: FlinkToolProps = {
+    id: config.name,
+    description: config.description || `Mock tool: ${config.name}`,
+    inputSchema: config.inputSchema,
+    outputSchema: config.outputSchema,
+    permissions: config.permissions,
+  };
+
+  // Create the tool function with invocation tracking
+  const fn: FlinkTool<any, Input, Output> = async ({ input, ctx, user }) => {
+    // Track invocation
+    invocations.push({ input, user });
+
+    // If custom function provided, use it
+    if (config.fn) {
+      return config.fn({ input, ctx, user });
+    }
+
+    // If error configured, return error
+    if (config.error) {
+      return {
+        success: false,
+        error: config.error.error,
+        code: config.error.code,
+      };
+    }
+
+    // If response configured, return success with data
+    if (config.response !== undefined) {
+      return {
+        success: true,
+        data: config.response,
+      };
+    }
+
+    // Default: return empty success
+    return {
+      success: true,
+      data: {} as Output,
+    };
+  };
+
+  const getLastInvocation = (): MockToolInvocation<Input> | undefined => {
+    return invocations[invocations.length - 1];
+  };
+
+  const reset = (): void => {
+    invocations.length = 0;
+  };
+
+  return {
+    props,
+    fn,
+    invocations,
+    getLastInvocation,
+    reset,
+  };
+}

package/src/http.ts

@@ -1,4 +1,4 @@
-import { FlinkApp, FlinkResponse } from "@flink-app/flink";
+import { FlinkApp, FlinkContext, FlinkResponse } from "@flink-app/flink";
 import got, { GotJSONOptions } from "got";
 import qs from "qs";
 
@@ -34,8 +34,8 @@ export type HttpOpts = {
  * Initializes test flink app.
  * Must be invoked prior to using test HTTP methods.
  */
-export function init(_app: FlinkApp<any>, host = "localhost") {
-    app = _app;
+export function init<C extends FlinkContext<any>>(_app: FlinkApp<C>, host = "localhost") {
+    app = _app as unknown as FlinkApp<any>;
     baseUrl = `http://${host}:${app.port}`;
 }
 

package/src/index.ts

@@ -1,2 +1,4 @@
 export * from "./http";
 export * from "./mocks";
+export * from "./ai";
+export * from "./requestContext";

package/src/mocks.ts

@@ -1,4 +1,4 @@
-import { FlinkAuthPlugin, FlinkRequest } from "@flink-app/flink";
+import { FlinkAuthPlugin, FlinkContext, FlinkRequest } from "@flink-app/flink";
 
 interface TestFlinkRequest<T, P, Q> extends Omit<Partial<FlinkRequest<T, P, Q>>, "body" | "params" | "query"> {
     body?: T;
@@ -42,3 +42,23 @@ export function noOpAuthPlugin(): FlinkAuthPlugin {
         createToken: async () => "mock-token",
     };
 }
+
+/**
+ * Creates a mock FlinkContext with only the parts you need.
+ * Useful for testing services with mocked dependencies.
+ *
+ * @example
+ * ```typescript
+ * const carService = new CarService();
+ * carService.ctx = mockCtx<AppCtx>({
+ *     repos: { carRepo: mockCarRepo },
+ * });
+ * ```
+ */
+export function mockCtx<C extends FlinkContext>(partial: Partial<C> = {}): C {
+    return {
+        repos: {},
+        plugins: {},
+        ...partial,
+    } as C;
+}

package/src/requestContext.ts

@@ -0,0 +1,44 @@
+import { RequestContext, requestContext } from '@flink-app/flink';
+
+/**
+ * Create a mock request context for testing
+ */
+export function createMockRequestContext(overrides?: Partial<RequestContext>): RequestContext {
+    return {
+        reqId: "test-req-" + Math.random().toString(36).substring(7),
+        timestamp: Date.now(),
+        ...overrides,
+    };
+}
+
+/**
+ * Execute a function within a mocked request context
+ * Useful for testing tools and agents that use AsyncLocalStorage
+ *
+ * @example
+ * const result = await withRequestContext(
+ *     { user: { id: '123', username: 'test' }, reqId: 'req-123' },
+ *     async () => {
+ *         return await someTool.execute({ carId: 'car-1' });
+ *     }
+ * );
+ */
+export async function withRequestContext<T>(
+    context: Partial<RequestContext>,
+    fn: () => T | Promise<T>
+): Promise<T> {
+    const fullContext = createMockRequestContext(context);
+    return requestContext.run(fullContext, fn);
+}
+
+/**
+ * Create a test user with common properties
+ */
+export function createMockUser(overrides?: any) {
+    return {
+        id: "user-" + Math.random().toString(36).substring(7),
+        username: "testuser",
+        email: "test@example.com",
+        ...overrides,
+    };
+}

package/tsconfig.dist.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["spec/**/*.ts", "node_modules/*", "dist/*"]
+}

package/tsconfig.json

@@ -8,16 +8,17 @@
     "allowSyntheticDefaultImports": true,
     "strict": true,
     "forceConsistentCasingInFileNames": true,
-    "module": "commonjs",
-    "moduleResolution": "node",
+    "module": "node16",
+    "moduleResolution": "node16",
     "resolveJsonModule": true,
     "isolatedModules": true,
     "noEmit": false,
     "declaration": true,
     "experimentalDecorators": true,
     "checkJs": false,
-    "outDir": "dist"
+    "outDir": "dist",
+    "types": ["jasmine", "node"]
   },
-  "include": ["./src/**/*.ts", "./.flink/**/*.ts"],
-  "exclude": ["./node_modules/*"]
+  "include": ["./src/**/*.ts", "./.flink/**/*.ts", "./spec/**/*.ts"],
+  "exclude": ["./node_modules/*", "./dist/*"]
 }