@albertodian/mimic-e2e 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Dian
+
+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/README.md

@@ -0,0 +1,63 @@
+# Mimic
+
+E2E tests written like user instructions.
+
+```ts
+export default [
+  'Search for {{city}} and finish when "Results for {{city}}" appears.',
+];
+```
+
+No user-written selectors or Playwright scripts. Mimic observes labelled browser controls, asks a local Laya browser model for the next action, and lets Playwright execute it.
+
+## Install
+
+Mimic uses Laya locally. On Apple Silicon, install its runtime once:
+
+```bash
+uv tool install 'laya-browser-agent[mlx] @ git+https://github.com/ChenneyZhuang/laya-browser-agent.git'
+```
+
+Install Mimic in the app you want to test, then install Chromium:
+
+```bash
+npm install -D /path/to/mimic-e2e-0.1.0.tgz
+npx playwright install chromium
+npx mimic init
+```
+
+`mimic init` detects a common Vite/Angular dev command, adds `mimic.e2e.ts`, and adds `npm run e2e` when that script is free. It never overwrites either file.
+
+Edit the generated file with the page text that proves the task completed:
+
+```ts
+import { defineSuite } from "@albertodian/mimic-e2e";
+
+export default defineSuite({
+  url: "http://localhost:5173",
+  devServer: { command: "npm run dev", url: "http://localhost:5173" },
+  variables: { city: "Verona" },
+  tests: [
+    'Search for {{city}} and finish when "Results for {{city}}" appears.',
+  ],
+});
+```
+
+Run it with:
+
+```bash
+npm run e2e
+```
+
+Use `E2E_URL=https://preview.example.com npm run e2e` to test an existing deployment without starting a local server. `npx mimic doctor` verifies the local Laya runtime and Chromium.
+
+## 0.1 boundary
+
+This first package supports labelled text fields, buttons, explicit variables, and `finish when "…" appears`. React/Angular fixtures, selects, retries, traces, and CI are not included yet.
+
+## Local packaging check
+
+```bash
+npm run build
+npm pack
+```

package/dist/agent.d.ts

@@ -0,0 +1,2 @@
+import type { AgentOptions, DecisionModel } from "./types.js";
+export declare function runAgent(model: DecisionModel, { page, goal, values, maxSteps }: AgentOptions): Promise<string[]>;

package/dist/agent.js

