3 +Transport: JSON-RPC 2.0 over localhost HTTP POST.
8 +java -jar fxdriver.jar attach
<pid
> [port
] 9 +java -jar fxdriver.jar launch
[port
] -- \
10 + java
[java
-options...
] <main-or-jar
> [args...
] 11 +java -jar fxdriver.jar rpc
<port
|launch-json
> <method
> '<params-json>' [token
] 12 +java -jar fxdriver.jar snapshot
<port
> [-
-summary
] [token
] 15 +Attach/launch default to port `0`, so the OS chooses a free loopback port. The
16 +first fxdriver-owned CLI output line is machine-readable JSON with `pid`,
17 +`port`, `token`, `endpoint`, and `endpointFile`. Compatibility lines still print
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. `rpc` also accepts a saved launch JSON file and reads its port/token directly.
23 +Use `attach` for already-running apps:
26 +java -jar fxdriver.jar attach
<pid
> 27 +export FXDRIVER_TOKEN
=<printed-token
> 30 +Use `launch` for repeatable runs where you control the Java command:
33 +java -jar fxdriver.jar launch
-- \
34 + java --module-path
<mods
> --add-modules javafx.controls \
36 +export FXDRIVER_TOKEN
=<printed-token
> 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.
51 + "endpoint":
"http://127.0.0.1:43123/rpc",
52 + "endpointFile":
"/abs/target/fxdriver-endpoints/launch-1.json",
62 +java -jar fxdriver.jar rpc
<port
> ping
'{}' 67 +###
`version`, `capabilities` 70 +java -jar fxdriver.jar rpc
<port
> version
'{}' 71 +java -jar fxdriver.jar rpc
<port
> capabilities
'{}' 74 +Use these before relying on optional methods or selector forms. `capabilities` also returns `workingDirectory`, the base for relative screenshot paths.
79 +java -jar fxdriver.jar rpc
<port
> configure
'{"visualTrace":true,"highlightMs":250,"effect":"invert"}' 80 +java -jar fxdriver.jar rpc
<port
> configure
'{"visualTrace":false}' 83 +Controls optional visual tracing. When enabled, supported actions highlight the
84 +resolved target briefly before acting. Default is off. Effects are
85 +non-layout-affecting and apply to any JavaFX `Node`: `invert` (default;
86 +theme-independent), `colorAdjust`, `glow`, `bloom`.
91 +java -jar fxdriver.jar rpc
<port
> click
'{"nodeId":"save","highlightMs":250}' 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.
113 +java -jar fxdriver.jar rpc
<port
> snapshot
'{}' 114 +java -jar fxdriver.jar snapshot
<port
> --summary
117 +Optional type filters (exact simple class name, case-sensitive):
120 +java -jar fxdriver.jar rpc
<port
> snapshot
'{"includeTypes":["Button","TextField"]}' 121 +java -jar fxdriver.jar rpc
<port
> snapshot
'{"excludeTypes":["LabeledText","FontIcon"]}' 124 +Both can be combined. `excludeTypes` wins over `includeTypes`. Default (no
125 +filters) returns all visible nodes.
129 +- `windows[]`: visible JavaFX windows with bounds and nested nodes.
130 +- `nodes[]`: flat compatibility list.
132 +Important node fields:
140 +- `accessibleText`, `accessibleHelp`, `accessibleRole`,
141 + `accessibleRoleDescription`
143 +- `visible`, `disabled`, `focused`, `managed`, `mouseTransparent`,
144 + `pickOnBounds`, `opacity`, `cursor`, `actionable`
145 +- `bounds` (screen coordinates), `boundsInLocal`, `layoutBounds`
146 +- optional `semantic` object
148 +Initial `semantic` support:
150 +- `kind`: `labeled`, `button`, `hyperlink`, `toggle`, `checkbox`, `radio`,
151 + `textInput`, `list`, `tree`, `table`, `treeTable`, `comboBox`, `choiceBox`,
152 + `spinner`, `tabPane`, `text`, `control`
153 +- `ComboBox`/`ChoiceBox`: `value`, `itemsCount`, `selectedIndex` (+
154 + `editable`/`showing` for ComboBox); `Spinner`: `value`, `editable`; `TabPane`:
155 + `value` (selected tab text), `tabsCount`, `selectedIndex`
156 +- `Labeled`: `text`, `graphicType`, `contentDisplay`, `mnemonicParsing`,
157 + `wrapText`, `textOverrun`
158 +- `ButtonBase`: `armed`; `Button`: `defaultButton`, `cancelButton`; `Hyperlink`:
160 +- `ToggleButton`/`RadioButton`: `selected`, `toggleGroup`
161 +- `CheckBox`: `selected`, `indeterminate`, `allowIndeterminate`
162 +- `TextInputControl`: `value`, `prompt`, `editable`, `selectedText`,
163 + `selectionStart`, `selectionEnd`, `caretPosition`, `anchor`, `length`,
165 +- `TextField`: `prefColumnCount`; `TextArea`: `prefColumnCount`, `prefRowCount`,
166 + `wrapText`, `scrollTop`, `scrollLeft`
167 +- `ListView`: `itemsCount`, `selectionMode`, `selectedIndices`, `selectedItems`,
168 + `focusedIndex`, `editable`, `fixedCellSize`, `orientation`, `placeholderText`
169 +- `TreeView`: `itemsCount` (expanded items), `selectionMode`, `selectedIndices`,
170 + `selectedItems`, `focusedIndex`, `editable`, `fixedCellSize`, `rootVisible`,
172 +- `TableView`: `itemsCount`, `selectionMode`, `selectedIndices`,
173 + `selectedItems`, `focusedIndex`, `focusedCell`, `editable`, `fixedCellSize`,
174 + `placeholderText`, `columns`, `sortOrder`
175 +- `TreeTableView`: `itemsCount` (expanded items), `selectionMode`,
176 + `selectedIndices`, `selectedItems`, `focusedIndex`, `focusedCell`, `editable`,
177 + `fixedCellSize`, `rootVisible`, `rootValue`, `placeholderText`, `columns`,
180 +`PasswordField` text/value/selectedText are redacted by default
181 +(`masked: true`). Virtualized controls expose model/selection metadata;
182 +unrealized rows/cells are not emitted as nodes.
184 +###
Snapshot summary 187 +java -jar fxdriver.jar snapshot
<port
> --summary
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.
195 +- `windows[]`: window id/title/focus/bounds.
196 +- `buttons[]`: visible `ButtonBase` controls with text and disabled state.
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.
200 +- `tables[]`: visible `TableView` and `TreeTableView` row/column summaries.
201 +- `selectedTabs[]`: selected tab text per visible `TabPane`.
202 +- `focusedNode`: target metadata or `null`.
203 +- `visibleTextSample[]`: bounded visible text for orientation.
205 +Use full `snapshot` when you need complete semantics or raw node hierarchy.
210 +java -jar fxdriver.jar rpc
<port
> highlight
'{"selector":"type=Button"}' 211 +java -jar fxdriver.jar rpc
<port
> highlight
'{"selector":"type=Button","effect":"invert"}' 212 +java -jar fxdriver.jar rpc
<port
> highlight
'{"selector":"type=Button","effect":"glow"}' 215 +Applies a temporary non-layout JavaFX `Effect` to raw matching `Node`s,
216 +including non-control nodes such as `Text`, layout panes, and `SubScene`.
217 +Default `invert` effect uses blend-difference against white over the node's
218 +local bounds, so it is visible on both light and dark themes without changing
219 +layout. Use to verify selector ambiguity or show humans what target will be
220 +used. Calling `highlight` with no matches clears prior highlights. Visual trace
221 +for actions highlights the resolved actionable target instead.
226 +java -jar fxdriver.jar rpc
<port
> click
'{"nodeId":"find-duplicates"}' 227 +java -jar fxdriver.jar rpc
<port
> click
'{"textExact":"Keep duplicates"}' 228 +java -jar fxdriver.jar rpc
<port
> click
'{"textExact":"Projects","untilQuietMs":500,"timeoutMs":10000}' 231 +Fires `ButtonBase` directly when possible; otherwise uses JavaFX Robot center
232 +click. With `untilQuietMs`, waits after the click until the visible UI signature
233 +has stayed stable for that many milliseconds, or returns `QUIET_TIMEOUT`.
238 +java -jar fxdriver.jar rpc
<port
> fire
'{"textExact":"Find duplicates..."}' 241 +Calls `ButtonBase.fire()` on first matching button-like control.
243 +###
`type`, `setText`, `clear` 246 +java -jar fxdriver.jar rpc
<port
> setText
'{"nodeId":"filter-duplicates","value":"portrait"}' 247 +java -jar fxdriver.jar rpc
<port
> clear
'{"nodeId":"filter-duplicates"}' 248 +java -jar fxdriver.jar rpc
<port
> type
'{"nodeId":"filter-duplicates","value":"abc","replace":false}' 251 +Prefer `setText` for deterministic tests; use `type` when simulating user input
252 +matters. These set the control's text directly; for real keystrokes (Enter to
253 +submit a dialog, Tab to move focus, accelerators), use `key`.
258 +java -jar fxdriver.jar rpc
<port
> key
'{"key":"ENTER"}' 259 +java -jar fxdriver.jar rpc
<port
> key
'{"key":"CTRL+S"}' 260 +java -jar fxdriver.jar rpc
<port
> key
'{"nodeId":"search","chars":"hello"}' 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`.
270 +###
`setValue`, `selectIndex`, `selectListItem` 273 +java -jar fxdriver.jar rpc
<port
> setValue
'{"nodeId":"country","value":"Germany"}' 274 +java -jar fxdriver.jar rpc
<port
> selectIndex
'{"nodeId":"projects","index":2}' 275 +java -jar fxdriver.jar rpc
<port
> selectListItem
'{"nodeId":"duplicates-list","itemText":"portrait"}' 278 +Drives controls that `click`/`fire` cannot reliably set. Use `setValue` for
279 +controls with a direct value such as `ChoiceBox`, `ComboBox`, `DatePicker`,
280 +`Slider`, and text-like value controls. Use `selectIndex` for indexed selection
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.
300 +java -jar fxdriver.jar rpc
<port
> tableCell
'{"nodeId":"projects","tableText":"MDP_40982497","column":"Projektnummer"}' 301 +java -jar fxdriver.jar rpc
<port
> tableCell
'{"nodeId":"projects","rowIndex":2,"columnIndex":0}' 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`.
312 +java -jar fxdriver.jar rpc
<port
> fireMenuItem
'{"nodeId":"main-menu","path":["File","Save"]}' 313 +java -jar fxdriver.jar rpc
<port
> fireMenuItem
'{"nodeId":"actions","itemText":"Delete"}' 316 +Fires `MenuBar`, `MenuButton`, `SplitMenuButton`, or context-menu items without
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`.
325 +java -jar fxdriver.jar rpc
<port
> wait
'{"text":"Done","timeoutMs":5000}' 326 +java -jar fxdriver.jar rpc
<port
> wait
'{"nodeId":"save","enabled":true,"timeoutMs":5000}' 329 +Polls until selector is present by default. Default timeout is 2000 ms; pass
330 +explicit `timeoutMs` for slow app operations. Optional predicates: `present`,
331 +`enabled`, `focused`, `visible`. Like the action commands, `wait` and `assert`
332 +only consider visible nodes unless `visible:false` is passed explicitly, so a
333 +satisfied `wait` means the follow-up `click`/`type` sees the same node. Failed
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`.
342 +java -jar fxdriver.jar rpc
<port
> assert
'{"textExact":"Keep duplicates","present":true}' 343 +java -jar fxdriver.jar rpc
<port
> assert
'{"selector":"type=Button","count":3}' 346 +Returns `{ok,count}`. The CLI exits non-zero only on a protocol-level JSON-RPC
347 +error (top-level `error` member); app-level `ok:false` results exit zero and
348 +need inspection in scripts.
350 +###
`events`, `eventsSince`, `clearEvents` 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}' 356 +java -jar fxdriver.jar rpc
<port
> events
'{"clear":true}' 357 +java -jar fxdriver.jar rpc
<port
> clearEvents
'{}' 360 +Returns recent fxdriver calls with `ts`, `method`, `ok`, and `params`. If
361 +request params include `tag` or `scenario`, the event copies them to top-level
362 +fields. `eventsSince` accepts an event cursor or millisecond timestamp. Use `events {"clear":true}` to read and clear in one call.
366 +CLI shortcut for the focused showing stage, then first showing stage:
369 +java -jar fxdriver.jar screenshot
<port
> target/fxdriver.png
372 +RPC supports window/default, node, and rect targets:
375 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"path":"/tmp/run/window.png"}' 376 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"target":"node","nodeId":"save","path":"/tmp/run/save.png"}' 377 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"target":"rect","x":0,"y":0,"w":320,"h":200,"path":"/tmp/run/crop.png"}' 378 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"path":"/tmp/run/dialog.png","window":"w2"}' 381 +A relative `path` resolves against the target app's working directory, not the
382 +caller's — pass an absolute path (or use the CLI `screenshot` subcommand, which
383 +absolutizes before sending). The result echoes the absolute path written. Window
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.
389 +Captures optimized lossless PNG. RPC results include `path`, `bytes`, `target`,
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.
396 +###
Video and modal dispatch 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.
405 +java -jar fxdriver.jar image-summary target/fxdriver.png
408 +Reports path, bytes, width, height, average color, and average hash.
413 +java -jar fxdriver.jar image-diff before.png after.png target/diff.png
416 +Reports changed pixels, percent, changed bounds, size mismatch, and optional
417 +optimized lossless diff PNG path.
422 +java -jar fxdriver.jar rpc
<port
> listItems
'{"nodeId":"duplicates-list"}' 425 +Returns `ListView` item strings.
427 +###
`selectListItem` 430 +java -jar fxdriver.jar rpc
<port
> selectListItem
'{"nodeId":"duplicates-list","itemText":"portrait"}' 433 +Selects matching item. Default `activate=true` also fires a matching realized
434 +row button if available.
439 +java -jar fxdriver.jar rpc
<port
> scroll
'{"selector":"type=ScrollPane","amount":6}' 442 +Uses control-specific scroll when possible; Robot fallback otherwise.
447 +java -jar fxdriver.jar rpc
<port
> shutdown
'{}' 450 +Stops the RPC server. Apps started by `launch` exit; attached apps keep running. `exitApp:true` explicitly exits either.
457 +@handle capability label for numeric handles
460 +#node-id JavaFX node id
461 +.style-class JavaFX style class
462 +=exact text exact visible/control text
463 +text=Open contains visible/control text
464 +regexText=Open.* regex over visible/control text
465 +type=Button Java class simple name
466 +role=BUTTON accessible role
467 +accessible=Save accessible text contains
470 +JSON params that map to selectors:
474 +{
"nodeId":
"save" }
476 +{
"styleClass":
"primary" }
477 +{
"textExact":
"Save" }
479 +{
"regexText":
"Sa.*" }
480 +{
"type":
"Button" }
481 +{
"role":
"BUTTON" }
482 +{
"accessible":
"Save" }
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.