@lark-apaas/action-plugin-testing 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,338 @@
+import { Logger, PlatformHttpClient, PluginInstance, ActionContext, Plugin, StreamChunk, StreamEvent, StreamDoneEvent, StreamErrorEvent, StreamDoneMetadata, StreamErrorInfo } from '@lark-apaas/action-plugin-core';
+export { Logger } from '@lark-apaas/action-plugin-core';
+import { ZodSchema } from 'zod';
+
+/**
+ * 日志条目
+ */
+interface LogEntry {
+    level: 'log' | 'error' | 'warn' | 'debug';
+    args: unknown[];
+    timestamp: number;
+}
+/**
+ * Mock Logger 接口
+ */
+interface MockLogger extends Logger {
+    /** 获取所有日志记录 */
+    getLogs(): LogEntry[];
+    /** 获取指定级别的日志 */
+    getLogsByLevel(level: 'log' | 'error' | 'warn' | 'debug'): LogEntry[];
+    /** 清空日志记录 */
+    clear(): void;
+    /** 断言是否包含指定消息 */
+    hasLog(level: string, messagePattern: string | RegExp): boolean;
+}
+/**
+ * 测试上下文选项
+ */
+interface TestContextOptions {
+    userId?: string;
+    tenantId?: string;
+    appId?: string;
+    logger?: 'console' | 'silent' | Logger;
+    platformHttpClient?: PlatformHttpClient;
+    /** 是否处于调试模式，默认 false */
+    isDebug?: boolean;
+}
+/**
+ * TestRunner 选项
+ */
+interface TestRunnerOptions {
+    defaultContext?: Partial<TestContextOptions>;
+}
+/**
+ * 测试运行器接口
+ */
+interface TestRunner {
+    /**
+     * 执行 action
+     * @param actionName action 名称
+     * @param input 输入参数
+     * @param contextOverrides 覆盖默认 context 的字段
+     */
+    run<TInput, TOutput>(actionName: string, input: TInput, contextOverrides?: Partial<TestContextOptions>): Promise<TOutput>;
+    /**
+     * 获取底层插件实例
+     */
+    getInstance(): PluginInstance;
+    /**
+     * 获取 action 的 input schema
+     */
+    getInputSchema(actionName: string): ZodSchema | undefined;
+    /**
+     * 获取 action 的 output schema
+     */
+    getOutputSchema(actionName: string, input: unknown): ZodSchema | undefined;
+}
+
+/**
+ * 创建测试用的 ActionContext
+ *
+ * @param options 配置选项
+ * @returns ActionContext 实例
+ *
+ * @example
+ * ```typescript
+ * // 使用默认值
+ * const context = createTestContext();
+ *
+ * // 自定义部分字段
+ * const context = createTestContext({
+ *   userId: 'user-123',
+ *   logger: 'console',
+ * });
+ *
+ * // 使用自定义 logger
+ * const mockLogger = createMockLogger();
+ * const context = createTestContext({ logger: mockLogger });
+ * ```
+ */
+declare function createTestContext(options?: TestContextOptions): ActionContext;
+
+/**
+ * 创建测试运行器
+ *
+ * 封装插件实例，简化测试调用。
+ *
+ * @param plugin 插件定义
+ * @param config 插件配置（有配置插件必传）
+ * @param options 运行器选项
+ * @returns TestRunner 实例
+ *
+ * @example
+ * ```typescript
+ * // 无配置插件
+ * const runner = createTestRunner(plugin);
+ *
+ * // 有配置插件
+ * const runner = createTestRunner(plugin, {
+ *   apiKey: 'test-key',
+ *   endpoint: 'https://test.api.com',
+ * });
+ *
+ * // 自定义默认 context
+ * const runner = createTestRunner(plugin, config, {
+ *   defaultContext: {
+ *     userId: 'test-user-123',
+ *     logger: 'console',
+ *   },
+ * });
+ *
+ * // 执行测试
+ * const result = await runner.run('createUser', { name: 'John' });
+ * ```
+ */
+declare function createTestRunner<TConfig = undefined>(plugin: Plugin<TConfig>, config?: TConfig, options?: TestRunnerOptions): TestRunner;
+
+/**
+ * 创建 Mock Logger
+ * 可收集日志记录用于测试断言
+ */
+declare function createMockLogger(): MockLogger;
+
+/**
+ * Stream testing utilities
+ * 用于测试流式输出的辅助函数
+ */
+
+/**
+ * 收集流式输出的所有 chunk
+ *
+ * @example
+ * ```typescript
+ * const chunks = await collectStream(instance.runStream('action', ctx, input));
+ * expect(chunks).toHaveLength(3);
+ * ```
+ */
+declare function collectStream<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * 收集流式输出并提取 data 字段
+ *
+ * @example
+ * ```typescript
+ * const data = await collectStreamData(stream);
+ * // [{ content: 'a' }, { content: 'b' }] 而不是 [{ data: { content: 'a' } }, ...]
+ * ```
+ */
+declare function collectStreamData<T>(stream: AsyncIterable<StreamChunk<T>>): Promise<T[]>;
+/**
+ * 收集文本流式输出并拼接成完整字符串
+ *
+ * @example
+ * ```typescript
+ * const text = await collectStreamText(instance.runStream('chat', ctx, input));
+ * expect(text).toContain('Hello');
+ * ```
+ */
+declare function collectStreamText(stream: AsyncIterable<StreamChunk<{
+    content: string;
+}>>): Promise<string>;
+/**
+ * 获取流的第一个 chunk
+ */
+declare function firstChunk<T>(stream: AsyncIterable<T>): Promise<T | undefined>;
+/**
+ * 获取流的最后一个 chunk
+ */
+declare function lastChunk<T>(stream: AsyncIterable<T>): Promise<T | undefined>;
+/**
+ * 计算流的 chunk 数量（不保存数据）
+ */
+declare function countChunks<T>(stream: AsyncIterable<T>): Promise<number>;
+/**
+ * 验证流式输出的结构
+ *
+ * @example
+ * ```typescript
+ * await assertStreamChunks(stream, [
+ *   { data: { value: 1 } },
+ *   { data: { value: 2 } },
+ * ]);
+ * ```
+ */
+declare function assertStreamChunks<T>(stream: AsyncIterable<T>, expected: T[]): Promise<void>;
+/**
+ * 验证每个 chunk 都满足条件
+ *
+ * @example
+ * ```typescript
+ * await assertEveryChunk(stream, (chunk) => {
+ *   return chunk.data.value > 0;
+ * });
+ * ```
+ */
+declare function assertEveryChunk<T>(stream: AsyncIterable<T>, predicate: (chunk: T, index: number) => boolean): Promise<void>;
+
+/**
+ * StreamEvent testing utilities
+ * 用于测试 StreamEvent 事件流的辅助函数
+ */
+
+/**
+ * StreamEvent 收集结果
+ */
+interface StreamEventResult<T> {
+    /** 所有事件 */
+    events: StreamEvent<T>[];
+    /** 所有 data 事件的数据 */
+    data: T[];
+    /** done 事件（如果有） */
+    done?: StreamDoneEvent;
+    /** error 事件（如果有） */
+    error?: StreamErrorEvent;
+    /** 是否正常完成（有 done 事件且无 error 事件） */
+    completed: boolean;
+}
+/**
+ * 收集 StreamEvent 流的所有事件
+ *
+ * @example
+ * ```typescript
+ * const result = await collectStreamEvents(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ *
+ * expect(result.completed).toBe(true);
+ * expect(result.data).toHaveLength(3);
+ * expect(result.done?.metadata.chunks).toBe(3);
+ * ```
+ */
+declare function collectStreamEvents<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<StreamEventResult<T>>;
+/**
+ * 只收集 data 事件的数据
+ *
+ * @example
+ * ```typescript
+ * const data = await collectEventData(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ * // [{ content: 'Hello' }, { content: 'World' }]
+ * ```
+ */
+declare function collectEventData<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<T[]>;
+/**
+ * 等待流完成并返回 done 事件的 metadata
+ * 如果流以 error 结束，则抛出错误
+ *
+ * @example
+ * ```typescript
+ * const metadata = await waitForDone(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ * expect(metadata.chunks).toBe(5);
+ * expect(metadata.aggregated).toBeDefined();
+ * ```
+ */
+declare function waitForDone<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<StreamDoneMetadata>;
+/**
+ * 等待流出错并返回 error 信息
+ * 如果流正常完成，则抛出错误
+ *
+ * @example
+ * ```typescript
+ * const error = await waitForError(
+ *   instance.runStreamWithEvents('badAction', ctx, input)
+ * );
+ * expect(error.code).toBe('INVALID_INPUT');
+ * ```
+ */
+declare function waitForError<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<StreamErrorInfo>;
+/**
+ * 断言流正常完成
+ *
+ * @example
+ * ```typescript
+ * await expectStreamCompletes(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ * ```
+ */
+declare function expectStreamCompletes<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<void>;
+/**
+ * 断言流以错误结束
+ *
+ * @example
+ * ```typescript
+ * await expectStreamErrors(
+ *   instance.runStreamWithEvents('badAction', ctx, input),
+ *   'INVALID_INPUT'
+ * );
+ * ```
+ */
+declare function expectStreamErrors<T>(stream: AsyncIterable<StreamEvent<T>>, expectedCode?: string): Promise<void>;
+/**
+ * 断言聚合结果
+ *
+ * @example
+ * ```typescript
+ * await expectAggregatedResult(
+ *   instance.runStreamWithEvents('chat', ctx, input),
+ *   { data: { content: 'Hello World' } }
+ * );
+ * ```
+ */
+declare function expectAggregatedResult<T, R>(stream: AsyncIterable<StreamEvent<T>>, expected: R): Promise<void>;
+
+/**
+ * Schema testing utilities
+ * 用于测试 schema 验证的辅助函数
+ */
+/**
+ * 解析并验证 input
+ */
+declare function parseInput<T>(instance: {
+    getInputSchema: (name: string) => {
+        parse: (v: unknown) => T;
+    } | undefined;
+}, actionName: string, input: unknown): T;
+/**
+ * 验证 input 是否会被拒绝
+ */
+declare function expectInputRejected(instance: {
+    getInputSchema: (name: string) => {
+        parse: (v: unknown) => unknown;
+    } | undefined;
+}, actionName: string, input: unknown): void;
+
+export { type LogEntry, type MockLogger, type StreamEventResult, type TestContextOptions, type TestRunner, type TestRunnerOptions, assertEveryChunk, assertStreamChunks, collectEventData, collectStream, collectStreamData, collectStreamEvents, collectStreamText, countChunks, createMockLogger, createTestContext, createTestRunner, expectAggregatedResult, expectInputRejected, expectStreamCompletes, expectStreamErrors, firstChunk, lastChunk, parseInput, waitForDone, waitForError };

