mirror of
https://github.com/priyanshujain/sanderling.git
synced 2026-10-02 11:07:10 +00:00
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.
58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
---
|
|
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`.
|