8 8 java -jar fxdriver.jar attach <
pid> [port]
9 9 java -jar fxdriver.jar launch [port] --
\ 10 10 java [java-options...] <
main-or-jar> [args...]
11 -java -jar fxdriver.jar rpc <
port> <
method> '<
params-json>' [token]
11 +java -jar fxdriver.jar rpc <
port|launch-json> <
method> '<
params-json>' [token]
12 12 java -jar fxdriver.jar snapshot <
port> [--summary] [
token]
16 16 first fxdriver-owned CLI output line is machine-readable JSON with `pid`,
17 17 `port`, `token`, `endpoint`, and `endpointFile`. Compatibility lines still print
18 18 the chosen port, an endpoint file, and `FXDRIVER_TOKEN`. RPC calls require that
19 -token via `FXDRIVER_TOKEN` or the optional final token argument.
19 +token via `FXDRIVER_TOKEN` or the optional final token argument. `rpc` also accepts a saved launch JSON file and reads its port/token directly.
21 21 ##
Attach vs launch 39 39 Current launch mode injects `-javaagent` after `java` and supports direct Java
40 +commands only. It supervises the child and blocks until the app exits. Run it
41 +as a persistent/background process, capture its first JSON stdout line, and keep
42 +the launcher alive: killing it also kills the app.
42 44 Example launch JSON:
69 71 java -jar fxdriver.jar rpc <
port> capabilities '{}'
72 -Use these before relying on optional methods or selector forms.
74 +Use these before relying on optional methods or selector forms. `capabilities` also returns `workingDirectory`, the base for relative screenshot paths.
92 94 `highlightMs:0` disables trace for that action.
96 +###
`run`, batch, and `mark` 98 +Group dependent actions with `run`; each step uses `op` (or `method`) plus the
99 +normal method parameters. It stops on the first failed step unless
100 +`continueOnError:true`. `returnState:"compact"` adds bounded state.
103 +java -jar fxdriver.jar rpc
<port
> run
'{"steps":[{"op":"setText","nodeId":"name","value":"Ada"},{"op":"wait","textExact":"Ada"}],"returnState":"compact"}' 104 +java -jar fxdriver.jar rpc
<port
> mark
'{}' 107 +The HTTP endpoint also accepts a raw JSON-RPC request array as a batch. `mark`
108 +visually marks showing stages and needs no parameters.
171 187 java -jar fxdriver.jar snapshot <
port> --summary
174 -The CLI summary command returns a compact first view:
190 +The CLI summary command returns a compact first view. It caps windows at 8,
191 +buttons at 24, text fields at 16, value controls at 24, menus at 16, tables at
192 +12, selected tabs at 12, and the distinct visible-text sample at 40 strings. Integration tests enforce a 16 KiB
193 +response bound for the focused fixture.
176 -- `windows[]`: window id/index/title/focus/bounds.
177 -- `buttons[]`: visible `ButtonBase` controls with text.
195 +- `windows[]`: window id/title/focus/bounds.
196 +- `buttons[]`: visible `ButtonBase` controls with text and disabled state.
178 197 - `textFields[]`: text inputs with value/prompt/editability.
198 +- `controls[]`: toggles and choice/date/spinner/range values.
199 +- `menus[]`: menu controls and context-menu targets with nested item paths.
179 200 - `tables[]`: visible `TableView` and `TreeTableView` row/column summaries.
180 201 - `selectedTabs[]`: selected tab text per visible `TabPane`.
181 -- `visibleTextSample[]`: bounded visible text sample for orientation.
202 +- `focusedNode`: target metadata or `null`.
203 +- `visibleTextSample[]`: bounded visible text for orientation.
183 -Use full `snapshot` when you need bounds, semantics, or raw node hierarchy.
205 +Use full `snapshot` when you need complete semantics or raw node hierarchy.
238 260 java -jar fxdriver.jar rpc <
port> key '{"nodeId":"search","chars":"hello"}'
241 -Sends real keystrokes as synthetic `KEY_PRESSED`/`KEY_TYPED`/`KEY_RELEASED`
242 -events (works headless, unlike OS-level robot keys). `key` is a single named key
243 -or chord — `ENTER`, `ESCAPE`/`ESC`, `TAB`, `UP`/`DOWN`/`LEFT`/`RIGHT`,
244 -`F1`–`F12`, letters, `CTRL+S`, `SHIFT+TAB`, `ALT+`/`META+`/`CMD+`. `chars` types
245 -a literal string. With a selector (`nodeId`, `textExact`, …) the target node is
246 -focused first; otherwise events go to the current focus owner. Returns the
247 -resolved key/chars and a description of the target node.
263 +Dispatches synthetic JavaFX `KeyEvent`s to a node; it is not OS/global input.
264 +`key` accepts one named key or chord such as `ENTER`, `ESCAPE`/`ESC`, `TAB`,
265 +`F1`, `CTRL+S`, `SHIFT+TAB`, or `META+K`. `chars` emits one `KEY_TYPED` event
266 +per Unicode code point. With a selector (`nodeId`, `textExact`, …), the first
267 +match is focused; otherwise the current JavaFX focus owner is used. The result
268 +contains `key`, `chars`, `sent`, and `target`; no target returns `NO_FOCUS`.
249 270 ### `setValue`, `selectIndex`, `selectListItem`
258 279 controls with a direct value such as `ChoiceBox`, `ComboBox`, `DatePicker`,
259 280 `Slider`, and text-like value controls. Use `selectIndex` for indexed selection
260 281 in list/table/tree-style controls. Use `selectListItem` for `ListView` by item
282 +text. A generic `select` method is intentionally unsupported.
284 +###
Choice, popup, and step controls 287 +java -jar fxdriver.jar rpc
<port
> setValue
'{"nodeId":"theme","value":"Dark"}' 288 +java -jar fxdriver.jar rpc
<port
> showPopup
'{"nodeId":"density"}' 289 +java -jar fxdriver.jar rpc
<port
> hidePopup
'{"nodeId":"density"}' 290 +java -jar fxdriver.jar rpc
<port
> increment
'{"nodeId":"days","steps":5}' 291 +java -jar fxdriver.jar rpc
<port
> decrement
'{"nodeId":"days","steps":2}' 294 +`setValue` supports choice/combo/date/range/spinner controls. Increment and
295 +decrement default to one step.
267 301 java -jar fxdriver.jar rpc <
port> tableCell '{"nodeId":"projects","rowIndex":2,"columnIndex":0}'
270 -Returns a `TableView` or `TreeTableView` cell by row text/row index and
271 -column text, id, or index. The result includes `rowIndex`, `columnIndex`,
272 -resolved `column`, full `rowText`, `value`, and `ok`.
304 +Reads `TableView` or `TreeTableView` model values by row text/row index and
305 +flat top-level column text, id, or index. It does not depend on realized cell
306 +nodes. The result includes `rowIndex`, `columnIndex`, resolved `column`, full
307 +`rowText`, `value`, and `ok`; failures use `NO_TABLE`, `NO_ROW`, or `NO_COLUMN`.
274 309 ### `fireMenuItem`
281 316 Fires `MenuBar`, `MenuButton`, `SplitMenuButton`, or context-menu items without
282 -showing the popup. Use `path` for nested menu traversal or `itemText` to find
283 -the first matching item recursively. Returns the menu kind, resolved value, and
317 +showing a JavaFX popup. It cannot operate native menus or dialogs. Use `path`
318 +for nested traversal or `itemText` for exact-then-contains recursive lookup.
319 +The result contains `query`, `kind`, `path`, `value`, and `fired`; failures use
320 +`NO_MENU_ITEM` or `DISABLED`.
295 331 `enabled`, `focused`, `visible`. Like the action commands, `wait` and `assert`
296 332 only consider visible nodes unless `visible:false` is passed explicitly, so a
297 333 satisfied `wait` means the follow-up `click`/`type` sees the same node. Failed
298 -waits return `ok:false` with `TIMEOUT`; take a fresh snapshot or CLI summary to
299 -compare visible text, ids, roles, and control state before retrying.
334 +waits return `ok:false` with `TIMEOUT` and up to five bounded `nearMatches`.
335 +Each candidate has `eid`, `type`, `id`, `text`, and diagnostic `selectorPath`.
336 +Near matches and selector paths explain misses; they are not supported
337 +selectors. Successful waits omit `nearMatches`.
309 347 error (top-level `error` member); app-level `ok:false` results exit zero and
310 348 need inspection in scripts.
312 -###
`events`, `clearEvents` 350 +###
`events`, `eventsSince`, `clearEvents` 315 353 java -jar fxdriver.jar rpc
<port
> events
'{}' 354 +java -jar fxdriver.jar rpc
<port
> eventsSince
'{"cursor":20}' 355 +java -jar fxdriver.jar rpc
<port
> eventsSince
'{"since":1735689600000}' 316 356 java -jar fxdriver.jar rpc
<port
> events
'{"clear":true}' 317 357 java -jar fxdriver.jar rpc
<port
> clearEvents
'{}' 320 360 Returns recent fxdriver calls with `ts`, `method`, `ok`, and `params`. If
321 361 request params include `tag` or `scenario`, the event copies them to top-level
322 -fields. Use `events {"clear":true}` to read and clear in one call.
362 +fields. `eventsSince` accepts an event cursor or millisecond timestamp. Use `events {"clear":true}` to read and clear in one call.
326 -CLI shortcut for first visible stage/window:
366 +CLI shortcut for the focused showing stage, then first showing stage:
329 369 java -jar fxdriver.jar screenshot
<port
> target/fxdriver.png
341 381 A relative `path` resolves against the target app's working directory, not the
342 382 caller's — pass an absolute path (or use the CLI `screenshot` subcommand, which
343 383 absolutizes before sending). The result echoes the absolute path written. Window
344 -and rect targets default to the first showing stage; pass `window` with a `wid`
345 -from snapshot (`"w2"`) to capture another stage. `press` accepts the same
346 -`window` parameter to scope accelerators.
384 +and rect targets default to the focused showing JavaFX stage, then the first
385 +showing stage; pass `window` with a stage `wid` from snapshot (`"w2"`) to
386 +capture that exact stage. Popup window ids are rejected. `press` accepts the
387 +same parameter to scope accelerators.
348 389 Captures optimized lossless PNG. RPC results include `path`, `bytes`, `target`,
349 -`image` bounds, `source` bounds/units, `scale`, `activeWindow`, and
350 -`visibleTextSample`. CLI screenshot prints that result plus image summary.
351 -Opaque screenshots may be encoded as RGB; transparent screenshots preserve
390 +`image` bounds, `source` bounds/units, `scale`, `activeWindow`, and a bounded
391 +`visibleTextSample` for orientation. `activeWindow` contains only id, title,
392 +bounds, and focused-node metadata—not a recursive snapshot. CLI screenshot
393 +prints that result plus image summary. Opaque screenshots may be encoded as
394 +RGB; transparent screenshots preserve alpha.
354 -###
`videoStart`, `videoStep`, `videoStop` 396 +###
Video and modal dispatch 357 -java -jar fxdriver.jar rpc
<port
> videoStart
'{"path":"/tmp/run/run.gif","fps":10,"canvas":"fixed","width":1280,"height":900,"titleMode":"band"}' 358 -java -jar fxdriver.jar rpc
<port
> videoStep
'{"title":"Login"}' 359 -java -jar fxdriver.jar rpc
<port
> videoStop
'{}' 362 -Records one stage's scene into GIF by default or APNG with `quality:"high"`.
363 -Frames are captured on a timer and encoded as delta rects on a background
364 -thread: unchanged ticks cost no bytes, and the UI thread is never blocked on
365 -encoding (frames are dropped instead and reported as `dropped`; frame delays
366 -come from capture timestamps, so playback speed stays true to wall clock even
367 -under load). Params: `path` (resolved in the target JVM's working directory —
368 -prefer absolute), `fps` (default 10, clamped to 1-30), `maxMs` (hard cap,
369 -default 120000, clamped to 1000-3600000), `quality` (`low` GIF or `high` APNG),
370 -`window` (a `wid` from snapshot), `scalePercent` (clamped to 25-200, default
371 -100), `canvas`, `width`, `height`, `background`, `titleMode`, `titleHeight`,
372 -and `title`. One recording at a time: a second `videoStart` while recording
377 -- `canvas:"fixed"` uses explicit `width` and `height`; use this for
378 - deterministic test videos.
379 -- `canvas:"screen"` (default) uses a stable primary-screen canvas so
380 - login/splash windows do not trap the recording at their small size.
381 -- `canvas:"firstFrame"` preserves the older behavior where the first captured
382 - frame defines the animation canvas; use only for small, single-window
383 - captures or scalePercent comparisons.
385 -Every source frame is composed into the stable canvas. Oversized source frames
386 -are scaled down to fit and centered; smaller windows are centered on the
387 -`background` color (`#RRGGBB` or `#AARRGGBB`, default white).
389 -Native step titles are recorder overlays, not app UI. Set `titleMode:"band"` to
390 -reserve a title bar inside the video canvas, or `titleMode:"overlay"` for a
391 -translucent top-left label. `title` sets the initial title;
392 -`videoStep {"title":"..."}` changes it during recording and forces an immediate
393 -capture tick. `titleMode:"off"` disables drawing titles.
395 -`videoStop` returns `path`, `frames` (encoded), `captured`, `dropped`,
396 -`durationMs`, `bytes`, `startedAt` (epoch ms — correlate with `events`
397 -timestamps to map actions to video time), `canvasWidth`, `canvasHeight`,
398 -`canvas`, `titleMode`, `quality`, `format`, `steps`, `scaledFrames`, and `ok`.
399 -`ok:false` carries an error code: `NO_VIDEO` (nothing to stop), `NO_FRAMES` (no
400 -showing stage ever matched, no file written), `VIDEO_FAILED` (encoder error,
401 -e.g. unwritable path), or `VIDEO_STALLED`. Recording also finalizes on
402 -`shutdown` and on JVM exit. GIF is streamed, so even a killed process can leave
403 -the file playable through the last flushed frame. APNG is patched on close and
404 -requires normal finalization to be playable.
398 +`videoStart`, `videoStep`, and `videoStop` are not available in this phase.
399 +Modal-safe asynchronous action dispatch is also deferred. Check `capabilities`
400 +rather than assuming either API exists.
406 402 ###
`image-summary` 451 447 java -jar fxdriver.jar rpc <
port> shutdown '{}'
454 -Stops the target JVM's fxdriver RPC server, not the app itself.
450 +Stops the RPC server. Apps started by `launch` exit; attached apps keep running. `exitApp:true` explicitly exits either.
486 482 { "accessible": "Save" }
487 483 { "selector": "type=Button" }
486 +Snapshot and near-match `selectorPath` values are diagnostics only and cannot
487 +be passed back as selectors. Generic `select` is unsupported; use the explicit
488 +selection methods above.