lecodes-cli 0.20.2 → 2.0.0

package/src/commands/test.ts

@@ -1,16 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { compileHeadlessBundle } from "../compile/headlessBundle"
-import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer } from "./appShared"
-import { fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice } from "./render"
+import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer } from "./app/shared"
+import { desktopRenderFlags, fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice, viewportFlags } from "./render"
 import { buildBundle } from "./compile"
-import { findProjectRoot } from "../manifest"
-import { runDesktopRender } from "../desktopRenderer"
-import { evaluateDesktopRun, translateScenario } from "../desktopScript"
-import { CliError, c, flagBool, flagStr, log, logErr, note, warnErr, type Args } from "../util"
+import { findProjectRoot } from "../project/manifest"
+import { runDesktopRender } from "../hosts/desktopRenderer"
+import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
+import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr, type FlagValues } from "../cli"
+import { bundleFlags, bundleOptions } from "./shared"
 
 /*
- * `lecodes test` — run the project's headless flow tests (needs the optional `lecodes-renderer`
+ * `lecodes test` — run the project's headless flow tests (needs the optional `lecodes-headless`
  * package). Two sources, both executed as scenario step lists against a fresh session each:
  *
  *   1. `tests/*.flow.json` — hand-written scenarios (same schema as `lecodes render --script`:
@@ -26,6 +27,11 @@ import { CliError, c, flagBool, flagStr, log, logErr, note, warnErr, type Args }
  *
  * A failing step stops its flow and dumps the failing frame (JSON + PNG when @napi-rs/canvas is
  * installed) under tests/.artifacts/<flow>/ so a red test explains itself without a rerun.
+ *
+ * `--desktop` runs the file scenarios through the NATIVE host (desktopScript.ts — targets by name or
+ * coordinates, expect.log + expect.paint checked, the semantic expects reported skipped). The
+ * design-derived flows need `expect.screen` and `fill`, which the host can't answer, so they stay
+ * headless-only. The viewport / timing and --desktop flags are `lecodes render`'s own groups.
  */
 
 type DesignEdge = { from: string, to: string, label?: string, activator?: string }
@@ -37,7 +43,7 @@ type FlowCase = {
   steps: unknown
   /** Canned fetch responses for this case's session. File scenarios: their envelope `fixtures`
    *  (inline or a path). Design flows: the project pack (tests/fixtures.json / --fixtures). */
-  fixtures?: import("lecodes-renderer/headless").Fixtures
+  fixtures?: import("lecodes-headless/headless").Fixtures
   /** Per-file envelope overrides (file scenarios only). */
   width?: number
   height?: number
@@ -131,19 +137,47 @@ const readFlowFile = (abs: string, displayName: string): FlowCase => {
   }
 }
 
