Description
Selenium Manager's --output flag has grown by accretion (logger β json/shell β mixed) into four modes that aren't four distinct use cases β they're two use cases with duplicates, and none of them provides the behavior conventionally expected of a CLI tool:
--output |
stdout |
stderr |
Notes |
logger |
β’ result + logs (text) β’ Streamed |
nothing |
β’ Default |
shell |
β’ result + INFO logs (text) β’ Streamed |
β’ logged errors (text) β’ Streamed |
β’ Not currently used β’ WARN/DEBUG/TRACE logging completely dropped, always (even with --debug) |
json |
β’ result + logs (JSON) β’ Buffered |
nothing |
β’ java, py, rb, js (pending #13989) β’ A crash can lose all logs β’ result.message intended as the failure reason, but holds the last non-path INFO/ERROR log, even on success |
mixed |
β’ result (JSON) β’ Buffered |
β’ logs (text) β’ Streamed |
β’ .NET β’ error field always holds the last non-path INFO/ERROR log, even on success |
| Proposed CLI default |
β’ result (text) β’ Buffered |
β’ logs (text) β’ Streamed |
β’ Follows standard conventions |
| Proposed Bindings default |
β’ result (JSON) β’ Buffered |
β’ logs (JSON) β’ Streamed |
β’ Follows standard conventions β’ Error information not included in result but obtained from exit code |
I uncovered this issue trying to figure out how to emit a notice about what data is getting sent to Plausible. There is no way to do it that works properly in all the --output modes we support because it conflates concerns that should be independent.
Proposal
Deprecate the --output toggle and replace with an audience target toggle β human vs application β with one consistent discipline underneath:
- Result β stdout, all diagnostics β stderr, always. Not a per-mode choice.
- One toggle selects only the payload shape on stdout: human-readable text (default) vs structured (JSON). (
logger/shell collapse into human; json/mixed collapse into application.)
- Model the result as data, not a constant-prefixed log line β emit
driver_path/browser_path directly.
- Failure is the exit code β the reason is logged to stderr (shown to a CLI user, replayed by a binding), never scraped into the result payload.
- Application mode streams logs on stderr, leaving stdout as the clean result document β and those streamed logs should be structured (one JSON object per line, e.g.
{"level","timestamp","message"}) so bindings can replay them without each writing a text parser.
Relevant context / related issues
Have you considered any alternatives or workarounds?
Fix the current --output modes in place rather than adding a new flag. Rejected because --output json/mixed are a consumed contract β Java/Python/Ruby/JS/.NET parse their exact shape β so changing their behavior in place breaks every binding at once. A new flag lets --output keep working through a deprecation window while bindings migrate deliberately. (Selenium Manager is in beta, so flags may change without guarantee, but a deprecation notice on --output still makes the migration explicit rather than silent.)
Description
Selenium Manager's
--outputflag has grown by accretion (loggerβjson/shellβmixed) into four modes that aren't four distinct use cases β they're two use cases with duplicates, and none of them provides the behavior conventionally expected of a CLI tool:--outputloggerβ’ Streamed
shellINFOlogs (text)β’ Streamed
β’ Streamed
β’
WARN/DEBUG/TRACElogging completely dropped, always (even with--debug)jsonβ’ Buffered
β’ A crash can lose all logs
β’
result.messageintended as the failure reason, but holds the last non-pathINFO/ERRORlog, even on successmixedβ’ Buffered
β’ Streamed
β’
errorfield always holds the last non-pathINFO/ERRORlog, even on successβ’ Buffered
β’ Streamed
β’ Buffered
β’ Streamed
β’ Error information not included in result but obtained from exit code
I uncovered this issue trying to figure out how to emit a notice about what data is getting sent to Plausible. There is no way to do it that works properly in all the
--outputmodes we support because it conflates concerns that should be independent.Proposal
Deprecate the
--outputtoggle and replace with an audience target toggle β human vs application β with one consistent discipline underneath:logger/shellcollapse into human;json/mixedcollapse into application.)driver_path/browser_pathdirectly.{"level","timestamp","message"}) so bindings can replay them without each writing a text parser.Relevant context / related issues
mixed.Have you considered any alternatives or workarounds?
Fix the current
--outputmodes in place rather than adding a new flag. Rejected because--output json/mixedare a consumed contract β Java/Python/Ruby/JS/.NET parse their exact shape β so changing their behavior in place breaks every binding at once. A new flag lets--outputkeep working through a deprecation window while bindings migrate deliberately. (Selenium Manager is in beta, so flags may change without guarantee, but a deprecation notice on--outputstill makes the migration explicit rather than silent.)