@lunatest/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config/lua-config.d.ts

@@ -0,0 +1,4 @@
+import { type LuaConfig } from "../runtime/scenario-runtime.js";
+type LuaConfigSource = string | URL;
+export declare function loadLunaConfig(source: LuaConfigSource): Promise<LuaConfig>;
+export {};

package/dist/config/lua-config.js

@@ -0,0 +1,71 @@
+import { createRuntime } from "../runtime/engine.js";
+import { LuaConfigSchema } from "../runtime/scenario-runtime.js";
+import { isRecord } from "@lunatest/contracts";
+function seemsInlineLua(input) {
+    return input.includes("\n") || input.includes("scenario {") || input.includes("scenario{");
+}
+async function readSource(source) {
+    if (source instanceof URL) {
+        if (source.protocol === "http:" || source.protocol === "https:") {
+            if (typeof fetch !== "function") {
+                throw new Error(`Fetch API is unavailable for URL source: ${source.toString()}`);
+            }
+            const response = await fetch(source);
+            if (!response.ok) {
+                throw new Error(`Failed to load Lua config: ${source.toString()} (${response.status})`);
+            }
+            return response.text();
+        }
+        if (source.protocol !== "file:") {
+            throw new Error(`Unsupported Lua config URL protocol: ${source.protocol}`);
+        }
+        const [{ fileURLToPath }, { readFile }] = await Promise.all([
+            import("node:url"),
+            import("node:fs/promises"),
+        ]);
+        return readFile(fileURLToPath(source), "utf8");
+    }
+    if (seemsInlineLua(source)) {
+        return source;
+    }
+    if (typeof document !== "undefined" && typeof fetch === "function") {
+        const response = await fetch(source);
+        if (!response.ok) {
+            throw new Error(`Failed to load Lua config: ${source} (${response.status})`);
+        }
+        return response.text();
+    }
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return await readFile(source, "utf8");
+    }
+    catch {
+        return source;
+    }
+}
+export async function loadLunaConfig(source) {
+    const code = await readSource(source);
+    const runtime = await createRuntime();
+    let captured;
+    runtime.register("scenario", (table) => {
+        captured = table;
+        return table;
+    });
+    runtime.register("lunatest", (table) => {
+        captured = table;
+        return table;
+    });
+    await runtime.eval(code);
+    if (captured === undefined) {
+        const snapshot = await runtime.getState(["__lunatest_config"]);
+        captured = snapshot.__lunatest_config;
+    }
+    if (captured === undefined || captured === null) {
+        throw new Error("Lua config must declare scenario { ... } or lunatest({ ... })");
+    }
+    const parsed = LuaConfigSchema.parse(captured);
+    if (!isRecord(parsed.given)) {
+        throw new Error("Lua config given must be a table");
+    }
+    return parsed;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export declare const sdkName = "@lunatest/core";
+export { LunaProvider } from "./provider/luna-provider.js";
+export type { LunaProviderOptions } from "./provider/luna-provider.js";
+export { loadLunaConfig } from "./config/lua-config.js";
+export { applyInterceptState, createScenarioRuntime, LuaConfigSchema, setRouteMocks, type LuaConfig, type RouteMock, type ScenarioRuntime, } from "./runtime/scenario-runtime.js";
+export { executeLuaScenario, type ExecuteLuaScenarioInput, type ExecuteLuaScenarioResult, } from "./runner/execute-scenario.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export const sdkName = "@lunatest/core";
+export { LunaProvider } from "./provider/luna-provider.js";
+export { loadLunaConfig } from "./config/lua-config.js";
+export { applyInterceptState, createScenarioRuntime, LuaConfigSchema, setRouteMocks, } from "./runtime/scenario-runtime.js";
+export { executeLuaScenario, } from "./runner/execute-scenario.js";

package/dist/mocks/provider.d.ts

@@ -0,0 +1,56 @@
+type ProviderRequest = {
+    method: string;
+    params?: unknown[];
+};
+type TxStatus = "0x0" | "0x1";
+type MockEvent = {
+    atMs: number;
+    type: "tx_submitted" | "tx_confirmed" | "tx_failed";
+    txHash: string;
+    error?: string;
+};
+type MockProviderInput = {
+    chain?: {
+        id?: string;
+        blockNumber?: number;
+    };
+    wallet: {
+        address: string;
+        connected?: boolean;
+        chainId?: string;
+        balances: Record<string, string>;
+        allowances?: Record<string, string>;
+    };
+    events?: MockEvent[];
+};
+type MockProviderState = {
+    timeMs: number;
+    chain: {
+        id: string;
+        blockNumber: number;
+    };
+    wallet: {
+        address: string;
+        connected: boolean;
+        chainId: string;
+        balances: Record<string, string>;
+        allowances: Record<string, string>;
+    };
+    queue: MockEvent[];
+    receipts: Record<string, {
+        status: TxStatus;
+        transactionHash: string;
+    } | null>;
+};
+export type MockProvider = {
+    request: (payload: ProviderRequest) => Promise<unknown>;
+    given: MockProviderInput;
+    getState: () => MockProviderState;
+    advanceTime: (deltaMs: number) => void;
+    connect: (address?: string) => void;
+    disconnect: () => void;
+    approve: (token: string, amount: string) => void;
+    queueEvent: (event: MockEvent) => void;
+};
+export declare function createMockProvider(given: MockProviderInput): Promise<MockProvider>;
+export {};

package/dist/mocks/provider.js

@@ -0,0 +1,166 @@
+function parseTokenAmountToWeiHex(value) {
+    const [integerPartRaw, fractionalPartRaw = ""] = value.split(".");
+    const integerPart = integerPartRaw === "" ? "0" : integerPartRaw;
+    const fractionalPart = fractionalPartRaw.padEnd(18, "0").slice(0, 18);
+    const integerWei = BigInt(integerPart) * 10n ** 18n;
+    const fractionalWei = BigInt(fractionalPart || "0");
+    return `0x${(integerWei + fractionalWei).toString(16)}`;
+}
+function normalizeAddress(value) {
+    return value.toLowerCase();
+}
+function cloneState(state) {
+    return {
+        timeMs: state.timeMs,
+        chain: { ...state.chain },
+        wallet: {
+            ...state.wallet,
+            balances: { ...state.wallet.balances },
+            allowances: { ...state.wallet.allowances },
+        },
+        queue: state.queue.map((event) => ({ ...event })),
+        receipts: Object.fromEntries(Object.entries(state.receipts).map(([key, value]) => [
+            key,
+            value ? { ...value } : null,
+        ])),
+    };
+}
+function sortQueue(queue) {
+    queue.sort((left, right) => {
+        if (left.atMs === right.atMs) {
+            return left.type.localeCompare(right.type);
+        }
+        return left.atMs - right.atMs;
+    });
+}
+export async function createMockProvider(given) {
+    const state = {
+        timeMs: 0,
+        chain: {
+            id: given.chain?.id ?? given.wallet.chainId ?? "0x1",
+            blockNumber: given.chain?.blockNumber ?? 0,
+        },
+        wallet: {
+            address: given.wallet.address,
+            connected: given.wallet.connected ?? true,
+            chainId: given.wallet.chainId ?? given.chain?.id ?? "0x1",
+            balances: { ...given.wallet.balances },
+            allowances: { ...(given.wallet.allowances ?? {}) },
+        },
+        queue: [...(given.events ?? [])],
+        receipts: {},
+    };
+    sortQueue(state.queue);
+    let txCounter = 1n;
+    const applyEvent = (event) => {
+        if (event.type === "tx_submitted") {
+            state.receipts[event.txHash] = null;
+            return;
+        }
+        if (event.type === "tx_confirmed") {
+            state.receipts[event.txHash] = {
+                transactionHash: event.txHash,
+                status: "0x1",
+            };
+            return;
+        }
+        state.receipts[event.txHash] = {
+            transactionHash: event.txHash,
+            status: "0x0",
+        };
+    };
+    const consumeDueEvents = () => {
+        const remaining = [];
+        for (const event of state.queue) {
+            if (event.atMs <= state.timeMs) {
+                applyEvent(event);
+            }
+            else {
+                remaining.push(event);
+            }
+        }
+        state.queue = remaining;
+    };
+    const queueEvent = (event) => {
+        state.queue.push({ ...event });
+        sortQueue(state.queue);
+    };
+    return {
+        given,
+        getState() {
+            return cloneState(state);
+        },
+        advanceTime(deltaMs) {
+            state.timeMs += Math.max(0, Math.trunc(deltaMs));
+            consumeDueEvents();
+        },
+        connect(address) {
+            state.wallet.connected = true;
+            if (address) {
+                state.wallet.address = address;
+            }
+        },
+        disconnect() {
+            state.wallet.connected = false;
+        },
+        approve(token, amount) {
+            state.wallet.allowances[token] = amount;
+        },
+        queueEvent,
+        async request(payload) {
+            const method = payload.method;
+            if (method === "eth_chainId") {
+                return state.chain.id;
+            }
+            if (method === "eth_accounts") {
+                return state.wallet.connected ? [state.wallet.address] : [];
+            }
+            if (method === "eth_getBalance") {
+                const [requestedAddress] = payload.params ?? [];
+                const addressMatches = typeof requestedAddress === "string" &&
+                    normalizeAddress(requestedAddress) === normalizeAddress(state.wallet.address);
+                if (!addressMatches) {
+                    return "0x0";
+                }
+                const amount = state.wallet.balances.ETH ?? "0";
+                return parseTokenAmountToWeiHex(amount);
+            }
+            if (method === "eth_sendTransaction") {
+                const txHash = `0x${txCounter.toString(16).padStart(64, "0")}`;
+                txCounter += 1n;
+                queueEvent({
+                    atMs: state.timeMs,
+                    type: "tx_submitted",
+                    txHash,
+                });
+                queueEvent({
+                    atMs: state.timeMs + 3000,
+                    type: "tx_confirmed",
+                    txHash,
+                });
+                consumeDueEvents();
+                return txHash;
+            }
+            if (method === "eth_getTransactionReceipt") {
+                const [txHash] = payload.params ?? [];
+                if (typeof txHash !== "string") {
+                    return null;
+                }
+                return state.receipts[txHash] ?? null;
+            }
+            if (method === "wallet_switchEthereumChain") {
+                const [target] = payload.params ?? [];
+                const chainId = target && typeof target === "object"
+                    ? target.chainId
+                    : undefined;
+                if (typeof chainId !== "string") {
+                    throw new Error("wallet_switchEthereumChain requires chainId");
+                }
+                state.chain.id = chainId;
+                state.wallet.chainId = chainId;
+                return null;
+            }
+            throw new Error(`Unsupported method: ${method}`);
+        },
+    };
+}

package/dist/provider/luna-provider.d.ts

@@ -0,0 +1,27 @@
+export type Eip1193Request = {
+    method: string;
+    params?: unknown[];
+};
+export type LunaProviderOptions = {
+    chainId?: string;
+    accounts?: string[];
+    balances?: Record<string, string>;
+    callHandler?: (input: Record<string, unknown>) => Promise<string> | string;
+};
+type ProviderListener = (...args: unknown[]) => void;
+export declare class LunaProvider {
+    private chainId;
+    private accounts;
+    private balances;
+    private callHandler?;
+    private txCounter;
+    private subCounter;
+    private receipts;
+    private listeners;
+    constructor(options: LunaProviderOptions);
+    on(event: string, listener: ProviderListener): this;
+    removeListener(event: string, listener: ProviderListener): this;
+    private emit;
+    request(payload: Eip1193Request): Promise<unknown>;
+}
+export {};

package/dist/provider/luna-provider.js

@@ -0,0 +1,117 @@
+function normalizeAddress(value) {
+    return value.toLowerCase();
+}
+export class LunaProvider {
+    chainId;
+    accounts;
+    balances;
+    callHandler;
+    txCounter;
+    subCounter;
+    receipts;
+    listeners;
+    constructor(options) {
+        this.chainId = options.chainId ?? "0x1";
+        this.accounts = options.accounts ?? [];
+        this.balances = Object.fromEntries(Object.entries(options.balances ?? {}).map(([key, value]) => [
+            normalizeAddress(key),
+            value,
+        ]));
+        this.callHandler = options.callHandler;
+        this.txCounter = 1n;
+        this.subCounter = 1;
+        this.receipts = new Map();
+        this.listeners = new Map();
+    }
+    on(event, listener) {
+        const bucket = this.listeners.get(event) ?? new Set();
+        bucket.add(listener);
+        this.listeners.set(event, bucket);
+        return this;
+    }
+    removeListener(event, listener) {
+        const bucket = this.listeners.get(event);
+        if (!bucket) {
+            return this;
+        }
+        bucket.delete(listener);
+        if (bucket.size === 0) {
+            this.listeners.delete(event);
+        }
+        return this;
+    }
+    emit(event, ...args) {
+        const bucket = this.listeners.get(event);
+        if (!bucket) {
+            return;
+        }
+        for (const listener of bucket) {
+            listener(...args);
+        }
+    }
+    async request(payload) {
+        const method = payload.method;
+        if (method === "eth_chainId") {
+            return this.chainId;
+        }
+        if (method === "eth_accounts") {
+            return this.accounts;
+        }
+        if (method === "eth_getBalance") {
+            const [address] = payload.params ?? [];
+            if (typeof address !== "string") {
+                return "0x0";
+            }
+            return this.balances[normalizeAddress(address)] ?? "0x0";
+        }
+        if (method === "eth_call") {
+            const [callInput] = payload.params ?? [];
+            const normalized = callInput && typeof callInput === "object"
+                ? callInput
+                : {};
+            if (!this.callHandler) {
+                return "0x";
+            }
+            return this.callHandler(normalized);
+        }
+        if (method === "eth_sendTransaction") {
+            const txHash = `0x${this.txCounter.toString(16).padStart(64, "0")}`;
+            this.txCounter += 1n;
+            this.receipts.set(txHash, {
+                transactionHash: txHash,
+                status: "0x1",
+                blockNumber: "0x1",
+            });
+            this.emit("message", {
+                type: "tx_submitted",
+                data: { transactionHash: txHash },
+            });
+            return txHash;
+        }
+        if (method === "eth_getTransactionReceipt") {
+            const [txHash] = payload.params ?? [];
+            if (typeof txHash !== "string") {
+                return null;
+            }
+            return this.receipts.get(txHash) ?? null;
+        }
+        if (method === "wallet_switchEthereumChain") {
+            const [target] = payload.params ?? [];
+            const chainId = target && typeof target === "object"
+                ? target.chainId
+                : undefined;
+            if (typeof chainId !== "string") {
+                throw new Error("wallet_switchEthereumChain requires chainId");
+            }
+            this.chainId = chainId;
+            this.emit("chainChanged", chainId);
+            return null;
+        }
+        if (method === "eth_subscribe") {
+            const id = `0xsub${this.subCounter.toString(16).padStart(4, "0")}`;
+            this.subCounter += 1;
+            return id;
+        }
+        throw new Error(`Unsupported method: ${method}`);
+    }
+}

package/dist/runner/assert.d.ts

@@ -0,0 +1,11 @@
+export type AssertionResult = {
+    pass: boolean;
+    diff: string;
+    expected: unknown;
+    actual: unknown;
+};
+export declare function assertUI(expected: unknown, actual: unknown): AssertionResult;
+export declare function assertState(expected: unknown, actual: unknown): AssertionResult;
+export declare function assertTransition(expectedPath: string[], actualPath: string[]): AssertionResult;
+export declare function assertNot(forbiddenPaths: string[], actual: Record<string, unknown>): AssertionResult;
+export declare function assertTiming(targetMs: number, actualMs: number): AssertionResult;

package/dist/runner/assert.js

@@ -0,0 +1,58 @@
+function format(value) {
+    return JSON.stringify(value, null, 2);
+}
+function deepEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function buildResult(expected, actual) {
+    const pass = deepEqual(expected, actual);
+    return {
+        pass,
+        diff: pass ? "" : `expected ${format(expected)} but got ${format(actual)}`,
+        expected,
+        actual,
+    };
+}
+function hasPath(input, path) {
+    const parts = path.split(".").filter(Boolean);
+    let cursor = input;
+    for (const part of parts) {
+        if (!cursor || typeof cursor !== "object" || !(part in cursor)) {
+            return false;
+        }
+        cursor = cursor[part];
+    }
+    return true;
+}
+export function assertUI(expected, actual) {
+    return buildResult(expected, actual);
+}
+export function assertState(expected, actual) {
+    return buildResult(expected, actual);
+}
+export function assertTransition(expectedPath, actualPath) {
+    return buildResult(expectedPath, actualPath);
+}
+export function assertNot(forbiddenPaths, actual) {
+    const found = forbiddenPaths.filter((path) => hasPath(actual, path));
+    const pass = found.length === 0;
+    return {
+        pass,
+        diff: pass
+            ? ""
+            : `forbidden paths found: ${found.join(", ")} in ${format(actual)}`,
+        expected: forbiddenPaths,
+        actual,
+    };
+}
+export function assertTiming(targetMs, actualMs) {
+    const pass = actualMs <= targetMs;
+    return {
+        pass,
+        diff: pass
+            ? ""
+            : `expected timing <= ${targetMs}ms but got ${actualMs}ms`,
+        expected: targetMs,
+        actual: actualMs,
+    };
+}

package/dist/runner/execute-scenario.d.ts

@@ -0,0 +1,38 @@
+import type { RunScenarioResult } from "./runner.js";
+import { type LuaConfig, type ScenarioRuntime } from "../runtime/scenario-runtime.js";
+type LuaScenarioSource = string | URL | LuaConfig;
+type ExecuteAdapter = {
+    runWhen?: (context: {
+        config: LuaConfig;
+        runtime: ScenarioRuntime;
+    }) => Promise<void> | void;
+    resolveUi?: (context: {
+        config: LuaConfig;
+        runtime: ScenarioRuntime;
+    }) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    resolveState?: (context: {
+        config: LuaConfig;
+        runtime: ScenarioRuntime;
+    }) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    resolveTransitions?: (context: {
+        config: LuaConfig;
+        runtime: ScenarioRuntime;
+    }) => Promise<string[]> | string[];
+    resolveElapsedMs?: (context: {
+        config: LuaConfig;
+        runtime: ScenarioRuntime;
+    }) => Promise<number> | number;
+};
+export type ExecuteLuaScenarioInput = {
+    source: LuaScenarioSource;
+    adapter?: ExecuteAdapter;
+};
+export type ExecuteLuaScenarioResult = {
+    scenarioName: string;
+    pass: boolean;
+    error?: string;
+    result?: RunScenarioResult;
+    config: LuaConfig;
+};
+export declare function executeLuaScenario(input: ExecuteLuaScenarioInput): Promise<ExecuteLuaScenarioResult>;
+export {};

package/dist/runner/execute-scenario.js

@@ -0,0 +1,70 @@
+import { runScenario } from "./runner.js";
+import { loadLunaConfig } from "../config/lua-config.js";
+import { createScenarioRuntime, LuaConfigSchema, } from "../runtime/scenario-runtime.js";
+async function resolveConfig(source) {
+    if (typeof source === "string" || source instanceof URL) {
+        return loadLunaConfig(source);
+    }
+    return LuaConfigSchema.parse(source);
+}
+function normalizeScenario(config) {
+    const whenAction = config.when && typeof config.when.action === "string" ? config.when.action : "run";
+    return {
+        name: config.name ?? "unnamed",
+        given: config.given,
+        when: {
+            action: whenAction,
+            ...(config.when ?? {}),
+        },
+        then_ui: config.then_ui ?? {},
+        then_state: config.then_state,
+    };
+}
+export async function executeLuaScenario(input) {
+    const config = await resolveConfig(input.source);
+    const runtime = createScenarioRuntime(config);
+    const scenario = normalizeScenario(config);
+    if (!input.adapter?.resolveUi) {
+        return {
+            scenarioName: scenario.name,
+            pass: false,
+            error: "executor_not_configured",
+            config,
+        };
+    }
+    try {
+        if (input.adapter.runWhen) {
+            await input.adapter.runWhen({
+                config,
+                runtime,
+            });
+        }
+        const result = await runScenario({
+            scenario,
+            resolveUi: () => input.adapter.resolveUi({ config, runtime }),
+            resolveState: input.adapter.resolveState
+                ? () => input.adapter.resolveState({ config, runtime })
+                : undefined,
+            resolveTransitions: input.adapter.resolveTransitions
+                ? () => input.adapter.resolveTransitions({ config, runtime })
+                : undefined,
+            resolveElapsedMs: input.adapter.resolveElapsedMs
+                ? () => input.adapter.resolveElapsedMs({ config, runtime })
+                : undefined,
+        });
+        return {
+            scenarioName: scenario.name,
+            pass: result.pass,
+            result,
+            config,
+        };
+    }
+    catch (cause) {
+        return {
+            scenarioName: scenario.name,
+            pass: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+            config,
+        };
+    }
+}

package/dist/runner/performance.d.ts

@@ -0,0 +1,14 @@
+import { type RunScenarioInput } from "./runner.js";
+export type ScenarioPerformanceInput = {
+    iterations: number;
+    scenario: RunScenarioInput["scenario"];
+    resolveUi: RunScenarioInput["resolveUi"];
+};
+export type ScenarioPerformanceResult = {
+    iterations: number;
+    totalMs: number;
+    averageMs: number;
+    p95Ms: number;
+    samplesMs: number[];
+};
+export declare function measureScenarioPerformance(input: ScenarioPerformanceInput): Promise<ScenarioPerformanceResult>;