gz-laya-pilot

Node 22+ package based on LayaPilot. Functional TypeScript host API, ESM and declarations; Playwright execution stays in Node.

Autonomous exploration (0.1.2)

Version 0.1.1 introduced the full upstream generation and replay workflow, pinned at 9f1bb801e0ca5eb4ded82413ab112ab0da0716d8. Version 0.1.2 extends that workflow with semantic record trees, continuous microfrontend execution, query/detail assertions and related-record transactions. Version 0.1.0 only contains the recorded JSON adapter. Original and modified source hashes are in vendor/UPSTREAM.json; the complete diff is under vendor/patches/.

import { runAgent } from 'gz-laya-pilot';
const options = {
  url: 'http://localhost:3000/customers',
  python: '/absolute/path/to/python',
  model: '/absolute/path/to/laya-multilingual',
  channel: 'chrome', allowWrite: true,
};
await runAgent({ ...options, outputDir: './results/explore', onProgress: console.log });
await runAgent({ ...options, workbook: './results/explore/cases.xlsx', outputDir: './results/replay' });

runAgent starts an isolated worker calling the vendored runWorkflow. Upstream owns DOM observation, field/option decisions, CRUD and supplemental discovery, assertions, retries, pending-write journal, screenshots, Trace and Excel. The original 17-column workbook and hidden __laya_steps__ contract are preserved, including visible-column integrity checks. There is no second planner or custom workbook grammar. Both generation and replay use real Laya decisions; replay binds recorded targets to the new DOM and creates new test identifiers. A model refusal or assertion failure remains a failure.

createAgentBridge({targets: [{url, authState?, authCheck?}], python, model, outputDir, channel?, headed?}) returns {middleware, stop, isRunning}. Mount at <assistant bridgeUrl>/agent in a same-origin local Node server. It validates target permissions, serializes runs and serves upstream reports. The default is installed Chrome in headless mode. This is local middleware, not a production multi-user service. Saved login state must use the upstream auth-state format and a login-success selector. Browser cookies are not implicitly copied from the host page.

The CLI delegates to upstream and preserves its flags. Generate: gz-laya-pilot --mode generate --url <url> --case-file ./cases.xlsx --out ./results/generate --python <path> --model <path> --browser-channel chrome --headless --allow-write. Replay uses --mode execute with the same URL/case file and a new output directory. --help lists all upstream modes, including existing natural-language Excel via --excel.

