@lark-apaas/action-plugin-testing 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @lark-apaas/action-plugin-testing
+
+Testing utilities for `@lark-apaas/action-plugin-core` — provides mock context, test runner, stream helpers, and schema validation tools.
+
+## Install
+
+```bash
+npm install -D @lark-apaas/action-plugin-testing
+```
+
+## Quick Start
+
+```typescript
+import { createTestContext, createTestRunner } from '@lark-apaas/action-plugin-testing';
+import plugin from './my-plugin';
+
+const runner = createTestRunner(plugin);
+const context = createTestContext();
+
+// Run an action
+const result = await runner.run('sayHello', context, { name: 'World' });
+console.log(result); // { greeting: 'Hello, World!' }
+```
+
+## API
+
+### Test Context
+
+#### `createTestContext(options?)`
+
+Creates a mock `ActionContext` for testing.
+
+```typescript
+import { createTestContext } from '@lark-apaas/action-plugin-testing';
+
+// Default context
+const ctx = createTestContext();
+
+// Custom context
+const ctx = createTestContext({
+  userId: 'user-123',
+  tenantId: 'tenant-456',
+  appId: 'app-789',
+});
+```
+
+### Test Runner
+
+#### `createTestRunner(plugin, options?)`
+
+Wraps a plugin instance with convenience methods for testing.
+
+```typescript
+import { createTestRunner } from '@lark-apaas/action-plugin-testing';
+
+const runner = createTestRunner(plugin);
+
+// Unary action
+const result = await runner.run('actionName', context, input);
+
+// Stream action
+const stream = runner.runStream('actionName', context, input);
+
+// Schema access
+const inputSchema = runner.getInputSchema('actionName');
+const outputSchema = runner.getOutputSchema('actionName');
+```
+
+### Mock Logger
+
+#### `createMockLogger()`
+
+Creates a logger that records all log entries for assertions.
+
+```typescript
+import { createMockLogger } from '@lark-apaas/action-plugin-testing';
+
+const logger = createMockLogger();
+const ctx = createTestContext({ logger });
+
+await runner.run('action', ctx, input);
+
+// Query logs
+logger.getLogs();                    // all entries
+logger.getLogs('error');             // filter by level
+logger.hasLog('error');              // check existence
+logger.getLastLog('info');           // last entry of level
+```
+
+### Stream Helpers
+
+Utilities for testing async iterable streams.
+
+```typescript
+import {
+  collectStream,
+  collectStreamData,
+  collectStreamText,
+  firstChunk,
+  lastChunk,
+  countChunks,
+  assertStreamChunks,
+  assertEveryChunk,
+} from '@lark-apaas/action-plugin-testing';
+
+const stream = runner.runStream('chat', context, input);
+
+// Collect all chunks
+const chunks = await collectStream(stream);
+
+// Extract data fields from StreamChunk items
+const data = await collectStreamData(stream);
+
+// Concatenate text content
+const text = await collectStreamText(stream);
+
+// Access specific chunks
+const first = await firstChunk(stream);
+const last = await lastChunk(stream);
+
+// Count without storing
+const count = await countChunks(stream);
+
+// Assertions
+await assertStreamChunks(stream, [expected1, expected2]);
+await assertEveryChunk(stream, (chunk) => chunk.data.content.length > 0);
+```
+
+### StreamEvent Helpers
+
+Utilities for testing `StreamEvent` streams.
+
+```typescript
+import {
+  collectStreamEvents,
+  collectEventData,
+  waitForDone,
+  waitForError,
+  expectStreamCompletes,
+  expectStreamErrors,
+  expectAggregatedResult,
+} from '@lark-apaas/action-plugin-testing';
+
+// Collect and categorize events
+const { dataEvents, doneEvent, errorEvent } = await collectStreamEvents(stream);
+
+// Collect only data payloads
+const data = await collectEventData(stream);
+
+// Wait for completion / error
+const meta = await waitForDone(stream);
+const error = await waitForError(stream);
+
+// Assertions
+await expectStreamCompletes(stream);
+await expectStreamErrors(stream, 'ERROR_CODE');
+await expectAggregatedResult(stream, expectedResult);
+```
+
+### Schema Validation
+
+```typescript
+import { parseInput, expectInputRejected } from '@lark-apaas/action-plugin-testing';
+
+// Validate input against action schema
+const parsed = parseInput(runner, 'actionName', { name: 'test' });
+
+// Assert invalid input is rejected
+expectInputRejected(runner, 'actionName', { name: 123 });
+```
+
+## Types
+
+```typescript
+import type {
+  TestContextOptions,
+  TestRunner,
+  TestRunnerOptions,
+  MockLogger,
+  LogEntry,
+  StreamEventResult,
+} from '@lark-apaas/action-plugin-testing';
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,335 @@
+'use strict';
+
+// src/context.ts
+var silentLogger = {
+  log: () => {
+  },
+  error: () => {
+  },
+  warn: () => {
+  },
+  debug: () => {
+  }
+};
+var consoleLogger = {
+  log: (...args) => console.log("[TEST]", ...args),
+  error: (...args) => console.error("[TEST]", ...args),
+  warn: (...args) => console.warn("[TEST]", ...args),
+  debug: (...args) => console.debug("[TEST]", ...args)
+};
+function createMockResponse(data = {}) {
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+var mockHttpClient = {
+  get: async () => createMockResponse(),
+  post: async () => createMockResponse(),
+  put: async () => createMockResponse(),
+  delete: async () => createMockResponse(),
+  patch: async () => createMockResponse()
+};
+function resolveLogger(logger) {
+  if (!logger || logger === "silent") {
+    return silentLogger;
+  }
+  if (logger === "console") {
+    return consoleLogger;
+  }
+  return logger;
+}
+function createTestContext(options) {
+  const {
+    userId = "test-user",
+    tenantId = "test-tenant",
+    appId = "test-app",
+    logger,
+    platformHttpClient = mockHttpClient,
+    isDebug = false
+  } = options ?? {};
+  return {
+    userContext: {
+      userId,
+      tenantId,
+      appId
+    },
+    logger: resolveLogger(logger),
+    platformHttpClient,
+    isDebug
+  };
+}
+
+// src/runner.ts
+function createTestRunner(plugin, config, options) {
+  const instance = plugin.create(config);
+  const defaultContextOptions = options?.defaultContext ?? {};
+  return {
+    async run(actionName, input, contextOverrides) {
+      const mergedContextOptions = {
+        ...defaultContextOptions,
+        ...contextOverrides
+      };
+      const context = createTestContext(mergedContextOptions);
+      return instance.run(actionName, context, input);
+    },
+    getInstance() {
+      return instance;
+    },
+    getInputSchema(actionName) {
+      return instance.getInputSchema(actionName);
+    },
+    getOutputSchema(actionName, input) {
+      return instance.getOutputSchema(actionName, input);
+    }
+  };
+}
+
+// src/mocks/logger.ts
+function createMockLogger() {
+  const logs = [];
+  const createLogMethod = (level) => {
+    return (...args) => {
+      logs.push({
+        level,
+        args,
+        timestamp: Date.now()
+      });
+    };
+  };
+  return {
+    log: createLogMethod("log"),
+    error: createLogMethod("error"),
+    warn: createLogMethod("warn"),
+    debug: createLogMethod("debug"),
+    getLogs() {
+      return [...logs];
+    },
+    getLogsByLevel(level) {
+      return logs.filter((log) => log.level === level);
+    },
+    clear() {
+      logs.length = 0;
+    },
+    hasLog(level, messagePattern) {
+      return logs.some((log) => {
+        if (log.level !== level) return false;
+        return log.args.some((arg) => {
+          if (typeof arg !== "string") {
+            try {
+              arg = JSON.stringify(arg);
+            } catch {
+              return false;
+            }
+          }
+          if (typeof messagePattern === "string") {
+            return arg.includes(messagePattern);
+          }
+          return messagePattern.test(arg);
+        });
+      });
+    }
+  };
+}
+
+// src/stream.ts
+async function collectStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+  return chunks;
+}
+async function collectStreamData(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk.data);
+  }
+  return chunks;
+}
+async function collectStreamText(stream) {
+  let result = "";
+  for await (const chunk of stream) {
+    result += chunk.data.content;
+  }
+  return result;
+}
+async function firstChunk(stream) {
+  for await (const chunk of stream) {
+    return chunk;
+  }
+  return void 0;
+}
+async function lastChunk(stream) {
+  let last;
+  for await (const chunk of stream) {
+    last = chunk;
+  }
+  return last;
+}
+async function countChunks(stream) {
+  let count = 0;
+  for await (const _item of stream) {
+    count++;
+  }
+  return count;
+}
+async function assertStreamChunks(stream, expected) {
+  const actual = await collectStream(stream);
+  if (actual.length !== expected.length) {
+    throw new Error(`Expected ${expected.length} chunks, but got ${actual.length}`);
+  }
+  for (let i = 0; i < expected.length; i++) {
+    const actualStr = JSON.stringify(actual[i]);
+    const expectedStr = JSON.stringify(expected[i]);
+    if (actualStr !== expectedStr) {
+      throw new Error(`Chunk ${i} mismatch:
+Expected: ${expectedStr}
+Actual: ${actualStr}`);
+    }
+  }
+}
+async function assertEveryChunk(stream, predicate) {
+  let index = 0;
+  for await (const chunk of stream) {
+    if (!predicate(chunk, index)) {
+      throw new Error(`Chunk ${index} failed assertion: ${JSON.stringify(chunk)}`);
+    }
+    index++;
+  }
+}
+
+// src/stream-events.ts
+async function collectStreamEvents(stream) {
+  const events = [];
+  const data = [];
+  let done;
+  let error;
+  for await (const event of stream) {
+    events.push(event);
+    switch (event.type) {
+      case "data":
+        data.push(event.data);
+        break;
+      case "done":
+        done = event;
+        break;
+      case "error":
+        error = event;
+        break;
+    }
+  }
+  return {
+    events,
+    data,
+    done,
+    error,
+    completed: done !== void 0 && error === void 0
+  };
+}
+async function collectEventData(stream) {
+  const data = [];
+  for await (const event of stream) {
+    if (event.type === "data") {
+      data.push(event.data);
+    }
+  }
+  return data;
+}
+async function waitForDone(stream) {
+  for await (const event of stream) {
+    if (event.type === "done") {
+      return event.metadata;
+    }
+    if (event.type === "error") {
+      throw new Error(`Stream ended with error: [${event.error.code}] ${event.error.message}`);
+    }
+  }
+  throw new Error("Stream ended without done or error event");
+}
+async function waitForError(stream) {
+  for await (const event of stream) {
+    if (event.type === "error") {
+      return event.error;
+    }
+    if (event.type === "done") {
+      throw new Error("Expected stream to error, but it completed successfully");
+    }
+  }
+  throw new Error("Stream ended without done or error event");
+}
+async function expectStreamCompletes(stream) {
+  const result = await collectStreamEvents(stream);
+  if (!result.completed) {
+    if (result.error) {
+      throw new Error(
+        `Expected stream to complete, but got error: [${result.error.error.code}] ${result.error.error.message}`
+      );
+    }
+    throw new Error("Expected stream to complete, but no done event received");
+  }
+}
+async function expectStreamErrors(stream, expectedCode) {
+  const result = await collectStreamEvents(stream);
+  if (!result.error) {
+    throw new Error("Expected stream to error, but it completed successfully");
+  }
+  if (expectedCode && result.error.error.code !== expectedCode) {
+    throw new Error(`Expected error code "${expectedCode}", but got "${result.error.error.code}"`);
+  }
+}
+async function expectAggregatedResult(stream, expected) {
+  const metadata = await waitForDone(stream);
+  const actual = JSON.stringify(metadata.aggregated);
+  const expectedStr = JSON.stringify(expected);
+  if (actual !== expectedStr) {
+    throw new Error(`Aggregated result mismatch:
+Expected: ${expectedStr}
+Actual: ${actual}`);
+  }
+}
+
+// src/schema.ts
+function parseInput(instance, actionName, input) {
+  const schema = instance.getInputSchema(actionName);
+  if (!schema) {
+    throw new Error(`Action "${actionName}" not found`);
+  }
+  return schema.parse(input);
+}
+function expectInputRejected(instance, actionName, input) {
+  const schema = instance.getInputSchema(actionName);
+  if (!schema) {
+    throw new Error(`Action "${actionName}" not found`);
+  }
+  let threw = false;
+  try {
+    schema.parse(input);
+  } catch {
+    threw = true;
+  }
+  if (!threw) {
+    throw new Error(`Expected input to be rejected: ${JSON.stringify(input)}`);
+  }
+}
+
+exports.assertEveryChunk = assertEveryChunk;
+exports.assertStreamChunks = assertStreamChunks;
+exports.collectEventData = collectEventData;
+exports.collectStream = collectStream;
+exports.collectStreamData = collectStreamData;
+exports.collectStreamEvents = collectStreamEvents;
+exports.collectStreamText = collectStreamText;
+exports.countChunks = countChunks;
+exports.createMockLogger = createMockLogger;
+exports.createTestContext = createTestContext;
+exports.createTestRunner = createTestRunner;
+exports.expectAggregatedResult = expectAggregatedResult;
+exports.expectInputRejected = expectInputRejected;
+exports.expectStreamCompletes = expectStreamCompletes;
+exports.expectStreamErrors = expectStreamErrors;
+exports.firstChunk = firstChunk;
+exports.lastChunk = lastChunk;
+exports.parseInput = parseInput;
+exports.waitForDone = waitForDone;
+exports.waitForError = waitForError;