@@ -0,0 +1,21 @@
+import { execute } from "./executor.js";
+import { observe } from "./observer.js";
+export async function runAgent(model, { page, goal, values = [], maxSteps = 30 }) {
+    const steps = [];
+    let valueIndex = 0;
+    for (let step = 0; step < maxSteps; step++) {
+        const state = await observe(page);
+        const decision = await model.decide(goal, state);
+        if (decision.operation === "DONE")
+            return steps;
+        if (decision.operation === "FAIL")
+            throw new Error("Laya reported failure");
+        const element = state.candidates.find((candidate) => candidate.id === decision.element);
+        if (!element || !["CLICK", "TYPE_TEXT"].includes(decision.operation))
+            throw new Error("Laya chose an invalid action");
+        await execute(page, element, decision.operation, decision.operation === "TYPE_TEXT" ? values[valueIndex++] : undefined);
+        steps.push(`${decision.operation} ${JSON.stringify(element.name)}`);
+        await page.waitForTimeout(100);
+    }
+    throw new Error("Maximum steps exceeded");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { init } from "./init.js";
+import { doctor } from "./doctor.js";
+import { run } from "./run.js";
+const [command, ...flags] = process.argv.slice(2);
+const cwd = process.cwd();
+try {
+    if (command === "init")
+        await init(cwd);
+    else if (command === "doctor")
+        await doctor();
+    else if (command === "run")
+        await run({ cwd, headed: flags.includes("--headed") || flags.includes("--debug") });
+    else
+        throw new Error("Usage: mimic <init|run|doctor> [--headed|--debug]");
+}
+catch (error) {
+    console.error(`Mimic failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}

package/dist/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctor(): Promise<void>;

package/dist/doctor.js

@@ -0,0 +1,10 @@
+import { spawnSync } from "node:child_process";
+import { chromium } from "playwright";
+export async function doctor() {
+    const laya = spawnSync(process.env.LAYA_SERVER_COMMAND || "localdecide", ["--help"], { stdio: "ignore" });
+    if (laya.error)
+        throw new Error("Local Laya is missing. Install it with the command in Mimic's README.");
+    const browser = await chromium.launch();
+    await browser.close();
+    console.log("✓ Local Laya ready\n✓ Chromium ready");
+}

package/dist/executor.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright";
+import type { InteractiveElement, Operation } from "./types.js";
+export declare function execute(page: Page, element: InteractiveElement, operation: Operation, value?: string): Promise<void>;

package/dist/executor.js

@@ -0,0 +1,8 @@
+export async function execute(page, element, operation, value) {
+    const locator = page.locator("input, button").nth(element.id);
+    if (operation === "CLICK")
+        return locator.click();
+    if (operation === "TYPE_TEXT" && value)
+        return locator.fill(value);
+    throw new Error(`${operation} cannot run without a valid element and value`);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export interface MimicSuite {
+    url: string;
+    devServer?: {
+        command: string;
+        url?: string;
+    };
+    variables?: Record<string, string | undefined>;
+    tests: string[];
+}
+export declare function defineSuite(suite: MimicSuite): MimicSuite;

package/dist/index.js

@@ -0,0 +1,3 @@
+export function defineSuite(suite) {
+    return suite;
+}

package/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function init(cwd: string): Promise<void>;

package/dist/init.js

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+function defaults(scripts) {
+    const command = scripts.dev || scripts.start || "npm run dev";
+    const angular = /ng serve|angular/i.test(command);
+    return { command, url: angular ? "http://localhost:4200" : "http://localhost:5173" };
+}
+export async function init(cwd) {
+    const packagePath = resolve(cwd, "package.json");
+    if (!existsSync(packagePath))
+        throw new Error("package.json not found");
+    const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+    const scripts = packageJson.scripts || {};
+    const { command, url } = defaults(scripts);
+    const configPath = resolve(cwd, "mimic.e2e.ts");
+    if (!existsSync(configPath)) {
+        await writeFile(configPath, `import { defineSuite } from "@albertodian/mimic-e2e";\n\nexport default defineSuite({\n  url: "${url}",\n  devServer: { command: "${command}", url: "${url}" },\n  variables: {},\n  tests: [\n    'Finish when "Welcome" appears.',\n  ],\n});\n`);
+        console.log("✓ Created mimic.e2e.ts");
+    }
+    else
+        console.log("• mimic.e2e.ts already exists");
+    if (!scripts.e2e) {
+        scripts.e2e = "mimic run";
+        packageJson.scripts = scripts;
+        await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+        console.log("✓ Added npm script e2e");
+    }
+    else
+        console.log("• Existing e2e script left unchanged");
+    console.log(`✓ Dev command: ${command}\n✓ App URL: ${url}`);
+}

package/dist/model.d.ts

@@ -0,0 +1,8 @@
+import type { BrowserState, Decision, DecisionModel } from "./types.js";
+export declare class LayaBrowserDecider implements DecisionModel {
+    #private;
+    private constructor();
+    static start(): Promise<LayaBrowserDecider>;
+    decide(goal: string, state: BrowserState): Promise<Decision>;
+    close(): void;
+}

package/dist/model.js

@@ -0,0 +1,77 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+async function freePort() {
+    const server = createServer();
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Could not reserve a Laya port");
+    const { port } = address;
+    await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+    return port;
+}
+async function waitFor(url) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        try {
+            if ((await fetch(`${url}/healthz`)).ok)
+                return;
+        }
+        catch { }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error("Local Laya server did not start");
+}
+function completionText(goal) {
+    return goal.match(/finish when\s+"([^"]+)"\s+appears/i)?.[1];
+}
+export class LayaBrowserDecider {
+    #server;
+    #url;
+    constructor(server, url) {
+        this.#server = server;
+        this.#url = url;
+    }
+    static async start() {
+        const port = await freePort();
+        const server = spawn(process.env.LAYA_SERVER_COMMAND || "localdecide", ["serve", "--port", String(port)], { stdio: "ignore" });
+        const url = `http://127.0.0.1:${port}`;
+        await waitFor(url);
+        return new LayaBrowserDecider(server, url);
+    }
+    async decide(goal, state) {
+        const input = state.candidates.find((candidate) => candidate.role === "textbox" && !candidate.value);
+        const button = state.candidates.find((candidate) => candidate.role === "button");
+        const done = Boolean(completionText(goal) && state.visibleText.includes(completionText(goal)));
+        const operation = done ? "DONE" : input ? "TYPE_TEXT" : "CLICK";
+        const candidate = operation === "TYPE_TEXT" ? input : operation === "CLICK" ? button : undefined;
+        if (!candidate && operation !== "DONE")
+            throw new Error("No valid next action");
+        const answer = await this.#decide(goal, state, operation, candidate);
+        if (answer.operation !== operation || answer.element !== candidate?.id)
+            throw new Error("Laya chose an unavailable action");
+        return answer;
+    }
+    async #decide(goal, state, operation, candidate) {
+        const response = await fetch(`${this.#url}/v1/decide`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                state: { url: state.url, text: state.visibleText, history: [] },
+                questions: {
+                    operation: { type: "choice", criteria: {
+                            [operation]: operation === "TYPE_TEXT" ? "Enter text in the empty field required to advance the goal." : operation === "CLICK" ? "Click the ready button that advances the goal." : "Every requirement in the goal is visibly satisfied.",
+                            WAIT: "The needed control is absent, disabled, or loading.",
+                            BLOCKED: "No supported operation can make progress.",
+                        }, instructions: { goal, rules: "Advance the goal from the current page using one operation." } },
+                    ...(candidate ? { [`${operation.toLowerCase()}_target`]: { type: "choice", criteria: { [candidate.id]: `[${candidate.id}] ${candidate.name} (${candidate.role})${candidate.value ? ` = ${candidate.value}` : ""}` }, instructions: { goal, operation, rules: "Choose the observed element that performs this operation." } } } : {}),
+                },
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Local Laya rejected the decision: ${await response.text()}`);
+        const answer = await response.json();
+        const selected = answer.answers.operation.choice;
+        return { operation: selected, element: candidate ? Number(answer.answers[`${operation.toLowerCase()}_target`]?.choice) : undefined };
+    }
+    close() { this.#server.kill(); }
+}

package/dist/observer.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright";
+import type { BrowserState } from "./types.js";
+export declare function observe(page: Page): Promise<BrowserState>;

package/dist/observer.js

@@ -0,0 +1,13 @@
+export async function observe(page) {
+    const candidates = await page.locator("input, button").evaluateAll((elements) => elements.map((element, id) => {
+        const input = element;
+        return {
+            id,
+            role: element.tagName === "BUTTON" ? "button" : "textbox",
+            name: input.labels?.[0]?.textContent?.trim() || element.getAttribute("aria-label") || element.textContent?.trim() || "unnamed",
+            value: input.value || undefined,
+            visible: Boolean(element.offsetParent),
+        };
+    }));
+    return { url: page.url(), visibleText: await page.locator("body").innerText(), candidates };
+}

package/dist/run.d.ts

@@ -0,0 +1,5 @@
+export interface RunOptions {
+    cwd: string;
+    headed: boolean;
+}
+export declare function run({ cwd, headed }: RunOptions): Promise<void>;

package/dist/run.js

@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+import { chromium } from "playwright";
+import { runAgent } from "./agent.js";
+import { LayaBrowserDecider } from "./model.js";
+function suiteFrom(exported) {
+    if (Array.isArray(exported) && exported.every((goal) => typeof goal === "string"))
+        return { url: "http://localhost:3000", tests: exported };
+    if (typeof exported === "object" && exported && Array.isArray(exported.tests))
+        return exported;
+    throw new Error("mimic.e2e.ts must export an array of goals or defineSuite({...})");
+}
+async function waitFor(url) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        try {
+            if ((await fetch(url)).ok)
+                return;
+        }
+        catch { }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`App did not respond at ${url}`);
+}
+function start(command, cwd) {
+    return spawn(command, { cwd, shell: true, stdio: "inherit" });
+}
+function stop(process) {
+    process?.kill("SIGTERM");
+}
+function interpolate(goal, variables) {
+    return goal.replace(/{{(\w+)}}/g, (_, name) => {
+        const value = variables[name];
+        if (value === undefined)
+            throw new Error(`Missing variable: ${name}`);
+        return value;
+    });
+}
+export async function run({ cwd, headed }) {
+    const configPath = resolve(cwd, "mimic.e2e.ts");
+    if (!existsSync(configPath))
+        throw new Error("Missing mimic.e2e.ts. Run `mimic init` first.");
+    const suite = suiteFrom((await tsImport(pathToFileURL(configPath).href, import.meta.url)).default);
+    const url = process.env.E2E_URL || suite.devServer?.url || suite.url;
+    const server = process.env.E2E_URL ? undefined : suite.devServer ? start(suite.devServer.command, cwd) : undefined;
+    const variables = suite.variables || {};
+    const values = Object.values(variables).filter((value) => Boolean(value));
+    const browser = await chromium.launch({ headless: !headed });
+    const model = await LayaBrowserDecider.start();
+    let passed = 0;
+    try {
+        await waitFor(url);
+        console.log("Mimic\n");
+        for (const template of suite.tests) {
+            const goal = interpolate(template, variables);
+            const page = await browser.newPage();
+            console.log(`▶ ${goal}`);
+            try {
+                await page.goto(url);
+                const steps = await runAgent(model, { page, goal, values });
+                for (const step of steps)
+                    console.log(`  → ${step.startsWith("TYPE_TEXT") ? `filled ${step.slice("TYPE_TEXT ".length)}` : `clicked ${step.slice("CLICK ".length)}`}`);
+                console.log("✓ PASS\n");
+                passed++;
+            }
+            finally {
+                await page.close();
+            }
+        }
+        console.log(`${passed} passed`);
+    }
+    finally {
+        model.close();
+        await browser.close();
+        stop(server);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import type { Page } from "playwright";
+export type Operation = "CLICK" | "TYPE_TEXT" | "SELECT" | "WAIT" | "BACK" | "DONE" | "FAIL";
+export interface InteractiveElement {
+    id: number;
+    role: "textbox" | "button";
+    name: string;
+    value?: string;
+    visible: boolean;
+}
+export interface BrowserState {
+    url: string;
+    visibleText: string;
+    candidates: InteractiveElement[];
+}
+export interface Decision {
+    operation: Operation;
+    element?: number;
+}
+export interface DecisionModel {
+    decide(goal: string, state: BrowserState): Promise<Decision>;
+    close(): void;
+}
+export interface AgentOptions {
+    page: Page;
+    goal: string;
+    values?: string[];
+    maxSteps?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@albertodian/mimic-e2e",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "spike": "tsx spike/run.ts",
+    "mimic": "tsx src/cli.ts run"
+  },
+  "bin": {
+    "mimic": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/albertodian/mimic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/albertodian/mimic/issues"
+  },
+  "homepage": "https://github.com/albertodian/mimic#readme",
+  "keywords": [
+    "e2e",
+    "playwright",
+    "testing",
+    "local-ai"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "playwright": "^1.63.0",
+    "tsx": "^4.20.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  }
+}