-export const test = async (args: Args) => {
-  // --desktop: run every file scenario through the NATIVE host (desktopScript.ts — coordinates
-  // only, expect.log checked, semantic expects reported skipped). Design-derived flows tap by
-  // activator NAME, which the host can't resolve, so they stay headless-only.
-  const desktop = flagBool(args, "desktop")
-  if (desktop && flagBool(args, "flows")) throw new CliError("--flows needs the headless renderer (design flows tap by name) — drop --desktop.")
+const testFlags = {
+  flows: bool("run ONLY the design-derived flows"),
+  "no-flows": bool("run ONLY the tests/*.flow.json files"),
+  fixtures: str("fixture pack for the design flows (overrides the tests/fixtures.json default)", { value: "<file>" }),
+  json: bool("machine-readable report on stdout"),
+  dir: str("tests folder", { value: "<folder>", default: "tests" }),
+  "design-dir": str("design folder", { value: "<dir>", default: "design" }),
+  artifacts: str("failure-artifact folder override (default <tests>/.artifacts)", { value: "<dir>" }),
+  timeout: num("hard cap on the whole run (default 20000 + 10000 per case; --desktop 60000 + 60000 per case)", { value: "<ms>" }),
+  ...viewportFlags,
+  ...bundleFlags,
+  ...desktopRenderFlags,
+  desktop: bool("run the file scenarios through the NATIVE host: the same steps, targets and expects as headless (expect.audio and the json output excepted); design flows stay headless. --frames / --fixed-dt as in render --desktop"),
+}
+// (`sim` comes with desktopRenderFlags: the file scenarios through the WINDOWLESS host — no GPU, no
+// pixels, expect.log only; the same coordinate-only contract as --desktop minus screenshots.)
+
+type TestFlags = FlagValues<typeof testFlags>
+
+export default defineCommand({
+  name: "test",
+  summary: "Run the flow tests (tests/*.flow.json + design-derived flows)",
+  usage: "[name…]",
+  description: "Headless flow tests: tests/*.flow.json scenarios, plus flows derived from the design graph (design/meta.json activator edges — checks the built app against the designed navigation; needs named elements + screen roots). Failing steps dump the frame (JSON + PNG) under tests/.artifacts/<flow>/.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
+  flags: testFlags,
+  examples: ["lecodes test", "lecodes test hero --logs", "lecodes test --flows --json", "lecodes test --desktop"],
+  run: ({ args, flags }) => runTests(args, flags),
+})
+
+const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
+  // --sim is the native path on the windowless host: everything --desktop does, minus pixels.
+  const sim = flags.sim
+  const desktop = flags.desktop || sim
+  if (desktop && flags.flows) throw new CliError(`--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop --${sim ? "sim" : "desktop"}.`)
   // --desktop: ONE renderer decision (host binary + the staged .filamat variant). The root is
   // recomputed here because `root` below comes from the headless bundle, which --desktop skips.
   let desktopRoot: string
   try { desktopRoot = findProjectRoot(process.cwd()) } catch { desktopRoot = process.cwd() }
-  const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, args) : undefined
-  const native = desktop ? await buildBundle(args, undefined, { localAssets: true, desktopRenderer }) : null
-  const headless = desktop ? null : await compileHeadlessBundle(args)
+  const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, flags.renderer) : undefined
+  const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer }) : null
+  const headless = desktop ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
   const warnings = headless?.warnings ?? []
   const useLocalAssets = headless?.useLocalAssets ?? false
   const js = headless?.js ?? ""
@@ -151,22 +185,21 @@ export const test = async (args: Args) => {
   if (headless) root = headless.root
   else { try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() } }
   const renderer = desktop ? null : await requireRenderer()