Install Python dependencies from the vendored requirements-local.txt (or the repository's tested Windows lock), then download the pinned model. Python runs Laya and openpyxl; this is not a pure TypeScript model/Excel rewrite. Python, model weights and browser binaries are not bundled into npm. Windows IPC explicitly uses UTF-8. No model/API fallback is silently substituted.

See the integration and acceptance guide for pinned setup, support boundaries and real-model verification. Browser consumers use gz-laya-pilot/agent-schema without importing Node/Excel/Playwright.

Version 0.1.2 describes observed numeric input constraints in the model's candidates, resolving the Credit limit refusal seen in the independent English fixture with 0.1.1. Model refusal and confidence thresholds remain enforced; these results do not guarantee support for arbitrary backends.

Real-model acceptance on 2026-10-07 generated and replayed 12 cases on the securities fixture and 11 on an independent English tree/relationship fixture in fresh sessions. These cover supported CRUD, search, detail and related-record flows, not every feature on either page. A backend that ignores edits fails persistence verification and blocks later deletion. Windows checkpoint replacement retries transient locks; replaced inputs/actions are re-observed; Ant Design 6 selected values are retained. Test data and these acceptance reports are not bundled in the npm package.

Tree support requires unambiguous named ARIA trees/items and expansion state (maximum 24 expansions, path depth 8); it is not a whole-site crawler or a business-rule planner. New expand-tree steps extend the existing workbook contract: old upstream workbooks still load, but the unmodified upstream engine cannot replay the new step. React and SDK both use this same Node engine.

Recorded JSON replay

npm install gz-laya-pilot
npx playwright install chromium

import { runCase } from 'gz-laya-pilot';
const result = await runCase(
  {
    schema: 'zhidao-recorded-case',
    version: 1,
    name: 'Customer search',
    path: '/customers',
    steps: [
      {
        kind: 'assert',
        assertion: {
          name: 'Page ready',
          source: 'element-state',
          selector: '[data-testid="search"]',
          operator: 'visible',
          timeout: 5000,
        },
      },
    ],
  },
  {
    origin: 'http://127.0.0.1:3000',
    launch: { headless: true },
    onProgress: console.log,
    signal: new AbortController().signal,
  },
);

Use beforeRun(page, context) for your host's authentication or test setup; use context.storageState for an existing test login. Credentials never belong in case JSON. allowedOrigins explicitly permits API/asset origins when the test app needs them. By default only the supplied origin is allowed. Abort closes the browser. A run with no assertions reports completed, not passed.

Browser consumers import gz-laya-pilot/schema or gz-laya-pilot/browser; neither entry imports Node or Playwright. locate() uses unique CSS plus W3C accessible name/role. Version 1 CSS/text targets still work. Automatic retry never substitutes another business control.

createApiDecision({base, model, key}) returns a Laya-protocol decision function. chooseStep(instruction, observedCandidates, decide) selects a structured step or returns null for uncertainty. It does not execute the candidate or invent locators. The host must observe candidates and review the draft; runCase evaluates assertions against real DOM, not model opinions. Recorded JSON replay does not require Python; autonomous Excel generation/replay uses the vendored upstream engine described above. The older tools/laya-pilot snapshot is retained for compatibility, not used as the new agent engine.

See NOTICE.md and LICENSE for upstream provenance and the scope of the port.

0.1.2: continuous microfrontend exploration

Relation pickers support a related-records transaction: an empty collection on a newly created parent, an add/remove pair, and a dialog with selectable existing records and disabled confirmation until selection. The executor adds one uniquely identified sample, verifies the visible collection and fresh-session persistence, removes only that relation and independently verifies the empty collection again. HTML tables and ARIA grids (including split pinned rows) use the same observer; names and codes come from the page. Failed writes or persistence checks retain the test parent and stop later writes. This does not infer arbitrary nested business rules or grant access to existing parents.

Persistence checks reuse one headless Chrome process prepared before the visible test window. Each read still creates a new browser context using pre-write authentication only. This removes repeated background Chrome startup/shutdown during a visible run without weakening session isolation.

Visible execution waits for a non-loading, stable control layout for at least 650ms after key interactions. A fixed sleep alone did not prevent advancing during asynchronous panel replacement. Headless verification retains its normal speed. Default CRUD generation validates the empty form and creates the record in one editor visit; explicit validation-only runs still have their own case. Existing visible-page and persistence assertions remain required.

The same workflow now opens an owned tree record's inline detail, verifies identity outside the list, then explores its semantic tab group and re-observes after each transition. aria-controls must identify a visible panel; a selected tab label alone cannot pass. Bounded disclosure checks can inspect newly revealed controls and restore their state. Model refusals remain coverage gaps. Replay grounds dynamic record labels through the upstream matchReplayTarget helper without reducing confidence thresholds. Positive search must reduce the visible collection to the uniquely named test record; edit/delete do not redundantly re-filter it. The functional extension lives in lib/page-exploration.mjs, with no application routes or business labels.

The workbook's “探索范围” sheet and run-result metadata list observed but unverified entry states. Passing cases are not a whole-page coverage guarantee: file import/export, nested business transactions, permission scenarios and business-specific oracles still require supported recipes and test data. New detail/disclosure/query assertion steps require version 0.1.2 or later; earlier engines cannot replay these new workbooks.

The default allowWrite: false mode now also runs the existing model-selected filter discovery on semantic tables and record trees. It expands bounded tree paths, verifies an unmatched query and restores the list without refreshing. These recipes are saved under the existing filters operation; read-only validation permits only filter-empty / filter-reset, never form or CRUD actions. Startup checkpoints distinguish opening/authenticating the page from waiting for local model warmup. Run npm test -w gz-laya-pilot from the repository root for package and vendored-engine regression tests; real-model acceptance additionally requires the Python/model setup and a supported test target.

Generated workflows check the visible page after each CRUD write, then query the same module in a separate headless browser/context for persistence. They no longer reload the visible host to reset a child app. Discovery clears only its observed business filter and cancels its observed editor; failed restoration stops the workflow. Background checks use a pre-write authentication snapshot and produce their own screenshot/trace. New assert-persisted-row and assert-persisted-absent Excel steps require version 0.1.2 or later.

Hosts may expose data-laya-host on the viewport, and data-laya-app, data-laya-instance, and data-laya-active="true" on their application containers. Continuity checks bind the current app/instance and exact URL; fresh verification sessions bind the logical app and URL. An inactive child cache does not prevent testing the host view. Old workbooks containing reload must be regenerated for such hosts; they are rejected before any case runs. This is not yet a complete DOM/frame/portal access boundary. Persistence assertions retain their observed semantic query steps for replay. React and SDK bridges use the same workflow.