@aigne/afs-testing 1.11.0-beta.7

package/dist/index.d.mts

@@ -0,0 +1,394 @@
+import * as bun_test0 from "bun:test";
+import { AFSEntry, AFSListResult, AFSModule, AFSReadResult, AFSSearchResult, AFSStatResult } from "@aigne/afs";
+
+//#region src/assertions.d.ts
+/**
+ * Validate that a result conforms to AFSListResult structure.
+ */
+declare function validateListResult(result: unknown): asserts result is AFSListResult;
+/**
+ * Validate that an object conforms to AFSEntry structure.
+ */
+declare function validateEntry(entry: unknown): asserts entry is AFSEntry;
+/**
+ * Validate that a result conforms to AFSReadResult structure.
+ */
+declare function validateReadResult(result: unknown): asserts result is AFSReadResult;
+/**
+ * Validate that a result conforms to AFSSearchResult structure.
+ */
+declare function validateSearchResult(result: unknown): asserts result is AFSSearchResult;
+/**
+ * Validate that a result conforms to AFSStatResult structure.
+ */
+declare function validateStatResult(result: unknown): asserts result is AFSStatResult;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Expected action declaration for a test node.
+ * Used to verify that actions are correctly exposed on nodes.
+ */
+interface TestActionDeclaration {
+  /** Action name */
+  name: string;
+  /** Optional description to verify */
+  description?: string;
+}
+/**
+ * A node in the test tree structure.
+ * - If `children` is defined and non-empty, it's a directory
+ * - If `content` is defined, it's a file
+ * - Root node has name "" (empty string)
+ */
+interface TestTreeNode {
+  /** Node name (not full path). Root node uses empty string. */
+  name: string;
+  /** For files: expected content (optional, for read verification) */
+  content?: string;
+  /** For directories: child nodes. Presence with length > 0 indicates directory. */
+  children?: TestTreeNode[];
+  /** Expected meta for this node */
+  meta?: Record<string, unknown>;
+  /**
+   * Expected actions for this node.
+   * If specified, the framework will verify these actions exist via list(.actions).
+   */
+  actions?: TestActionDeclaration[];
+}
+/**
+ * Describes the test data structure using a tree.
+ */
+interface TestDataStructure {
+  /**
+   * Root of the tree structure representing "/".
+   * All paths are derived from traversing this tree.
+   * The framework validates that provider data matches this tree.
+   */
+  root: TestTreeNode;
+}
+/**
+ * A flattened node with its computed path.
+ * Used internally for iterating over the tree.
+ */
+interface FlattenedNode {
+  /** Full path from root (e.g., "/docs/readme.md") */
+  path: string;
+  /** The tree node */
+  node: TestTreeNode;
+  /** Depth from root (root = 0) */
+  depth: number;
+}
+/**
+ * Check if a tree node represents a directory (has children).
+ */
+declare function isDirectory(node: TestTreeNode): boolean;
+/**
+ * Check if a tree node represents a file (has content or is a leaf without children).
+ */
+declare function isFile(node: TestTreeNode): boolean;
+/**
+ * Compute the full path for a node given its parent path.
+ */
+declare function computePath(parentPath: string, nodeName: string): string;
+/**
+ * Flatten a tree into an array of nodes with their paths.
+ * Traverses in BFS order.
+ */
+declare function flattenTree(root: TestTreeNode): FlattenedNode[];
+/**
+ * Find a node in the tree by path.
+ */
+declare function findNode(root: TestTreeNode, targetPath: string): TestTreeNode | undefined;
+/**
+ * Find the first file node in the tree (excluding root).
+ */
+declare function findFirstFile(root: TestTreeNode): FlattenedNode | undefined;
+/**
+ * Find the first directory node in the tree (excluding root).
+ */
+declare function findFirstDirectory(root: TestTreeNode): FlattenedNode | undefined;
+/**
+ * Find a nested directory (depth >= 2) in the tree.
+ */
+declare function findNestedDirectory(root: TestTreeNode): FlattenedNode | undefined;
+/**
+ * Get all file nodes from the tree.
+ */
+declare function getAllFiles(root: TestTreeNode): FlattenedNode[];
+/**
+ * Get all directory nodes from the tree.
+ */
+declare function getAllDirectories(root: TestTreeNode): FlattenedNode[];
+/**
+ * Configuration options for test behavior.
+ */
+interface TestConfig {
+  /** Custom timeout for slow providers (ms) */
+  timeout?: number;
+}
+/**
+ * Validator function for execute test output.
+ * Use expect() assertions inside to validate the output.
+ * @example
+ * ```typescript
+ * (output, expect) => {
+ *   expect(output.content).toBeDefined();
+ *   expect(output.content[0].text).toContain("hello");
+ * }
+ * ```
+ */
+type ExecuteOutputValidator = (output: Record<string, unknown>, expect: typeof bun_test0.expect) => void;
+/**
+ * Expected output specification for execute tests.
+ * Can be:
+ * - An exact object to match (deep equality)
+ * - A validator function that uses expect() assertions
+ * - An object with `contains` for partial matching
+ */
+type ExecuteExpectedOutput = Record<string, unknown> | ExecuteOutputValidator | {
+  contains: Record<string, unknown>;
+};
+/**
+ * A single execute test case.
+ */
+interface ExecuteTestCase {
+  /** Test case name/description */
+  name: string;
+  /** Path to execute (e.g., "/tools/echo") */
+  path: string;
+  /** Input arguments for execution */
+  args: Record<string, unknown>;
+  /**
+   * Expected output validation.
+   * - Object: exact deep equality match
+   * - Function: custom validator
+   * - { contains: ... }: partial match (output should contain these keys/values)
+   */
+  expected?: ExecuteExpectedOutput;
+  /**
+   * If true, the execution is expected to throw an error.
+   * Can also be a string/regex to match the error message.
+   */
+  shouldThrow?: boolean | string | RegExp;
+}
+/**
+ * Validator function for write test result.
+ * Uses a more flexible type to accommodate AFSWriteResult structure.
+ */
+type WriteOutputValidator = (result: {
+  data?: {
+    path: string;
+    content?: unknown;
+    meta?: Record<string, unknown> | null;
+  };
+}, expect: typeof bun_test0.expect) => void;
+/**
+ * Expected output specification for write tests.
+ */
+type WriteExpectedOutput = {
+  content: unknown;
+} | {
+  contentContains: string;
+} | {
+  meta: Record<string, unknown>;
+} | WriteOutputValidator;
+/**
+ * A single write test case.
+ * Tests write operations including content and meta writes.
+ */
+interface WriteTestCase {
+  /** Test case name/description */
+  name: string;
+  /**
+   * Path to write to.
+   * - Can be an existing path from structure (tests overwrite)
+   * - Can be a new path (tests creation)
+   * - Use payload.meta for meta-only writes (.meta paths are read-only)
+   */
+  path: string;
+  /**
+   * Payload to write.
+   * At least one of content or meta should be provided.
+   */
+  payload: {
+    content?: string | Record<string, unknown>;
+    meta?: Record<string, unknown>;
+  };
+  /**
+   * Expected output validation.
+   * - { content: ... }: verify written content matches
+   * - { contentContains: ... }: verify content contains string
+   * - { meta: ... }: verify meta matches
+   * - Function: custom validator with expect()
+   */
+  expected?: WriteExpectedOutput;
+  /**
+   * If true, the write is expected to throw an error.
+   * Can also be a string/regex to match the error message.
+   */
+  shouldThrow?: boolean | string | RegExp;
+}
+/**
+ * A single delete test case.
+ * Tests delete operations on paths from the structure.
+ */
+interface DeleteTestCase {
+  /** Test case name/description */
+  name: string;
+  /**
+   * Path to delete.
+   * Should typically be a path that exists in the structure.
+   */
+  path: string;
+  /**
+   * If true, the delete is expected to throw an error.
+   * Can also be a string/regex to match the error message.
+   */
+  shouldThrow?: boolean | string | RegExp;
+  /**
+   * If true, verify the path no longer exists after deletion.
+   * Uses list() or read() to confirm deletion.
+   * @default true
+   */
+  verifyDeleted?: boolean;
+}
+/**
+ * Validator function for action test output.
+ * Use expect() assertions inside to validate the output.
+ * @example
+ * ```typescript
+ * (result, expect) => {
+ *   expect(result.success).toBe(true);
+ *   expect(result.data?.newId).toBeDefined();
+ * }
+ * ```
+ */
+type ActionOutputValidator = (result: {
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: {
+    code: string;
+    message: string;
+  };
+}, expect: typeof bun_test0.expect) => void;
+/**
+ * Expected output specification for action tests.
+ * Can be:
+ * - An exact object to match (deep equality on data field)
+ * - A validator function that uses expect() assertions
+ * - An object with `contains` for partial matching
+ * - An object with `success` to just check success/failure
+ */
+type ActionExpectedOutput = {
+  success: boolean;
+} | {
+  data: Record<string, unknown>;
+} | {
+  contains: Record<string, unknown>;
+} | ActionOutputValidator;
+/**
+ * A single action test case.
+ * Tests input/output behavior of actions on nodes.
+ */
+interface ActionTestCase {
+  /** Test case name/description */
+  name: string;
+  /**
+   * Path to the action (e.g., "/users/.actions/insert" or "/.actions/create-table").
+   * This is the full action path including the .actions segment.
+   */
+  path: string;
+  /** Input arguments for the action */
+  args: Record<string, unknown>;
+  /**
+   * Expected output validation.
+   * - { success: true/false }: just check success status
+   * - { data: ... }: exact match on result.data
+   * - { contains: ... }: partial match on result.data
+   * - Function: custom validator
+   */
+  expected?: ActionExpectedOutput;
+  /**
+   * If true, the action execution is expected to throw an error.
+   * Can also be a string/regex to match the error message.
+   */
+  shouldThrow?: boolean | string | RegExp;
+}
+/**
+ * Fixture interface for provider conformance tests.
+ * Providers implement this to define their test environment.
+ */
+interface ProviderTestFixture<T extends AFSModule = AFSModule> {
+  /** Human-readable name for test output */
+  name: string;
+  /** Create a fresh provider instance */
+  createProvider: () => Promise<T> | T;
+  /** Describe the test data structure that will be available */
+  structure: TestDataStructure;
+  /**
+   * Execute test cases.
+   * Tests input/output behavior of executable nodes (e.g., tools, prompts).
+   */
+  executeCases?: ExecuteTestCase[];
+  /**
+   * Action test cases.
+   * Tests action execution on nodes (e.g., create-table, insert, delete).
+   * Actions are executed via exec() on .actions paths.
+   * These tests run LAST because they may modify the data structure.
+   */
+  actionCases?: ActionTestCase[];
+  /**
+   * Write test cases.
+   * Tests write operations including content and meta writes.
+   * These tests run LAST because they may modify the data structure.
+   */
+  writeCases?: WriteTestCase[];
+  /**
+   * Delete test cases.
+   * Tests delete operations on paths from the structure.
+   * These tests run LAST because they modify the data structure.
+   */
+  deleteCases?: DeleteTestCase[];
+  /** Optional lifecycle hooks */
+  beforeAll?: () => Promise<void> | void;
+  afterAll?: () => Promise<void> | void;
+  beforeEach?: () => Promise<void> | void;
+  afterEach?: () => Promise<void> | void;
+  /** Optional test configuration */
+  config?: TestConfig;
+}
+//#endregion
+//#region src/runner.d.ts
+/**
+ * Run provider conformance tests.
+ *
+ * @example
+ * ```typescript
+ * import { runProviderTests } from "@aigne/afs/testing";
+ *
+ * describe("MyProvider Conformance", () => {
+ *   runProviderTests({
+ *     name: "MyProvider",
+ *     createProvider: () => new MyProvider({ ... }),
+ *     structure: {
+ *       root: {
+ *         name: "",
+ *         children: [
+ *           { name: "file.txt", content: "Hello" },
+ *           {
+ *             name: "docs",
+ *             children: [
+ *               { name: "readme.md", content: "# Readme" },
+ *             ],
+ *           },
+ *         ],
+ *       },
+ *     },
+ *   });
+ * });
+ * ```
+ */
+declare function runProviderTests<T extends AFSModule>(fixture: ProviderTestFixture<T>): void;
+//#endregion
+export { type ActionExpectedOutput, type ActionOutputValidator, type ActionTestCase, type DeleteTestCase, type ExecuteExpectedOutput, type ExecuteOutputValidator, type ExecuteTestCase, type FlattenedNode, type ProviderTestFixture, type TestActionDeclaration, type TestConfig, type TestDataStructure, type TestTreeNode, type WriteExpectedOutput, type WriteOutputValidator, type WriteTestCase, computePath, findFirstDirectory, findFirstFile, findNestedDirectory, findNode, flattenTree, getAllDirectories, getAllFiles, isDirectory, isFile, runProviderTests, validateEntry, validateListResult, validateReadResult, validateSearchResult, validateStatResult };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/assertions.ts","../src/types.ts","../src/runner.ts"],"mappings":"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"}