-  const nativeFrames = Number(flagStr(args, "frames")) || 60
-  const fixedDtFlag = flagStr(args, "fixed-dt")
-  const nativeFixedDt = fixedDtFlag !== undefined ? Number(fixedDtFlag) : 16
-  if (!Number.isFinite(nativeFixedDt) || nativeFixedDt < 0 || nativeFixedDt > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${fixedDtFlag}".`)
+  const nativeFrames = flags.frames || 60
+  const nativeFixedDt = flags["fixed-dt"] ?? 16
+  if (nativeFixedDt < 0 || nativeFixedDt > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${nativeFixedDt}".`)
   // Desktop-only projects (app.json desktop block, no ios/android) run flows desktop-sized.
   const projectViewport = desktopDefaultViewport(root)
 
-  const testsDir = resolve(root, flagStr(args, "dir") ?? "tests")
-  const designMetaPath = resolve(root, flagStr(args, "design-dir") ?? "design", "meta.json")
-  const asJson = flagBool(args, "json")
+  const testsDir = resolve(root, flags.dir)
+  const designMetaPath = resolve(root, flags["design-dir"], "meta.json")
+  const asJson = flags.json
   const out = asJson ? logErr : log // --json owns stdout; the human report moves to stderr
 
   // 1. File scenarios: the given paths, or every tests/*.flow.json.
   const cases: FlowCase[] = []
-  if (args._.length > 0) {
-    for (const given of args._) {
+  if (args.length > 0) {
+    for (const given of args) {
       const candidates = [resolve(given), resolve(testsDir, given), resolve(testsDir, `${given}.flow.json`)]
       const abs = candidates.find((p) => existsSync(p))
       if (!abs) throw new CliError(`No such test: "${given}" (looked in ${testsDir}).`)
@@ -182,20 +215,19 @@ export const test = async (args: Args) => {
   // usually backend-gated). `tests/fixtures.json` is picked up automatically; --fixtures overrides
   // the path. File scenarios do NOT inherit it — they declare their own via the envelope, so a
   // deliberately-offline scenario (error states) stays offline.
-  const fixturesFlag = flagStr(args, "fixtures")
   const defaultPack = resolve(testsDir, "fixtures.json")
-  const flowFixtures = fixturesFlag !== undefined
-    ? resolveFixtures(fixturesFlag, ".")
+  const flowFixtures = flags.fixtures !== undefined
+    ? resolveFixtures(flags.fixtures, ".")
     : existsSync(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined
 
   // 2. Design-graph flows (opt out with --no-flows; --flows runs ONLY these).
-  const flowsOnly = flagBool(args, "flows")
-  const wantFlows = !flagBool(args, "no-flows") && args._.length === 0
+  const flowsOnly = flags.flows
+  const wantFlows = !flags["no-flows"] && args.length === 0
   if (flowsOnly) cases.length = 0
   let skipped: SkippedFlow[] = []
   let entryScreen: string | null = null
   if (desktop && wantFlows && existsSync(designMetaPath)) {
-    note("Design-derived flows skipped with --desktop (they tap by name; run `lecodes test` headless for them).")
+    note("Design-derived flows skipped with --desktop (they read expect.screen and fill inputs; run `lecodes test` headless for them).")
   }
   if (!desktop && (wantFlows || flowsOnly) && existsSync(designMetaPath)) {
     let meta: DesignMeta
@@ -211,7 +243,7 @@ export const test = async (args: Args) => {
       entryScreen = probe.screenName()
       probe.dispose()
       if (entryScreen === null) {
-        warnErr("Design flows skipped: the app's start screen root has no `name`. Name each screen root with its design screen id (e.g. UIScreen([...], { name: \"login\" })).")
+        warnErr("Design flows skipped: the app's start screen root has no `name`. Name each screen root with its design screen id (e.g. UIScreen(...).named(\"login\")).")
       } else {
         const derived = deriveDesignFlows(meta, entryScreen)
         cases.push(...derived.flows.map((f) => ({ ...f, fixtures: flowFixtures })))
@@ -229,17 +261,17 @@ export const test = async (args: Args) => {
 
   // Hard timeout across the whole run (each case is bounded by settles, but a pathological app can
   // still spin) — generous per-case allowance, overridable.
-  const timeoutMs = Number(flagStr(args, "timeout")) || (desktop ? 60000 + cases.length * 60000 : 20000 + cases.length * 10000)
+  const timeoutMs = flags.timeout || (desktop ? 60000 + cases.length * 60000 : 20000 + cases.length * 10000)
   const killer = setTimeout(() => {
     warnErr(`Test run timed out after ${timeoutMs}ms (raise --timeout or lower --settle).`)
     process.exit(1)
   }, timeoutMs)
   killer.unref?.()
 
-  const onConsole = flagBool(args, "logs")
+  const onConsole = flags.logs
     ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
     : undefined
-  const artifactsRoot = resolve(root, flagStr(args, "artifacts") ?? resolve(testsDir, ".artifacts"))
+  const artifactsRoot = resolve(root, flags.artifacts ?? resolve(testsDir, ".artifacts"))
 
   type CaseResult = {
     name: string
@@ -251,23 +283,38 @@ export const test = async (args: Args) => {
   }
   const results: CaseResult[] = []
 
+  const reportCase = (result: CaseResult): void => {
+    const skippedCount = result.steps.reduce((n, s) => n + (s.skipped?.length ?? 0), 0)
+    if (result.ok) {
+      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped on --desktop)`) : ""}`)
+    } else {
+      out(`${c.red("✗")} ${result.name}`)
+      if (result.error) out(`    ${c.red(result.error)}`)
+      for (const s of result.steps) {
+        out(s.ok ? c.dim(`    ✓ ${s.desc}`) : `    ${c.red(`✗ ${s.desc} — ${s.error}`)}`)
+        for (const sk of s.skipped ?? []) out(c.dim(`      – skipped: ${sk}`))
+      }
+      if (result.artifacts.length > 0) out(c.dim(`    failing frame: ${result.artifacts.join(", ")}`))
+    }
+  }
+
   // Native case runner: each case is its own host process (fresh state, like a fresh session);
   // per-step screenshots + the final frame land under the case's artifacts folder.
   const runNativeCase = async (kase: FlowCase): Promise<CaseResult> => {
     const caseDir = resolve(artifactsRoot, slug(kase.name))
-    const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: nativeFrames })
+    const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: nativeFrames, sim })
     for (const st of plan.steps) if (st.screenshot) mkdirSync(dirname(st.screenshot), { recursive: true })
     mkdirSync(caseDir, { recursive: true })
     const finalPng = resolve(caseDir, "final.png")
     const { output } = await runDesktopRender(native!.js, native!.resources, {
-      renderer: desktopRenderer,
+      renderer: desktopRenderer, host: sim ? "server" : "desktop",
       pluginDirs: desktopPluginLibraries(root).dirs,
-      width: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
-      height: Number(flagStr(args, "height")) || kase.height || projectViewport?.height || 844,
-      frames: plan.frameCap, outPng: finalPng, logs: flagBool(args, "logs"),
+      width: flags.width || kase.width || projectViewport?.width || 390,
+      height: flags.height || kase.height || projectViewport?.height || 844,
+      frames: plan.frameCap, outPng: finalPng, logs: flags.logs,
       timeoutMs: 60000 + plan.steps.length * 5000, script: plan.text, fixedDtMs: nativeFixedDt,
     })
-    const r = evaluateDesktopRun(plan, output)
+    const r = evaluateDesktopRun(plan, output, (path) => existsSync(path) ? readFileSync(path, "utf8") : null)
     if (!r.loaded) throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT). Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).")
     return {
       name: kase.name, kind: kase.kind, ok: r.ok,
@@ -278,7 +325,6 @@ export const test = async (args: Args) => {
   }
 
   for (const kase of cases) {
-    const flagSettle = flagStr(args, "settle")
     let result: CaseResult
     if (desktop) {
       try {
@@ -295,13 +341,13 @@ export const test = async (args: Args) => {
       const steps = renderer!.parseScenarioSteps(kase.steps)
       // Every case runs in a FRESH session — no state bleeds between flows.
       const session = await renderer!.createSession(js, {
-        width: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
-        height: Number(flagStr(args, "height")) || kase.height || projectViewport?.height || 844,
-        settleMs: flagSettle !== undefined ? Number(flagSettle) : kase.settle,
-        waitNetwork: flagBool(args, "wait-network"),
+        width: flags.width || kase.width || projectViewport?.width || 390,
+        height: flags.height || kase.height || projectViewport?.height || 844,
+        settleMs: flags.settle ?? kase.settle,
+        waitNetwork: flags["wait-network"],
         localAssets: useLocalAssets,
         fixtures: kase.fixtures,
-        ...resolveSafeAreaChoice(flagStr(args, "safe-area") ?? kase.safeArea, flagStr(args, "device") ?? kase.device),
+        ...resolveSafeAreaChoice(flags["safe-area"] ?? kase.safeArea, flags.device ?? kase.device),
         onConsole,
       })
       try {
@@ -323,21 +369,6 @@ export const test = async (args: Args) => {
     reportCase(result)
   }
 
-  function reportCase(result: CaseResult): void {
-    const skippedCount = result.steps.reduce((n, s) => n + (s.skipped?.length ?? 0), 0)
-    if (result.ok) {
-      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped on --desktop)`) : ""}`)
-    } else {
-      out(`${c.red("✗")} ${result.name}`)
-      if (result.error) out(`    ${c.red(result.error)}`)
-      for (const s of result.steps) {
-        out(s.ok ? c.dim(`    ✓ ${s.desc}`) : `    ${c.red(`✗ ${s.desc} — ${s.error}`)}`)
-        for (const sk of s.skipped ?? []) out(c.dim(`      – skipped: ${sk}`))
-      }
-      if (result.artifacts.length > 0) out(c.dim(`    failing frame: ${result.artifacts.join(", ")}`))
-    }
-  }
-
   for (const w of warnings) warnErr(w)
   const passed = results.filter((r) => r.ok).length
   const failed = results.length - passed