2 Commits

Include renames

Author	SHA1	Message	Date
pj	20dab0ae2f	refactor(testrun): defer the java preflight check to the physical-device path	2026-06-06 23:45:13 +05:30
pj	b23fb0c723	feat: web-native specs + per-platform doctor (#49) ... * feat(doctor): per-platform check sets + --platform flag Replaces unconditional defaultDoctorChecks with doctorChecksFor(platform); web-only users no longer see scary FAILs for adb/emulator/java/sidecar. * feat(testrun): add Preflight() before sidecar/driver setup Mobile platforms get a friendly install hint pointing at `sanderling doctor --platform=<p>` instead of `fork/exec java: not found`. Web is a no-op. * refactor(chrome): split tag (HTML name) from class (CSS classList) Hierarchy attributes now expose HTML tag under 'tag' and CSS classes under 'class', stopping the conflation of the two. * feat(chrome): translate legacy string selectors to CSS/XPath TapSelector now maps id:/desc:/descPrefix:/testTag:/etc. through TranslateStringSelector. Unknown prefixes pass through to a CSS attribute selector so a future Maestro key works without a release. * feat(trace): add WriteHTML + Step.HTMLAvailable Per-step HTML lives in <run>/html/step-NNNNN.html so trace.jsonl stays line-greppable on apps with hundreds-of-KB DOMs. * feat(driver): add WebDriver capability + chrome implementation WebDriver exposes InstallBundle/EvaluateExtractors/NextActionFromV8/Document for the V8-native web tick path. Mobile drivers stay binary-compatible. * feat(verifier): OverrideExtractorValues for V8-driven extractors Web tick path runs extractor bodies in V8 against the real DOM, then overrides goja-side .current slots so LTL predicates evaluate against those values. Mobile callers can pass nil for a no-op. * feat(spec): add WebState + camelCase attribute aliases WebState extends State with live `document`/`window` for V8-side web extractors. KnownAttrSelectors gains camelCase aliases (contentDescription, ariaLabel, testID, etc.) so cross-framework specs autocomplete. * feat(runner): per-tick HTML capture for WebDriver-capable drivers Type-asserts driver.WebDriver and writes <run>/html/step-NNNNN.html in parallel with screenshot/hierarchy/metrics. Step.HTMLAvailable flips so the inspect UI can hide the html tab on mobile runs. * feat(inspect): serveHTML route under /api/runs/<id>/html/<name> Mirrors serveScreenshot path validation; rejects traversal segments and unknown extensions. text/html content-type so the iframe renders cleanly. * feat(bundler): BundleWeb + V8-side runtime shim web-runtime.ts installs globalThis.__sanderling__ with extractor / action registries, plus __sanderlingExtractors__ + __sanderlingNextAction__ globals. BundleWeb composes user spec + runtime under esbuild's PlatformBrowser into one IIFE. * feat(runner): V8 extractor overrides + V8 action source for WebDriver When the driver implements WebDriver, the runner sources extractor values from V8 (real DOM) and the next action from the V8-side action generator. LTL property predicates still run host-side in goja. * feat(testrun): bundle + install web runtime when platform=web BundleWeb composes the user spec with web-runtime.ts; the chrome driver installs the resulting IIFE via Page.AddScriptToEvaluateOnNewDocument post-Launch so the per-tick V8 extractor + action evaluation can begin on step 1. * feat(inspect-ui): hierarchy + html panels in run detail HierarchyPanel renders the captured DOM/AX tree with a filter input. HtmlPanel renders the per-step HTML in an iframe (sandboxed) with a toggle to view source. HTML tab only shows when the step actually has HTML captured. * fix(folio-web): drop aria-label data-carrier abuse Account cards now expose data-account-id + data-balance attrs and use a human-readable aria-label. total-balance / ledger / ledger-balance carry data-cents and data-txn-count instead of stuffing values into title. Spec rewritten to read structured attrs via object-form selectors. * chore: rebuild inspect-ui dist + folio-web .gitignore Embeds the new HierarchyPanel + HtmlPanel into the inspect-ui dist that ships with sanderling. Adds folio-web/.gitignore so generated runs/ don't leak into commits. * revert(trace): drop WriteHTML + Step.HTMLAvailable Screenshots already cover inspection; HTML capture bloats disk by 50-200MB per run with no payoff. * revert(runner): drop per-tick HTML capture Removes captureHTML helper and its three call sites; HTMLAvailable flag no longer set on Step. * revert(driver): drop WebDriver.Document Document was only consumed by the runner's HTML capture which is gone. * revert(inspect): drop /html route Removes htmlPathPattern, serveHTML, and the dispatch block that called it; HTML capture no longer exists on disk. * revert(inspect-ui): drop htmlUrl + html_available type API surface no longer needs the HTML route; Step.html_available has no producer. * revert(inspect-ui): drop HtmlPanel + html tab Removes the iframe-based HTML viewer and its before/after tab wiring from RunDetail. * test(inspect-ui): drop htmlUrl test, add @types/bun Pulls bun-types into tsconfig so api.test.ts (which uses bun:test) typechecks; this was broken from the original feature commit. * chore: rebuild inspect-ui dist without HtmlPanel Embedded SPA bundle no longer ships the iframe HTML viewer. * fix(web-runtime): retry action resolution + implement taps/swipes V8-side runtime previously returned null when weighted picked a generator that returned [] (page-gated), causing 80%+ of ticks on narrow routes to emit no action and no post-screenshot. Now retries up to 16x like goja, and the taps/swipes builtins query the live DOM for clickable elements / dispatch random swipes instead of returning null. * fix(web-runtime): drop swipe, restrict pressKey to browser-meaningful keys Web has no swipe gesture, so swipes dispatched pointer events into empty divs. Make swipe() and the swipes builtin no-op. For PressKey, replace the always-"back" choice with a random pick from {enter, tab, escape, up, down, left, right} - keys that have real semantics in a browser. * chore(folio-web): drop swipes from action root Web runtime no-ops Swipe; remove the import and weighted entry so the spec doesn't request actions that won't fire. * fix(inspect-ui): correct HierarchyPanel CSS variable names Tokens --surface-1/--surface-2/--text-secondary/--border-subtle don't exist in tokens.css, so sticky thead had no background and tag/bounds text fell back to inherited color. Map to the canonical --surface, --surface-elevated, --text-muted, --border that other panels use. * fix(chrome): correct PressKey mappings to chromedp/kb constants Old keyMap had "home":"\x00" (NUL byte) and arrow keys mapped to random punctuation runes (\x25-\x28 = % & ' () instead of arrow keys. "escape" was missing entirely while the V8 runtime emits it. Drop back/home (no browser navigation semantics) and route the remaining keys through chromedp/kb constants so they actually dispatch as the named keys. * fix(cli): -h/--help exits 0 instead of error code parseDoctorArgs hand-rolled its own flag loop and surfaced help text as an error; parseTestArgs used flag.ContinueOnError but propagated flag.ErrHelp to main() which printed "error: flag: help requested" and exited 1. Switch parseDoctorArgs to flag.NewFlagSet matching parseTestArgs, then recognise flag.ErrHelp in main() so all subcommands exit 0 on -h. * fix(chrome): harden cssEscape for control chars + use [class~=] Previous cssEscape only handled " and \, leaving NUL/newlines/control chars to break out of the CSS string literal. Port the CSSOM string serialization rules: NUL becomes U+FFFD, control chars become \HEX, quotes/backslashes get escaped. Class selector switched from `.x` (which would need separate identifier escaping) to `[class~="x"]`, which is also semantically correct for multi-class elements. * fix(web-runtime): use CSS.escape and validate tag-name selectors The previous cssEscape only handled " and \, leaving newlines/control chars to break out of attribute string literals. Delegate to the platform CSS.escape per CSSOM spec. The `tag` selector branch returned the bare value through cssEscape, which doesn't prevent pseudo-classes (`*:hover`) from injecting into the surrounding selector. Add a positive whitelist; values that don't match a tag-name pattern collapse to a never-matching `:not(*)`. Also switch class selectors to `[class~="..."]` to remove the only identifier-context use of cssEscape. * fix(chrome): validate attribute name in unknown-prefix branch A selector like `foo]:has(*),body[x:value` previously produced [foo]:has(*),body[x="..."], a syntactically valid CSS selector that escaped the attribute match and selected `body`. Reject anything that isn't a plain HTML attribute name. * fix(selectors): emit valid XPath 1.0 string literals via concat() Both the Go translator and the V8 runtime escaped " by prepending \, which XPath 1.0 doesn't accept (its string literals have no escape syntax). A `text:` value containing a quote produced malformed XPath that chromedp/document.evaluate rejected. Use the standard concat() composition: when the value contains both ' and ", split on " and join with `, '"', ` so each fragment is wrapped in single or double quotes individually. * fix(runtime): surface unresolved action targets instead of dropping silently serializeAction emitted {x:0,y:0} via `?? 0` whenever a Tap/InputText/Swipe target failed to resolve to coordinates. The runner then collapsed those to ErrNoAction, so every selector typo became a silent no-op tick. Have the runtime return null on unresolved targets and log a console warning (visible via chromedp's runtime listener). Drop the now-redundant {0,0} -> ErrNoAction guard so a deliberate Tap at the origin actually fires. * fix(runner): use errgroup-bound ctx so siblings cancel on failure The errgroup's bound ctx was discarded; goroutines closed over the outer ctx, so neither a sibling failure nor the future ability to propagate per-step cancellation reached the V8 extractor's CDP round-trip. Switch closures to gctx and document why Wait()'s error is intentionally discarded. * fix(chrome): propagate caller ctx cancellation to CDP calls InstallBundle, EvaluateExtractors, NextActionFromV8 ignored the caller ctx and ran chromedp.Run on d.tabCtx alone, so step deadlines and Ctrl-C couldn't interrupt an in-flight CDP round-trip on a hung tab. Add a runCtx helper that derives a chromedp-bound context which also cancels when the caller's ctx cancels, and route the three V8 entry points through it. * fix(verifier): tolerate out-of-range override indices A single stale index from V8 aborted the entire override map, so any valid entries alongside it were dropped and verification ran on stale extractor values. V8 and goja register from the same bundle so a mismatch is unusual but recoverable. Skip out-of-range entries instead of erroring, and return the skipped count so the runner logs the mismatch without losing valid overrides. * test(verifier): cover object-shaped extractor overrides Existing tests only override scalars (777, 200), so a future jsonToJSValue regression around nested object propagation would slip through. Lock down the contract: a JSON object override should make {attrs.testTag, balance} readable from goja predicates. * fix(web-runtime): lock global runtime hooks against page shadowing AddScriptToEvaluateOnNewDocument runs first, but a page script can still delete or replace window.__sanderling{,Extractors__,NextAction__} between install and host invocation. Define them as non-writable, non-configurable properties so any attempt to shadow them throws in strict mode rather than silently breaking the run. * perf(web-runtime): cache randomTap candidate DOM scan per tick The 16-attempt retry loop in __sanderlingNextAction__ called randomTap repeatedly; each call ran querySelectorAll over a-button- input-... and re-flushed layout per match via getBoundingClientRect. On heavy SPA routes that's the per-tick budget gone. Cache the scan in a module-level slot, reset at the top of each __sanderlingNextAction__ invocation so the cache doesn't outlive a tick. * fix(web-runtime): cap sanitize recursion to prevent stack overflow State exposes document and window (per WebState in types.ts). A user extractor returning either crashes the runtime via stack overflow on the circular DOM/Window references. Track seen objects in a WeakSet and bail at depth 32 so the worst case becomes a truncated value, not a process kill. * fix(web-runtime): enforce pressKey allowlist in factory The factory accepted any string while randomPressKey only emitted enter/tab/escape/arrows. A spec emitting pressKey({key:"home"}) would flow through to the chrome driver, which rejects unsupported keys with a runtime error mid-step. Reject at the factory so the spec author sees the failure where it originates. * chore(chrome): drop dead bundleSource/bundleMu bundleSource was written under bundleMu but never read. Either remove it or wire a re-install path; remove until the second is actually needed. * fix(chrome): use strconv.Atoi for extractor key parsing fmt.Sscanf("%d", ...) silently accepts trailing garbage like "3abc" as 3. strconv.Atoi rejects the same input outright, so a malformed key surfaces as an error instead of a wrong-bucket override. * fix(doctor): raise per-check timeout to 15s for chromium launch 5s could time out the headless chromium check on cold CI. Most checks finish in milliseconds, so a longer ceiling doesn't slow real failures. * fix(runner): trust V8 coordinates for InputText, even at origin resolveCoordinates required strict positive X/Y, so a V8-emitted InputText for an element at viewport (0, *) or (*, 0) skipped the focus tap and typed into whatever was focused. Distinguish the selector-driven path (mobile) from the coords-only path (web V8) so edge coordinates are honored without breaking the existing tree-lookup fallback. Add applyAction tests covering both the typical web case and the (0,0) edge case. * test(bundler): lock down deterministic output across builds The review flagged map-iteration nondeterminism as a possible cause of unstable bundle SHAs. Empirically esbuild's Define handling is order- independent (parallel substitution rules), so output is already stable. Add a regression test that builds 10x with multiple Defines and asserts SHA equality so any future change that introduces ordering surfaces.	2026-05-03 11:21:21 +07:00