rnxsim 0.0.0 → 0.1.312

package/skills/rnx-test/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: rnx-test
+description: Run automated tests against your React Native app under rnx with Maestro YAML or Detox/Jest
+---
+
+# rnx tests
+
+rnx has two test runners. Maestro owns every YAML test, whether it was
+hand-authored, generated from a goal, or recorded from live CLI actions.
+Detox runs existing imperative Jest suites through the rnx driver.
+
+> needs a connected, pinned sim. if `rnxsim describe` errors, load
+> `/rnx-setup` first.
+
+## route in (decision tree)
+
+- have an existing `.maestro/` directory? → [Maestro](#branch--maestro)
+- have existing Detox specs? → [detox drop-in](#branch--detox-drop-in)
+- writing tests fresh, want plain-language generation, or want live authoring? → [Maestro](#branch--maestro)
+
+Do not invent a third runner for how a Maestro flow was authored.
+
+## anti-patterns (apply to both runners)
+
+- **`sleep` is almost always a bug.** the underlying CLI auto-settles
+  before reads and polls layout hash after writes. if a flow fails
+  without a `sleep`, the fix is `waitFor`, `waitForAnimationToEnd`, or
+  `wait idle` — not a blind timer. the one legitimate case: a
+  user-controlled debounce ("press and hold for 2s").
+- **prefer testID (`tapOn: { id: ... }`, `by.id(testID)`) over text.** text breaks
+  under i18n, copy churn, and duplicate strings. add `testID` during
+  implementation and author flows against it.
+- **pin a sim before running a suite.** parallel CI jobs colliding
+  on the default bridge port is the #1 flake source. pass `--port` in
+  CI and `rnxsim use <id>` locally.
+- **every flow ends with an assert, not a screenshot.** a screenshot
+  passes as long as the flow didn't throw. `assertVisible` (or
+  `expect(...).toBeVisible()`) actually verifies the happy path.
+- **don't run a 40-step "smoke everything" flow.** when it fails, you
+  can't tell what regressed. split into `login.yaml`, `compose.yaml`,
+  `settings.yaml`, chain with `runFlow`.
+
+## you're done when
+
+- the suite passes locally and in CI
+- every flake is either fixed or marked `xfail` with a written reason
+  and a removal date
+- the green run took noticeably less wall-clock than the previous
+  baseline (a suite that grows slower without growing wider is a smell)
+
+## branch — Maestro
+
+Write declarative Maestro YAML. The same command runs existing suites,
+generates tests, records live drafts, profiles, and uploads replayable results.
+
+```sh
+rnxsim maestro test .maestro/login.yaml             # run one flow
+rnxsim maestro test .maestro/login.yaml --record    # record video
+rnxsim maestro test .maestro/login.yaml --profile   # include perf stats
+rnxsim maestro test .maestro/                       # run the suite
+```
+
+Author from a live interaction:
+
+```sh
+rnxsim maestro start                     # begin a draft
+rnxsim do tap-id loginButton             # drive the app via the CLI
+rnxsim maestro keep                      # save the step
+rnxsim do type "user@example.com"
+rnxsim maestro keep
+rnxsim do tap-id submit
+rnxsim maestro keep
+rnxsim maestro end --output .maestro/login.yaml --validate
+```
+
+the recorder emits minimal YAML — no coordinate dumps, no `sleep` noise —
+because the underlying CLI already settled between every action.
+
+exemplar flow:
+
+```yaml
+# .maestro/login.yaml
+- launchApp: {}
+
+- waitFor:
+    text: 'Sign in'
+    timeout: 10000
+
+- tapOn:
+    id: emailInput
+- inputText: '${USERNAME}'
+
+- tapOn:
+    id: passwordInput
+- inputText: '${PASSWORD}'
+
+- tapOn:
+    id: signInButton
+- waitForAnimationToEnd: true
+
+- assertVisible: 'Welcome back'
+```
+
+run with env interpolation:
+
+```sh
+rnxsim maestro --env USERNAME=alice --env PASSWORD=hunter2 \
+  test .maestro/login.yaml \
+  --record --profile
+```
+
+automatic settling inside flows: every tap, type, scroll, swipe, and
+drag is backed by the same primitives that auto-wait for transitions on
+the way in and layout stability on the way out. you rarely need
+explicit waits; when you do, `waitForAnimationToEnd: true` maps to the
+CLI's `wait idle` with a generous budget. use it before any
+`assertVisible` that depends on a transition longer than ~400 ms.
+
+Generate and immediately run a Maestro flow from a plain-language goal:
+
+```sh
+rnxsim maestro generate "log in with the demo account and verify the dashboard"
+```
+
+Generation writes the same deterministic Maestro artifact, uploads its replay,
+and registers it as a Maestro run. The dashboard does not distinguish how it
+was authored.
+
+### existing Maestro suites
+
+if you already have a `.maestro/` directory, the migration is one
+command change:
+
+```sh
+# before
+maestro test .maestro/login.yaml
+
+# after
+rnxsim maestro test .maestro/login.yaml
+```
+
+no test rewrites, no detox config, no simulator. the runtime auto-launches
+an rnx shell if one isn't running.
+
+```sh
+rnxsim maestro                           # auto-discover .maestro/ or maestro/
+rnxsim maestro test .maestro/login.yaml
+rnxsim maestro test .maestro/            # every flow in a directory
+rnxsim maestro init                      # scaffold a starter flow
+rnxsim maestro --list-compat             # supported / partial / unsupported
+rnxsim maestro --env USERNAME=alice test .maestro/login.yaml
+```
+
+### supported verbs
+
+`launchApp`, `stopApp`, `clearState`, `tapOn`, `tapAtCoords`, `longPressOn`, `inputText`,
+`pressKey`, `dispatchKey`, `hideKeyboard`, `eraseText`, `assertVisible`,
+`assertNotVisible`, `assertTreeContains`, `waitFor`, `extendedWaitUntil`,
+`waitForAnimationToEnd`, `scroll`, `scrollUntilVisible`, `scrollTo`,
+`swipe`, `pinch`, `takeScreenshot`, `dumpTree`, `back`, `repeat.times`,
+`runFlow`, `when` (`visible` / `notVisible` / `platform` / `true`),
+`optional: true`, `onFlowStart` / `onFlowComplete`, `copyTextFrom` +
+`${maestroCopiedText}`, `evalScript`, `openLink`, env var `${NAME}`
+interpolation.
+
+### partial
+
+- `clearKeychain` — no keychain in rnx; logs a warning and continues.
+  if a test depends on keychain state being reset, add an explicit
+  in-app "sign out" step instead.
+- `when.platform` — rnx emulates iOS; android branches are skipped.
+- `openLink` — navigates `window.location`; no OS-level app routing.
+
+### not yet implemented
+
+these throw `unsupported maestro verb: X`:
+
+- `travel`, `setLocation`, `setAirplaneMode`, `killApp`
+- `addMedia`
+- `repeat.while` (use `repeat.times`)
+
+### troubleshooting
+
+- **"no maestro flows found"** — pass an explicit path
+  (`rnxsim maestro test path/to/flow.yaml`) or run `rnxsim maestro
+  init` to scaffold one.
+- **"missing environment variable for flow placeholder: FOO"** — pass
+  `--env FOO=bar` or export it. pick one mechanism per repo and document
+  it in the flow directory's README.
+- **flow can't find an element** — rnx's matcher uses testID + visible
+  text. UIKit-only labels that real maestro scrapes from the host OS won't
+  resolve here; switch to testID.
+- **flow runs but nothing renders** — confirm the bundler your flow
+  targets is reachable and pass `--url <port>` or add `app: <port>`
+  frontmatter at the top of the YAML.
+
+## branch — detox drop-in
+
+an existing detox suite runs against rnx with **one line** of jest
+config and zero test changes.
+
+`import { by, device, element, expect, waitFor } from 'detox'` is
+rewritten by jest to an rnx-backed driver that drives the real shell
+over playwright. matchers, assertions, and the `waitFor` API match the
+upstream detox surface.
+
+### one-line install
+
+```js
+// sootsim-detox.config.cjs
+module.exports = {
+  preset: 'rnxsim/detox/jest-preset',
+  rootDir: __dirname,
+  testMatch: ['<rootDir>/e2e/**/*.test.ts'],
+}
+```
+
+or, if you already have a jest config, pull in just the module mapper:
+
+```js
+moduleNameMapper: {
+  '^detox$': require.resolve('rnxsim/detox'),
+}
+```
+
+keep the **preset**, not just the mapper — the preset wires up the
+global setup/teardown that tears the shell down between suites. mapper-only
+works until your first hung shell.
+
+### commands
+
+```sh
+rnxsim detox                             # run e2e/, test/e2e/, or detox/
+rnxsim detox --config my.cjs             # use a specific jest config
+rnxsim detox --watch                     # jest watch mode
+rnxsim detox -t "login"                  # --testNamePattern
+rnxsim detox --headed                    # keep the shell window visible
+rnxsim detox --no-launch                 # don't auto-launch a shell
+rnxsim detox --port 5173                 # explicit bridge port for CI
+rnxsim detox init                        # scaffold config + e2e/example.test.ts
+```
+
+### compat surface
+
+| detox API                          | rnx |
+| ---------------------------------- | ------- |
+| `element(by.id(...))`              | supported |
+| `element(by.text(...))`            | supported — but prefer `by.id` |
+| `element(by.label(...))`           | supported |
+| `element(by.traits([...]))`        | supported for the iOS trait set |
+| `.toBeVisible()` / `.not.toBeVisible()` | supported |
+| `.toHaveText(...)` / `.toHaveLabel(...)` | supported |
+| `.tap()` / `.longPress()`          | supported |
+| `.typeText(...)` / `.replaceText(...)` | supported |
+| `.scroll(...)` / `.scrollTo(...)`  | supported |
+| `.swipe(...)`                      | supported |
+| `.setColumnToValue(...)`           | supported for uniquely named picker rows |
+| `waitFor(...).toBeVisible().withTimeout(...)` | supported |
+| `device.launchApp(...)` / `device.reloadReactNative()` | supported |
+| `device.shake()`                    | partial — emits the JS event, no haptic |
+| `device.sendUserNotification(...)`  | not yet |
+
+### troubleshooting
+
+- **"no rnx shell reachable"** — start one yourself
+  (`rnxsim open <port>`) or pass `--port <n>`.
+- **"jest cannot find module 'detox'"** — the preset isn't wired. confirm
+  `preset: 'rnxsim/detox/jest-preset'` is in the jest config jest
+  actually loaded (`--config` overrides package.json).
+- **matchers fail on elements that exist** — canvas has no DOM. use
+  `by.id` (testID); `rnxsim describe` shows what the shell sees.
+- **passes locally, flakes in CI** — the shell boots asynchronously.
+  bump jest `testTimeout` to 10–15 s and add a `waitFor(element(...))
+  .toBeVisible().withTimeout(10000)` before the first assertion.
+- **port conflicts under parallel CI** — pass `--port` explicitly per
+  job so workers don't collide on the default bridge port.
+
+## recovery — common failure modes (both runners)
+
+- **"no flows found"** — confirm the working directory or pass an explicit
+  `.maestro/` path.
+- **"missing env variable"** — set with `--env` (or jest env config) and
+  document the variable list in the flow directory's README so new
+  contributors aren't guessing.
+- **CI flakes but local passes** — bump test timeouts to 10–15 s before
+  the first assertion, pin the bridge port, and run with `--video` so
+  failing Maestro runs land a recording next to the output.
+- **a flake reproduces but resists fixing** — don't paper over with
+  `sleep`. open `/rnx-debug` against the same sim, capture
+  the timeline (`rnxsim timeline start` → reproduce → `rnxsim
+  what-happened`), and look for the missing animation-completion or
+  the unresolved fetch that's racing the assertion.

package/skills/rnx-visual/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: rnx-visual
+description: Pixel-level rendering comparison between rnx and native iOS — fonts, gradients, shadows, image fidelity
+---
+
+# rnx visual fidelity
+
+pixel-level rendering fidelity: does the rnx canvas match native iOS
+for text, gradients, shadows, blur, and image rendering? the `rnx`
+CLI gives you two primitives — **canvas capture** (`rnxsim screenshot`)
+and **structural diff** (`rnxsim debug snapshot`/`diff`). pixel
+comparison itself is "capture both sides, diff the PNGs with a standard
+image tool" — there is no single oracle-diff command, and that's fine:
+the capture step is the hard part and it's fully reproducible.
+
+> needs a connected, pinned sim. if `rnxsim describe` errors,
+> load `/rnx-setup` first.
+
+## route in
+
+- structural change ("which nodes / which props changed?") → load
+  `/rnx-debug`, debugging branch — `debug snapshot` + `debug
+  diff` is faster, deterministic, and tells you *why*.
+- visual change (color, gradient, shadow, font metric, blur, image)? →
+  continue here.
+- comparing rnx to your iOS simulator for fidelity? → continue.
+- regressing your own app against itself across commits? → continue.
+
+## anti-patterns (read first)
+
+- **run structural diff before pixel work.** `rnxsim debug snapshot` /
+  `debug diff` (in `/rnx-debug`) is cheaper, deterministic, and
+  points at the responsible nodes. only when it's empty (or the change is
+  pure rendering) does a pixel comparison add information.
+- **don't single-screenshot animated surfaces.** a gradient
+  mid-animation never matches. gate the capture behind `rnxsim wait
+  idle` first.
+- **a > 5% pixel threshold hides regressions.** ~1% is the right
+  ballpark for catching real font / shadow / gradient drift without
+  flagging anti-alias noise. go higher only with a written reason.
+- **pin device and theme.** capture both sides on the same simulated
+  device and appearance, or you're diffing layout, not rendering. use
+  `--themes` to capture light and dark together.
+- **commit baselines alongside the code change that produced them.**
+  baseline churn without code churn means someone captured noise.
+
+## capturing — `rnxsim screenshot`
+
+fast, no extra setup, works on any loaded app:
+
+```sh
+rnxsim screenshot --output app.png            # full canvas
+rnxsim screenshot --area 0,200,393,400        # crop to a logical rect
+rnxsim screenshot --id loginButton -o btn.png # crop to a node by testID
+rnxsim screenshot --text "Sign in"            # crop to a node by text
+rnxsim screenshot --gallery --themes          # crawl screens → HTML gallery, light+dark
+rnxsim screenshot --no-shell -o tenant.png    # tenant surface only, no iOS chrome
+rnxsim screenshot --shell-only                # only the simulated iOS chrome
+```
+
+`--gallery` crawls reachable screens and writes a browsable HTML gallery
+— the fastest way to eyeball a whole app for surprise rendering changes.
+
+## comparing pixels
+
+capture both sides to PNGs, then diff with any standard image tool.
+
+**rnx vs rnx (regression across your own commits):**
+
+```sh
+rnxsim screenshot -o before.png                      # baseline, before your change
+# … make the rendering change, let the sim hot-reload …
+rnxsim screenshot -o after.png                       # after your change
+npx pixelmatch before.png after.png diff.png 0.1      # writes diff.png
+# or: magick compare before.png after.png diff.png
+```
+
+**rnx vs native iOS (fidelity to the real thing):**
+
+```sh
+# native side — capture from your booted iOS simulator
+xcrun simctl io booted screenshot native.png
+# rnx side — same screen, same appearance
+rnxsim screenshot -o rnx.png
+npx pixelmatch native.png rnx.png diff.png 0.1
+```
+
+crop both to the same region (`--area` / `--id`) when you only care
+about one element — a full-screen diff buries a 3px font-baseline shift
+under unrelated chrome.
+
+## typical workflow
+
+1. structural diff first — confirm the change is genuinely visual.
+2. capture the affected screen with `rnxsim screenshot` (crop to the
+   element if you can).
+3. diff against the baseline (previous commit, or a native capture).
+4. iterate the rendering until the diff is under threshold.
+5. open the gallery (`--gallery`) and scroll through every screen — a red
+   patch on one icon is easy to miss when you're focused on one case.
+
+## you're done when
+
+- the diff is under threshold on every affected case, **or**
+- the differences are explicitly accepted, baselines re-captured, and
+  both halves (code + baselines) committed together.
+- the gallery shows no surprise changes when you scroll through every
+  screen, not just the one you targeted.
+
+## recovery — common failure modes
+
+- **a single icon/glyph diffs** — font-load race or image not yet
+  cached. recapture after `rnxsim wait idle`, or navigate away and back
+  to seed the cache.
+- **everything diffs by a constant offset** — you captured the two sides
+  on different devices or appearances. pin both, recapture.
+- **baselines churn without a code change** — someone captured noise (a
+  lingering badge, half-open keyboard, a drifting clock). revert and
+  recapture from a clean, idle state.
+- **persistent delta on the same font / shadow / gradient across
+  unrelated screens** — that's an engine-level rendering fidelity issue,
+  not your app. report it with the affected captures attached.