package/dist/index.d.ts

@@ -0,0 +1,338 @@
+import { Logger, PlatformHttpClient, PluginInstance, ActionContext, Plugin, StreamChunk, StreamEvent, StreamDoneEvent, StreamErrorEvent, StreamDoneMetadata, StreamErrorInfo } from '@lark-apaas/action-plugin-core';
+export { Logger } from '@lark-apaas/action-plugin-core';
+import { ZodSchema } from 'zod';
+
+/**
+ * 日志条目
+ */
+interface LogEntry {
+    level: 'log' | 'error' | 'warn' | 'debug';
+    args: unknown[];
+    timestamp: number;
+}
+/**
+ * Mock Logger 接口
+ */
+interface MockLogger extends Logger {
+    /** 获取所有日志记录 */
+    getLogs(): LogEntry[];
+    /** 获取指定级别的日志 */
+    getLogsByLevel(level: 'log' | 'error' | 'warn' | 'debug'): LogEntry[];
+    /** 清空日志记录 */
+    clear(): void;
+    /** 断言是否包含指定消息 */
+    hasLog(level: string, messagePattern: string | RegExp): boolean;
+}
+/**
+ * 测试上下文选项
+ */
+interface TestContextOptions {
+    userId?: string;
+    tenantId?: string;
+    appId?: string;
+    logger?: 'console' | 'silent' | Logger;
+    platformHttpClient?: PlatformHttpClient;
+    /** 是否处于调试模式，默认 false */
+    isDebug?: boolean;
+}
+/**
+ * TestRunner 选项
+ */
+interface TestRunnerOptions {
+    defaultContext?: Partial<TestContextOptions>;
+}
+/**
+ * 测试运行器接口
+ */
+interface TestRunner {
+    /**
+     * 执行 action
+     * @param actionName action 名称
+     * @param input 输入参数
+     * @param contextOverrides 覆盖默认 context 的字段
+     */
+    run<TInput, TOutput>(actionName: string, input: TInput, contextOverrides?: Partial<TestContextOptions>): Promise<TOutput>;
+    /**
+     * 获取底层插件实例
+     */
+    getInstance(): PluginInstance;
+    /**
+     * 获取 action 的 input schema
+     */
+    getInputSchema(actionName: string): ZodSchema | undefined;
+    /**
+     * 获取 action 的 output schema
+     */
+    getOutputSchema(actionName: string, input: unknown): ZodSchema | undefined;
+}
+
+/**
+ * 创建测试用的 ActionContext
+ *
+ * @param options 配置选项
+ * @returns ActionContext 实例
+ *
+ * @example
+ * ```typescript
+ * // 使用默认值
+ * const context = createTestContext();
+ *
+ * // 自定义部分字段
+ * const context = createTestContext({
+ *   userId: 'user-123',
+ *   logger: 'console',
+ * });
+ *
+ * // 使用自定义 logger
+ * const mockLogger = createMockLogger();
+ * const context = createTestContext({ logger: mockLogger });
+ * ```
+ */
+declare function createTestContext(options?: TestContextOptions): ActionContext;
+
+/**
+ * 创建测试运行器
+ *
+ * 封装插件实例，简化测试调用。
+ *
+ * @param plugin 插件定义
+ * @param config 插件配置（有配置插件必传）
+ * @param options 运行器选项
+ * @returns TestRunner 实例
+ *
+ * @example
+ * ```typescript
+ * // 无配置插件
+ * const runner = createTestRunner(plugin);
+ *
+ * // 有配置插件
+ * const runner = createTestRunner(plugin, {
+ *   apiKey: 'test-key',
+ *   endpoint: 'https://test.api.com',
+ * });
+ *
+ * // 自定义默认 context
+ * const runner = createTestRunner(plugin, config, {
+ *   defaultContext: {
+ *     userId: 'test-user-123',
+ *     logger: 'console',
+ *   },
+ * });
+ *
+ * // 执行测试
+ * const result = await runner.run('createUser', { name: 'John' });
+ * ```
+ */
+declare function createTestRunner<TConfig = undefined>(plugin: Plugin<TConfig>, config?: TConfig, options?: TestRunnerOptions): TestRunner;
+
+/**
+ * 创建 Mock Logger
+ * 可收集日志记录用于测试断言
+ */
+declare function createMockLogger(): MockLogger;
+
+/**
+ * Stream testing utilities
+ * 用于测试流式输出的辅助函数
+ */
+
+/**
+ * 收集流式输出的所有 chunk
+ *
+ * @example
+ * ```typescript
+ * const chunks = await collectStream(instance.runStream('action', ctx, input));
+ * expect(chunks).toHaveLength(3);
+ * ```
+ */
+declare function collectStream<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * 收集流式输出并提取 data 字段
+ *
+ * @example
+ * ```typescript
+ * const data = await collectStreamData(stream);
+ * // [{ content: 'a' }, { content: 'b' }] 而不是 [{ data: { content: 'a' } }, ...]
+ * ```
+ */
+declare function collectStreamData<T>(stream: AsyncIterable<StreamChunk<T>>): Promise<T[]>;
+/**
+ * 收集文本流式输出并拼接成完整字符串
+ *
+ * @example
+ * ```typescript
+ * const text = await collectStreamText(instance.runStream('chat', ctx, input));
+ * expect(text).toContain('Hello');
+ * ```
+ */
+declare function collectStreamText(stream: AsyncIterable<StreamChunk<{
+    content: string;
+}>>): Promise<string>;
+/**
+ * 获取流的第一个 chunk
+ */
+declare function firstChunk<T>(stream: AsyncIterable<T>): Promise<T | undefined>;
+/**
+ * 获取流的最后一个 chunk
+ */
+declare function lastChunk<T>(stream: AsyncIterable<T>): Promise<T | undefined>;
+/**
+ * 计算流的 chunk 数量（不保存数据）
+ */
+declare function countChunks<T>(stream: AsyncIterable<T>): Promise<number>;
+/**
+ * 验证流式输出的结构
+ *
+ * @example
+ * ```typescript
+ * await assertStreamChunks(stream, [
+ *   { data: { value: 1 } },
+ *   { data: { value: 2 } },
+ * ]);
+ * ```
+ */
+declare function assertStreamChunks<T>(stream: AsyncIterable<T>, expected: T[]): Promise<void>;
+/**
+ * 验证每个 chunk 都满足条件
+ *
+ * @example
+ * ```typescript
+ * await assertEveryChunk(stream, (chunk) => {
+ *   return chunk.data.value > 0;
+ * });
+ * ```
+ */
+declare function assertEveryChunk<T>(stream: AsyncIterable<T>, predicate: (chunk: T, index: number) => boolean): Promise<void>;
+
+/**
+ * StreamEvent testing utilities
+ * 用于测试 StreamEvent 事件流的辅助函数
+ */
+
+/**
+ * StreamEvent 收集结果
+ */
+interface StreamEventResult<T> {
+    /** 所有事件 */
+    events: StreamEvent<T>[];
+    /** 所有 data 事件的数据 */
+    data: T[];
+    /** done 事件（如果有） */
+    done?: StreamDoneEvent;
+    /** error 事件（如果有） */
+    error?: StreamErrorEvent;
+    /** 是否正常完成（有 done 事件且无 error 事件） */
+    completed: boolean;
+}
+/**
+ * 收集 StreamEvent 流的所有事件
+ *
+ * @example
+ * ```typescript
+ * const result = await collectStreamEvents(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ *
+ * expect(result.completed).toBe(true);
+ * expect(result.data).toHaveLength(3);
+ * expect(result.done?.metadata.chunks).toBe(3);
+ * ```
+ */
+declare function collectStreamEvents<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<StreamEventResult<T>>;
+/**
+ * 只收集 data 事件的数据
+ *
+ * @example
+ * ```typescript
+ * const data = await collectEventData(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ * // [{ content: 'Hello' }, { content: 'World' }]
+ * ```
+ */
+declare function collectEventData<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<T[]>;
+/**
+ * 等待流完成并返回 done 事件的 metadata
+ * 如果流以 error 结束，则抛出错误
+ *
+ * @example
+ * ```typescript
+ * const metadata = await waitForDone(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ * expect(metadata.chunks).toBe(5);
+ * expect(metadata.aggregated).toBeDefined();
+ * ```
+ */
+declare function waitForDone<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<StreamDoneMetadata>;
+/**
+ * 等待流出错并返回 error 信息
+ * 如果流正常完成，则抛出错误
+ *
+ * @example
+ * ```typescript
+ * const error = await waitForError(
+ *   instance.runStreamWithEvents('badAction', ctx, input)
+ * );
+ * expect(error.code).toBe('INVALID_INPUT');
+ * ```
+ */
+declare function waitForError<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<StreamErrorInfo>;
+/**
+ * 断言流正常完成
+ *
+ * @example
+ * ```typescript
+ * await expectStreamCompletes(
+ *   instance.runStreamWithEvents('chat', ctx, input)
+ * );
+ * ```
+ */
+declare function expectStreamCompletes<T>(stream: AsyncIterable<StreamEvent<T>>): Promise<void>;
+/**
+ * 断言流以错误结束
+ *
+ * @example
+ * ```typescript
+ * await expectStreamErrors(
+ *   instance.runStreamWithEvents('badAction', ctx, input),
+ *   'INVALID_INPUT'
+ * );
+ * ```
+ */
+declare function expectStreamErrors<T>(stream: AsyncIterable<StreamEvent<T>>, expectedCode?: string): Promise<void>;
+/**
+ * 断言聚合结果
+ *
+ * @example
+ * ```typescript
+ * await expectAggregatedResult(
+ *   instance.runStreamWithEvents('chat', ctx, input),
+ *   { data: { content: 'Hello World' } }
+ * );
+ * ```
+ */
+declare function expectAggregatedResult<T, R>(stream: AsyncIterable<StreamEvent<T>>, expected: R): Promise<void>;
+
+/**
+ * Schema testing utilities
+ * 用于测试 schema 验证的辅助函数
+ */
+/**
+ * 解析并验证 input
+ */
+declare function parseInput<T>(instance: {
+    getInputSchema: (name: string) => {
+        parse: (v: unknown) => T;
+    } | undefined;
+}, actionName: string, input: unknown): T;
+/**
+ * 验证 input 是否会被拒绝
+ */
+declare function expectInputRejected(instance: {
+    getInputSchema: (name: string) => {
+        parse: (v: unknown) => unknown;
+    } | undefined;
+}, actionName: string, input: unknown): void;
+
+export { type LogEntry, type MockLogger, type StreamEventResult, type TestContextOptions, type TestRunner, type TestRunnerOptions, assertEveryChunk, assertStreamChunks, collectEventData, collectStream, collectStreamData, collectStreamEvents, collectStreamText, countChunks, createMockLogger, createTestContext, createTestRunner, expectAggregatedResult, expectInputRejected, expectStreamCompletes, expectStreamErrors, firstChunk, lastChunk, parseInput, waitForDone, waitForError };