pj
f572c8ba66
* docs: README covers iOS + web, surface both example apps * docs(cli): document --ios-device and per-platform doctor * docs: tighten README, fold examples into Docs list * docs(runs): correct --clear-data lifecycle wording Default behavior no longer wipes app data between runs; --clear-data is now opt-in. * docs(getting-started): add iOS path, separate folio and folio-web Document just test-ios under examples/folio, and distinguish the KMP sample from the React + Vite folio-web sample. * docs(inspect): document the eight panels Lists Screenshot, ActionList, Timeline, ViolationsPanel, HierarchyPanel, SnapshotTable, MetricsChart, ExceptionsPanel. Cross-links HierarchyPanel to the spec language reference. * docs(writing-specs): document setup export, flag noLogcatErrors as android-only Mirrors pkg/spec/README.md so the manual covers the runner's setup-first fall-through. Marks noLogcatErrors as Android-only so iOS/web spec authors know it silently no-ops. * docs(folio): document web target and iOS sanderling test recipe After the KMP refactor folio also runs on wasmJs and the justfile exposes just web, just web-build, and just test-ios. Surface all three. * docs(folio-web): add README Covers prerequisites, demo credentials, just test recipe, and how the React + Vite host exposes state to the sanderling spec via stable ids and data-* attributes. * docs: scrub driver-implementation name from user docs Drop the implementation tool name from README, cli.md doctor table, and spec-language.md. These docs should describe behaviour, not the specific underlying tool the native sidecar wraps. * docs(development): scrub driver-implementation name from dev docs architecture, design-principles, decisions now describe the native sidecar by role (gRPC surface over OS UI-test pipeline) rather than by the specific tool it wraps.
2.8 KiB
title
| title |
|---|
| Decisions |
Decisions
Architectural and organizational decisions worth recording. Each entry states the decision and the reasoning.
Directory and Package Organization
web/ renamed to inspect-ui/
The directory containing the React/TypeScript frontend is inspect-ui/, not web/. The name web/ was ambiguous (the project also has a web/Chrome driver target). inspect-ui/ makes the purpose explicit: this is the UI for the sanderling inspect command.
Keep internal/
Go's internal/ directory restriction prevents any code outside this module from importing these packages. Sanderling is a CLI tool today, but the restriction costs nothing to keep and prevents accidental coupling if the module is ever used as a Go dependency. All implementation packages live under internal/.
internal/driver/ is an interface + subdirectory implementations
The driver.go file defines the DeviceDriver interface. Concrete implementations live in subdirectories: sidecar/ (gRPC to the native sidecar), chrome/ (CDP), mock/ (tests). This pattern keeps the runner and verifier decoupled from any specific platform.
internal/verifier/marshal.go moves to internal/inspect/
marshal.go serializes LTL formulas to JSON for the inspect UI. That is an inspect concern, not a verifier concern. Verifier should not know inspect exists.
internal/verifier/bindings.go splits into types.go + bindings.go
bindings.go currently holds shared types (Action, ActionKind, LogEntry, Exception) alongside JavaScript runtime wiring. The types half moves to types.go so the two concerns are separately navigable.
internal/permissions/ stays as-is
Android-only package but there is no iOS equivalent yet. Revisit if iOS gets similar permission setup.
cmd/sanderling/android_env.go moves to internal/android/
Android device enumeration, AVD selection, and emulator boot logic moves to internal/android/. This keeps cmd/sanderling/ as a thin CLI wrapper and makes the Android logic independently testable.
cmd/sanderling/test_run.go logic moves to internal/testrun/
Driver setup, agent connection, verifier init, trace setup, and runner orchestration extract to internal/testrun/. cmd/sanderling/ wires CLI flags to testrun calls and nothing more.
internal/inspect/runs.go splits into multiple files
429 LOC with mixed concerns (cache, file I/O, JSON decoding, summary types) splits into at least runs_cache.go and runs_decode.go within the same package.
cmd/internal-tools/ stays in cmd/
bundle-check and hier-check are dev/debug binaries. Leave them under cmd/ for now.
pkg/spec-api/ renamed to pkg/spec/
Aligns the directory name with the npm package name @sanderling/spec.