@movebridge/testing 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,451 @@
+import { MovementError, Resource, Transaction, TransactionResponse, ContractEvent, WalletState, TransactionPayload } from '@movebridge/core';
+import { Struct } from 'superstruct';
+
+/**
+ * @movebridge/testing - Type definitions
+ */
+
+/** Configuration for test harness */
+interface TestHarnessConfig {
+    /** Seed for deterministic random data generation */
+    seed?: number;
+    /** Network to simulate */
+    network?: 'mainnet' | 'testnet';
+    /** Default latency in milliseconds for mock responses */
+    defaultLatency?: number;
+}
+/** Test harness instance */
+interface TestHarness {
+    /** Mocked Movement client */
+    readonly client: MockMovementClient;
+    /** Call tracker for assertions */
+    readonly tracker: CallTracker;
+    /** Network simulator for latency/errors */
+    readonly simulator: NetworkSimulator;
+    /** Response faker for generating test data */
+    readonly faker: ResponseFaker;
+    /** Cleanup all state */
+    cleanup(): void;
+    /** Reset to initial state (keeps configuration) */
+    reset(): void;
+}
+/** Mock configuration for a method */
+interface MockConfig<T> {
+    response?: T;
+    error?: MovementError;
+    once?: boolean;
+}
+/** Mock Movement client interface */
+interface MockMovementClient {
+    mockResponse<T>(method: string, response: T): void;
+    mockError(method: string, error: MovementError): void;
+    mockResponseOnce<T>(method: string, response: T): void;
+    clearMocks(): void;
+    getAccountBalance(address: string): Promise<string>;
+    getAccountResources(address: string): Promise<Resource[]>;
+    getTransaction(hash: string): Promise<Transaction>;
+    waitForTransaction(hash: string): Promise<TransactionResponse>;
+}
+/** Result of address validation */
+interface AddressValidationResult {
+    valid: boolean;
+    normalized?: string;
+    error?: string;
+}
+/** Address validator interface */
+interface AddressValidator {
+    isValidAddress(address: string): boolean;
+    validateAddress(address: string): void;
+    normalizeAddress(address: string): string;
+    getValidationDetails(address: string): AddressValidationResult;
+}
+/** Transaction validator interface */
+interface TransactionValidator {
+    validateTransferPayload(payload: {
+        to: string;
+        amount: string;
+        coinType?: string;
+    }): boolean;
+    validateEntryFunctionPayload(payload: {
+        function: string;
+        typeArguments: string[];
+        arguments: unknown[];
+    }): boolean;
+    validatePayload(payload: TransactionPayload): boolean;
+}
+/** Validation error details */
+interface ValidationError {
+    path: string;
+    expected: string;
+    received: string;
+    message: string;
+}
+/** Schema names for validation */
+type SchemaName = 'Resource' | 'Transaction' | 'TransactionResponse' | 'WalletState' | 'ContractEvent' | string;
+/** Schema validator interface */
+interface SchemaValidator {
+    validateSchema(data: unknown, schemaName: SchemaName): boolean;
+    getValidationErrors(data: unknown, schemaName: SchemaName): ValidationError[];
+    registerSchema(name: string, schema: unknown): void;
+    hasSchema(name: string): boolean;
+}
+/** Options for creating a faker */
+interface FakerOptions {
+    seed?: number;
+}
+/** Options for generating fake balance */
+interface BalanceOptions {
+    min?: string;
+    max?: string;
+}
+/** Response faker interface */
+interface ResponseFaker {
+    fakeAddress(): string;
+    fakeBalance(options?: BalanceOptions): string;
+    fakeTransaction(): Transaction;
+    fakeTransactionResponse(success?: boolean): TransactionResponse;
+    fakeResource(type: string): Resource;
+    fakeEvent(type: string): ContractEvent;
+    fakeWalletState(connected?: boolean): WalletState;
+    fakeTransactionHash(): string;
+}
+/** Network simulator interface */
+interface NetworkSimulator {
+    simulateLatency(ms: number): void;
+    simulateTimeout(method: string): void;
+    simulateNetworkError(): void;
+    simulateRateLimit(maxCalls: number): void;
+    resetSimulation(): void;
+    getLatency(): number;
+    isNetworkErrorEnabled(): boolean;
+    isMethodTimedOut(method: string): boolean;
+    getRateLimitRemaining(): number | null;
+    incrementRateLimitCalls(): void;
+}
+/** Record of a method call */
+interface CallRecord {
+    method: string;
+    arguments: unknown[];
+    timestamp: number;
+    result: unknown | undefined;
+    error: Error | undefined;
+}
+/** Call tracker interface */
+interface CallTracker {
+    recordCall(method: string, args: unknown[], result?: unknown, error?: Error): void;
+    getCalls(method: string): CallRecord[];
+    getCallCount(method: string): number;
+    getAllCalls(): CallRecord[];
+    assertCalled(method: string): void;
+    assertCalledTimes(method: string, times: number): void;
+    assertCalledWith(method: string, ...args: unknown[]): void;
+    assertNotCalled(method: string): void;
+    clearCalls(): void;
+}
+/** Result of snapshot comparison */
+interface SnapshotResult {
+    match: boolean;
+    diff?: string;
+}
+/** Snapshot utilities interface */
+interface SnapshotUtils {
+    createSnapshot(data: unknown, name: string): void;
+    matchSnapshot(data: unknown, name: string): SnapshotResult;
+    updateSnapshot(data: unknown, name: string): void;
+    deleteSnapshot(name: string): void;
+    listSnapshots(): string[];
+}
+/** Test account for integration testing */
+interface TestAccount {
+    address: string;
+    privateKey: string;
+    publicKey: string;
+}
+/** Integration test utilities interface */
+interface IntegrationUtils {
+    createTestAccount(): Promise<TestAccount>;
+    waitForFunding(address: string, timeout?: number): Promise<string>;
+    cleanupTestAccount(account: TestAccount): Promise<void>;
+    withTestAccount<T>(callback: (account: TestAccount) => Promise<T>): Promise<T>;
+}
+
+/**
+ * @movebridge/testing - Test harness for MoveBridge SDK
+ */
+
+/**
+ * Creates a test harness for testing MoveBridge SDK integrations
+ * @param config - Optional configuration
+ * @returns TestHarness instance with mocked components
+ *
+ * @example
+ * ```typescript
+ * const harness = createTestHarness({ seed: 12345 });
+ *
+ * // Configure mock responses
+ * harness.client.mockResponse('getAccountBalance', '1000000000');
+ *
+ * // Use the mocked client
+ * const balance = await harness.client.getAccountBalance('0x1');
+ *
+ * // Assert on calls
+ * harness.tracker.assertCalled('getAccountBalance');
+ *
+ * // Cleanup
+ * harness.cleanup();
+ * ```
+ */
+declare function createTestHarness(config?: TestHarnessConfig): TestHarness;
+
+/**
+ * @movebridge/testing - Address validation utilities
+ */
+
+/**
+ * Checks if a string is a valid Movement/Aptos address
+ * @param address - The address to validate
+ * @returns true if valid, false otherwise
+ */
+declare function isValidAddress(address: string): boolean;
+/**
+ * Validates an address and throws if invalid
+ * @param address - The address to validate
+ * @throws MovementError with code 'INVALID_ADDRESS' if invalid
+ */
+declare function validateAddress(address: string): void;
+/**
+ * Normalizes an address to lowercase with '0x' prefix
+ * @param address - The address to normalize
+ * @returns Normalized address
+ * @throws MovementError if address is invalid
+ */
+declare function normalizeAddress(address: string): string;
+/**
+ * Gets detailed validation information for an address
+ * @param address - The address to validate
+ * @returns Validation result with details
+ */
+declare function getAddressValidationDetails(address: string): AddressValidationResult;
+
+/**
+ * @movebridge/testing - Transaction validation utilities
+ */
+
+/**
+ * Validates a transfer payload
+ * @param payload - Transfer payload to validate
+ * @returns true if valid
+ * @throws MovementError if invalid
+ */
+declare function validateTransferPayload(payload: {
+    to: string;
+    amount: string;
+    coinType?: string;
+}): boolean;
+/**
+ * Validates an entry function payload
+ * @param payload - Entry function payload to validate
+ * @returns true if valid
+ * @throws MovementError if invalid
+ */
+declare function validateEntryFunctionPayload(payload: {
+    function: string;
+    typeArguments: string[];
+    arguments: unknown[];
+}): boolean;
+/**
+ * Validates a transaction payload (polymorphic)
+ * @param payload - Transaction payload to validate
+ * @returns true if valid
+ * @throws MovementError if invalid
+ */
+declare function validatePayload(payload: TransactionPayload): boolean;
+
+/**
+ * @movebridge/testing - Schema validation utilities
+ */
+
+/**
+ * Predefined schemas for SDK types
+ */
+declare const PREDEFINED_SCHEMAS: {
+    readonly Resource: Struct<{
+        type: string;
+        data: Record<string, unknown>;
+    }, {
+        type: Struct<string, null>;
+        data: Struct<Record<string, unknown>, null>;
+    }>;
+    readonly Transaction: Struct<{
+        payload: {
+            function: string;
+            typeArguments: string[];
+            arguments: unknown[];
+            type: "entry_function_payload";
+        };
+        hash: string;
+        sender: string;
+        sequenceNumber: string;
+        timestamp: string;
+    }, {
+        hash: Struct<string, null>;
+        sender: Struct<string, null>;
+        sequenceNumber: Struct<string, null>;
+        payload: Struct<{
+            function: string;
+            typeArguments: string[];
+            arguments: unknown[];
+            type: "entry_function_payload";
+        }, {
+            type: Struct<"entry_function_payload", "entry_function_payload">;
+            function: Struct<string, null>;
+            typeArguments: Struct<string[], Struct<string, null>>;
+            arguments: Struct<unknown[], Struct<unknown, null>>;
+        }>;
+        timestamp: Struct<string, null>;
+    }>;
+    readonly TransactionResponse: Struct<{
+        hash: string;
+        success: boolean;
+        vmStatus: string;
+        gasUsed: string;
+        events: {
+            type: string;
+            data: Record<string, unknown>;
+            sequenceNumber: string;
+        }[];
+    }, {
+        hash: Struct<string, null>;
+        success: Struct<boolean, null>;
+        vmStatus: Struct<string, null>;
+        gasUsed: Struct<string, null>;
+        events: Struct<{
+            type: string;
+            data: Record<string, unknown>;
+            sequenceNumber: string;
+        }[], Struct<{
+            type: string;
+            data: Record<string, unknown>;
+            sequenceNumber: string;
+        }, {
+            type: Struct<string, null>;
+            sequenceNumber: Struct<string, null>;
+            data: Struct<Record<string, unknown>, null>;
+        }>>;
+    }>;
+    readonly WalletState: Struct<{
+        address: string | null;
+        connected: boolean;
+        publicKey: string | null;
+    }, {
+        connected: Struct<boolean, null>;
+        address: Struct<string | null, null>;
+        publicKey: Struct<string | null, null>;
+    }>;
+    readonly ContractEvent: Struct<{
+        type: string;
+        data: Record<string, unknown>;
+        sequenceNumber: string;
+    }, {
+        type: Struct<string, null>;
+        sequenceNumber: Struct<string, null>;
+        data: Struct<Record<string, unknown>, null>;
+    }>;
+};
+/**
+ * Validates data against a schema
+ * @param data - Data to validate
+ * @param schemaName - Name of the schema to validate against
+ * @returns true if valid, false otherwise
+ */
+declare function validateSchema(data: unknown, schemaName: SchemaName): boolean;
+/**
+ * Gets validation errors for data against a schema
+ * @param data - Data to validate
+ * @param schemaName - Name of the schema to validate against
+ * @returns Array of validation errors (empty if valid)
+ */
+declare function getValidationErrors(data: unknown, schemaName: SchemaName): ValidationError[];
+/**
+ * Registers a custom schema
+ * @param name - Name for the schema
+ * @param schema - Superstruct schema definition
+ */
+declare function registerSchema(name: string, schema: Struct<unknown>): void;
+/**
+ * Checks if a schema exists
+ * @param name - Schema name to check
+ * @returns true if schema exists
+ */
+declare function hasSchema(name: string): boolean;
+
+/**
+ * @movebridge/testing - Response faker for generating test data
+ */
+
+/**
+ * Creates a response faker with optional seeding
+ * @param options - Faker options including seed
+ * @returns ResponseFaker instance
+ */
+declare function createFaker(options?: FakerOptions): ResponseFaker;
+
+/**
+ * @movebridge/testing - Network simulator for testing latency, errors, and rate limits
+ */
+
+/**
+ * Creates a network simulator instance
+ * @returns NetworkSimulator instance
+ */
+declare function createNetworkSimulator(): NetworkSimulator;
+
+/**
+ * @movebridge/testing - Call tracker for recording and asserting method calls
+ */
+
+/**
+ * Creates a call tracker instance
+ * @returns CallTracker instance
+ */
+declare function createCallTracker(): CallTracker;
+
+/**
+ * @movebridge/testing - Snapshot testing utilities
+ */
+
+/**
+ * Creates snapshot utilities with in-memory storage
+ * For file-based snapshots, use with a test framework's snapshot feature
+ * @returns SnapshotUtils instance
+ */
+declare function createSnapshotUtils(): SnapshotUtils;
+
+/**
+ * @movebridge/testing - Integration test utilities
+ */
+
+/**
+ * Creates integration test utilities
+ * @param network - Network to use (only 'testnet' allowed)
+ * @returns IntegrationUtils instance
+ */
+declare function createIntegrationUtils(network: 'testnet'): IntegrationUtils;
+
+/**
+ * @movebridge/testing - Mock Movement client
+ */
+
+interface MockClientDependencies {
+    tracker: CallTracker;
+    simulator: NetworkSimulator;
+    faker: ResponseFaker;
+}
+/**
+ * Creates a mock Movement client
+ * @param deps - Dependencies (tracker, simulator, faker)
+ * @returns MockMovementClient instance
+ */
+declare function createMockClient(deps: MockClientDependencies): MockMovementClient;
+
+export { type AddressValidationResult, type AddressValidator, type BalanceOptions, type CallRecord, type CallTracker, type FakerOptions, type IntegrationUtils, type MockConfig, type MockMovementClient, type NetworkSimulator, PREDEFINED_SCHEMAS, type ResponseFaker, type SchemaName, type SchemaValidator, type SnapshotResult, type SnapshotUtils, type TestAccount, type TestHarness, type TestHarnessConfig, type TransactionValidator, type ValidationError, createCallTracker, createFaker, createIntegrationUtils, createMockClient, createNetworkSimulator, createSnapshotUtils, createTestHarness, getAddressValidationDetails, getValidationErrors, hasSchema, isValidAddress, normalizeAddress, registerSchema, validateAddress, validateEntryFunctionPayload, validatePayload, validateSchema, validateTransferPayload };