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
> <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.
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
45 +{
"pid":
12345,
"port":
43123,
"token":
"...",
"endpoint":
"http://127.0.0.1:43123/rpc",
"endpointFile":
"/abs/target/fxdriver-endpoints/launch-1.json",
"startupMs":
822}
53 +java -jar fxdriver.jar rpc
<port
> ping
'{}' 58 +###
`version`, `capabilities` 61 +java -jar fxdriver.jar rpc
<port
> version
'{}' 62 +java -jar fxdriver.jar rpc
<port
> capabilities
'{}' 65 +Use these before relying on optional methods or selector forms.
70 +java -jar fxdriver.jar rpc
<port
> configure
'{"visualTrace":true,"highlightMs":250,"effect":"invert"}' 71 +java -jar fxdriver.jar rpc
<port
> configure
'{"visualTrace":false}' 74 +Controls optional visual tracing. When enabled, supported actions highlight the
75 +resolved target briefly before acting. Default is off. Effects are
76 +non-layout-affecting and apply to any JavaFX `Node`: `invert` (default;
77 +theme-independent), `colorAdjust`, `glow`, `bloom`.
82 +java -jar fxdriver.jar rpc
<port
> click
'{"nodeId":"save","highlightMs":250}' 85 +`highlightMs:0` disables trace for that action.
90 +java -jar fxdriver.jar rpc
<port
> snapshot
'{}' 91 +java -jar fxdriver.jar snapshot
<port
> --summary
94 +Optional type filters (exact simple class name, case-sensitive):
97 +java -jar fxdriver.jar rpc
<port
> snapshot
'{"includeTypes":["Button","TextField"]}' 98 +java -jar fxdriver.jar rpc
<port
> snapshot
'{"excludeTypes":["LabeledText","FontIcon"]}' 101 +Both can be combined. `excludeTypes` wins over `includeTypes`. Default (no
102 +filters) returns all visible nodes.
106 +- `windows[]`: visible JavaFX windows with bounds and nested nodes.
107 +- `nodes[]`: flat compatibility list.
109 +Important node fields:
118 +- `accessibleText`, `accessibleHelp`, `accessibleRole`,
119 + `accessibleRoleDescription`
121 +- `visible`, `disabled`, `focused`, `managed`, `mouseTransparent`,
122 + `pickOnBounds`, `opacity`, `cursor`, `actionable`
123 +- `bounds` (screen coordinates), `boundsInLocal`, `layoutBounds`
124 +- optional `semantic` object
126 +Initial `semantic` support:
128 +- `kind`: `labeled`, `button`, `hyperlink`, `toggle`, `checkbox`, `radio`,
129 + `textInput`, `list`, `tree`, `table`, `treeTable`, `comboBox`, `choiceBox`,
130 + `spinner`, `tabPane`, `text`, `control`
131 +- `ComboBox`/`ChoiceBox`: `value`, `itemsCount`, `selectedIndex` (+
132 + `editable`/`showing` for ComboBox); `Spinner`: `value`, `editable`; `TabPane`:
133 + `value` (selected tab text), `tabsCount`, `selectedIndex`
134 +- `Labeled`: `text`, `graphicType`, `contentDisplay`, `mnemonicParsing`,
135 + `wrapText`, `textOverrun`
136 +- `ButtonBase`: `armed`; `Button`: `defaultButton`, `cancelButton`; `Hyperlink`:
138 +- `ToggleButton`/`RadioButton`: `selected`, `toggleGroup`
139 +- `CheckBox`: `selected`, `indeterminate`, `allowIndeterminate`
140 +- `TextInputControl`: `value`, `prompt`, `editable`, `selectedText`,
141 + `selectionStart`, `selectionEnd`, `caretPosition`, `anchor`, `length`,
143 +- `TextField`: `prefColumnCount`; `TextArea`: `prefColumnCount`, `prefRowCount`,
144 + `wrapText`, `scrollTop`, `scrollLeft`
145 +- `ListView`: `itemsCount`, `selectionMode`, `selectedIndices`, `selectedItems`,
146 + `focusedIndex`, `editable`, `fixedCellSize`, `orientation`, `placeholderText`
147 +- `TreeView`: `itemsCount` (expanded items), `selectionMode`, `selectedIndices`,
148 + `selectedItems`, `focusedIndex`, `editable`, `fixedCellSize`, `rootVisible`,
150 +- `TableView`: `itemsCount`, `selectionMode`, `selectedIndices`,
151 + `selectedItems`, `focusedIndex`, `focusedCell`, `editable`, `fixedCellSize`,
152 + `placeholderText`, `columns`, `sortOrder`
153 +- `TreeTableView`: `itemsCount` (expanded items), `selectionMode`,
154 + `selectedIndices`, `selectedItems`, `focusedIndex`, `focusedCell`, `editable`,
155 + `fixedCellSize`, `rootVisible`, `rootValue`, `placeholderText`, `columns`,
158 +`PasswordField` text/value/selectedText are redacted by default
159 +(`masked: true`). Virtualized controls expose model/selection metadata;
160 +unrealized rows/cells are not emitted as nodes.
162 +###
`snapshotSummary` 165 +java -jar fxdriver.jar rpc
<port
> snapshotSummary
'{}' 166 +java -jar fxdriver.jar snapshot
<port
> --summary
169 +Returns a compact first view:
171 +- `windows[]`: window id/index/title/focus/bounds.
172 +- `buttons[]`: visible `ButtonBase` controls with text and selector path.
173 +- `textFields[]`: text inputs with value/prompt/editability.
174 +- `tables[]`: visible `TableView` and `TreeTableView` row/column summaries.
175 +- `selectedTabs[]`: selected tab text per visible `TabPane`.
176 +- `visibleTextSample[]`: bounded visible text sample for orientation.
178 +Use full `snapshot` when you need bounds, semantics, or raw node hierarchy.
179 +Copy `selectorPath` back as `selectorPath` when repeated labels make text
180 +selectors ambiguous.
185 +java -jar fxdriver.jar rpc
<port
> highlight
'{"selector":"type=Button"}' 186 +java -jar fxdriver.jar rpc
<port
> highlight
'{"selector":"type=Button","effect":"invert"}' 187 +java -jar fxdriver.jar rpc
<port
> highlight
'{"selector":"type=Button","effect":"glow"}' 190 +Applies a temporary non-layout JavaFX `Effect` to raw matching `Node`s,
191 +including non-control nodes such as `Text`, layout panes, and `SubScene`.
192 +Default `invert` effect uses blend-difference against white over the node's
193 +local bounds, so it is visible on both light and dark themes without changing
194 +layout. Use to verify selector ambiguity or show humans what target will be
195 +used. Calling `highlight` with no matches clears prior highlights. Visual trace
196 +for actions highlights the resolved actionable target instead.
201 +java -jar fxdriver.jar rpc
<port
> click
'{"nodeId":"find-duplicates"}' 202 +java -jar fxdriver.jar rpc
<port
> click
'{"textExact":"Keep duplicates"}' 203 +java -jar fxdriver.jar rpc
<port
> click
'{"textExact":"Projects","untilQuietMs":500,"timeoutMs":10000}' 206 +Fires `ButtonBase` directly when possible; otherwise uses JavaFX Robot center
207 +click. With `untilQuietMs`, waits after the click until the visible UI signature
208 +has stayed stable for that many milliseconds, or returns `QUIET_TIMEOUT`.
213 +java -jar fxdriver.jar rpc
<port
> fire
'{"textExact":"Find duplicates..."}' 216 +Calls `ButtonBase.fire()` on first matching button-like control.
218 +###
`type`, `setText`, `clear` 221 +java -jar fxdriver.jar rpc
<port
> setText
'{"nodeId":"filter-duplicates","value":"portrait"}' 222 +java -jar fxdriver.jar rpc
<port
> clear
'{"nodeId":"filter-duplicates"}' 223 +java -jar fxdriver.jar rpc
<port
> type
'{"nodeId":"filter-duplicates","value":"abc","replace":false}' 226 +Prefer `setText` for deterministic tests; use `type` when simulating user input
227 +matters. These set the control's text directly; for real keystrokes (Enter to
228 +submit a dialog, Tab to move focus, accelerators), use `key`.
233 +java -jar fxdriver.jar rpc
<port
> key
'{"key":"ENTER"}' 234 +java -jar fxdriver.jar rpc
<port
> key
'{"key":"CTRL+S"}' 235 +java -jar fxdriver.jar rpc
<port
> key
'{"nodeId":"search","chars":"hello"}' 238 +Sends real keystrokes as synthetic `KEY_PRESSED`/`KEY_TYPED`/`KEY_RELEASED`
239 +events (works headless, unlike OS-level robot keys). `key` is a single named key
240 +or chord — `ENTER`, `ESCAPE`/`ESC`, `TAB`, `UP`/`DOWN`/`LEFT`/`RIGHT`,
241 +`F1`–`F12`, letters, `CTRL+S`, `SHIFT+TAB`, `ALT+`/`META+`/`CMD+`. `chars` types
242 +a literal string. With a selector (`nodeId`, `textExact`, …) the target node is
243 +focused first; otherwise events go to the current focus owner. Returns the
244 +resolved key/chars and a description of the target node.
249 +java -jar fxdriver.jar rpc
<port
> select
'{"nodeId":"country","itemText":"Germany"}' 250 +java -jar fxdriver.jar rpc
<port
> select
'{"nodeId":"size","index":2}' 251 +java -jar fxdriver.jar rpc
<port
> select
'{"nodeId":"count","value":"42"}' 254 +Drives choice controls that `click`/`fire` cannot: `ComboBox`, `ChoiceBox`,
255 +`TabPane`, `Spinner`, `DatePicker`, `ColorPicker`, `Slider`, `ScrollBar`,
256 +`TableView`, `TreeView`, and `TreeTableView`. Selects by `itemText` (exact then
257 +contains, using the control's `StringConverter` where available), by `index`,
258 +or by `value` where the control exposes a direct value. For a Spinner, a
259 +positive `index` increments and a negative one decrements. Returns `kind`,
260 +`index`, `value`, and `selected`; `ok:false` with `UNSUPPORTED` if the matched
261 +node is not a selectable control, or `NO_ITEM` if no entry matched. (`ListView`
262 +selection has its own `selectListItem`.)
267 +java -jar fxdriver.jar rpc
<port
> tableCell
'{"nodeId":"projects","tableText":"MDP_40982497","column":"Projektnummer"}' 268 +java -jar fxdriver.jar rpc
<port
> tableCell
'{"nodeId":"projects","rowIndex":2,"columnIndex":0}' 271 +Returns a `TableView` or `TreeTableView` cell by row text/row index and
272 +column text, id, or index. The result includes `rowIndex`, `columnIndex`,
273 +resolved `column`, full `rowText`, `value`, and `ok`.
278 +java -jar fxdriver.jar rpc
<port
> fireMenuItem
'{"nodeId":"main-menu","path":["File","Save"]}' 279 +java -jar fxdriver.jar rpc
<port
> fireMenuItem
'{"nodeId":"actions","itemText":"Delete"}' 282 +Fires `MenuBar`, `MenuButton`, `SplitMenuButton`, or context-menu items without
283 +showing the popup. Use `path` for nested menu traversal or `itemText` to find
284 +the first matching item recursively. Returns the menu kind, resolved value, and
290 +java -jar fxdriver.jar rpc
<port
> wait
'{"text":"Done","timeoutMs":5000}' 291 +java -jar fxdriver.jar rpc
<port
> wait
'{"nodeId":"save","enabled":true,"timeoutMs":5000}' 294 +Polls until selector is present by default. Default timeout is 2000 ms; pass
295 +explicit `timeoutMs` for slow app operations. Optional predicates: `present`,
296 +`enabled`, `focused`, `visible`. Like the action commands, `wait` and `assert`
297 +only consider visible nodes unless `visible:false` is passed explicitly, so a
298 +satisfied `wait` means the follow-up `click`/`type` sees the same node. Failed
299 +waits include `nearMatches[]` with nearby visible text/id/type candidates and
300 +their `selectorPath`.
305 +java -jar fxdriver.jar rpc
<port
> assert
'{"textExact":"Keep duplicates","present":true}' 306 +java -jar fxdriver.jar rpc
<port
> assert
'{"selector":"type=Button","count":3}' 309 +Returns `{ok,count}`. The CLI exits non-zero only on a protocol-level JSON-RPC
310 +error (top-level `error` member); app-level `ok:false` results exit zero and
311 +need inspection in scripts.
313 +###
`events`, `clearEvents` 316 +java -jar fxdriver.jar rpc
<port
> events
'{}' 317 +java -jar fxdriver.jar rpc
<port
> events
'{"clear":true}' 318 +java -jar fxdriver.jar rpc
<port
> clearEvents
'{}' 321 +Returns recent fxdriver calls with `ts`, `method`, `ok`, `severity`, and
322 +`params`. `severity` is `info` for successful calls, `miss` for app-level
323 +`ok:false` responses such as exploratory selector misses, and `error` for
324 +protocol-level JSON-RPC errors. If request params include `tag` or `scenario`,
325 +the event copies them to top-level fields. Use `events {"clear":true}` to read
326 +and clear in one call.
330 +CLI shortcut for first visible stage/window:
333 +java -jar fxdriver.jar screenshot
<port
> target/fxdriver.png
336 +RPC supports window/default, node, and rect targets:
339 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"path":"/tmp/run/window.png"}' 340 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"target":"node","nodeId":"save","path":"/tmp/run/save.png"}' 341 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"target":"rect","x":0,"y":0,"w":320,"h":200,"path":"/tmp/run/crop.png"}' 342 +java -jar fxdriver.jar rpc
<port
> screenshot
'{"path":"/tmp/run/dialog.png","window":"w2"}' 345 +A relative `path` resolves against the target app's working directory, not the
346 +caller's — pass an absolute path (or use the CLI `screenshot` subcommand, which
347 +absolutizes before sending). The result echoes the absolute path written. Window
348 +and rect targets default to the first showing stage; pass `window` with a `wid`
349 +from snapshot (`"w2"`) to capture another stage. `press` accepts the same
350 +`window` parameter to scope accelerators.
352 +Captures optimized lossless PNG. RPC results include `path`, `bytes`, `target`,
353 +`image` bounds, `source` bounds/units, `scale`, `activeWindow`, and
354 +`visibleTextSample`. CLI screenshot prints that result plus image summary.
355 +Opaque screenshots may be encoded as RGB; transparent screenshots preserve
358 +###
`videoStart`, `videoStep`, `videoStop` 361 +java -jar fxdriver.jar rpc
<port
> videoStart
'{"path":"/tmp/run/run.gif","fps":10,"canvas":"fixed","width":1280,"height":900,"titleMode":"band"}' 362 +java -jar fxdriver.jar rpc
<port
> videoStep
'{"title":"Login"}' 363 +java -jar fxdriver.jar rpc
<port
> videoStop
'{}' 366 +Records one stage's scene into GIF by default or APNG with `quality:"high"`.
367 +Frames are captured on a timer and encoded as delta rects on a background
368 +thread: unchanged ticks cost no bytes, and the UI thread is never blocked on
369 +encoding (frames are dropped instead and reported as `dropped`; frame delays
370 +come from capture timestamps, so playback speed stays true to wall clock even
371 +under load). Params: `path` (resolved in the target JVM's working directory —
372 +prefer absolute), `fps` (default 10, clamped to 1-30), `maxMs` (hard cap,
373 +default 120000, clamped to 1000-3600000), `quality` (`low` GIF or `high` APNG),
374 +`window` (a `wid` from snapshot), `scalePercent` (clamped to 25-200, default
375 +100), `canvas`, `width`, `height`, `background`, `titleMode`, `titleHeight`,
376 +and `title`. One recording at a time: a second `videoStart` while recording
381 +- `canvas:"fixed"` uses explicit `width` and `height`; use this for
382 + deterministic test videos.
383 +- `canvas:"screen"` (default) uses a stable primary-screen canvas so
384 + login/splash windows do not trap the recording at their small size.
385 +- `canvas:"firstFrame"` preserves the older behavior where the first captured
386 + frame defines the animation canvas; use only for small, single-window
387 + captures or scalePercent comparisons.
389 +Every source frame is composed into the stable canvas. Oversized source frames
390 +are scaled down to fit and centered; smaller windows are centered on the
391 +`background` color (`#RRGGBB` or `#AARRGGBB`, default white).
393 +Native step titles are recorder overlays, not app UI. Set `titleMode:"band"` to
394 +reserve a title bar inside the video canvas, or `titleMode:"overlay"` for a
395 +translucent top-left label. `title` sets the initial title;
396 +`videoStep {"title":"..."}` changes it during recording and forces an immediate
397 +capture tick. `titleMode:"off"` disables drawing titles.
399 +`videoStop` returns `path`, `frames` (encoded), `captured`, `dropped`,
400 +`durationMs`, `bytes`, `startedAt` (epoch ms — correlate with `events`
401 +timestamps to map actions to video time), `canvasWidth`, `canvasHeight`,
402 +`canvas`, `titleMode`, `quality`, `format`, `steps`, `scaledFrames`, and `ok`.
403 +`ok:false` carries an error code: `NO_VIDEO` (nothing to stop), `NO_FRAMES` (no
404 +showing stage ever matched, no file written), `VIDEO_FAILED` (encoder error,
405 +e.g. unwritable path), or `VIDEO_STALLED`. Recording also finalizes on
406 +`shutdown` and on JVM exit. GIF is streamed, so even a killed process can leave
407 +the file playable through the last flushed frame. APNG is patched on close and
408 +requires normal finalization to be playable.
413 +java -jar fxdriver.jar image-summary target/fxdriver.png
416 +Reports path, bytes, width, height, average color, and average hash.
421 +java -jar fxdriver.jar image-diff before.png after.png target/diff.png
424 +Reports changed pixels, percent, changed bounds, size mismatch, and optional
425 +optimized lossless diff PNG path.
430 +java -jar fxdriver.jar rpc
<port
> listItems
'{"nodeId":"duplicates-list"}' 433 +Returns `ListView` item strings.
435 +###
`selectListItem` 438 +java -jar fxdriver.jar rpc
<port
> selectListItem
'{"nodeId":"duplicates-list","itemText":"portrait"}' 441 +Selects matching item. Default `activate=true` also fires a matching realized
442 +row button if available.
447 +java -jar fxdriver.jar rpc
<port
> scroll
'{"selector":"type=ScrollPane","amount":6}' 450 +Uses control-specific scroll when possible; Robot fallback otherwise.
455 +java -jar fxdriver.jar rpc
<port
> shutdown
'{}' 458 +Stops the target JVM's fxdriver RPC server, not the app itself.
465 +@handle capability label for numeric handles
468 +#node-id JavaFX node id
469 +.style-class JavaFX style class
470 +=exact text exact visible/control text
471 +text=Open contains visible/control text
472 +regexText=Open.* regex over visible/control text
473 +type=Button Java class simple name
474 +role=BUTTON accessible role
475 +accessible=Save accessible text contains
476 +path=window[0] ... selectorPath copied from snapshot
479 +JSON params that map to selectors:
483 +{
"nodeId":
"save" }
485 +{
"styleClass":
"primary" }
486 +{
"textExact":
"Save" }
488 +{
"regexText":
"Sa.*" }
489 +{
"type":
"Button" }
490 +{
"role":
"BUTTON" }
491 +{
"accessible":
"Save" }
492 +{
"selectorPath":
"window[0] > control[0] > button#save[0]" }
493 +{
"selector":
"type=Button" }