Why did the Selenium Team switch Grid configuration from JSON to TOML?

Skip to first unread message

Scott Babcock

Jun 14, 2023, 4:04:25 PMJun 14
to Selenium Developers
I've been working to upgrade my Selenium library from Selenium 3 to Selenium 4, and the farther I dig into the Grid configuration, the more issues I find.
  • At first blush, TOML doesn't seem too bad, but the implementation in Selenium 4 only supports hierarchies that are three levels deep: section/option/value. This is insufficient for fully specifying Grid configuration, as clearly demonstrated by the fact that the value of the "stereotype" option is formatted as a JSON string.
  • There appears to be no native ability to dynamically assemble or modify configurations in Selenium 4, a process that was easily accomplished in Selenium 3.
  • Full-function JSON APIs are ubiquitous, whereas TOML support is spotty at best.
Has there been any discussion within the core contributor group about switching the configuration format back to JSON? You could still provide the ability to use TOML, but the ability of JSON to fully express complex configurations and the availability of full-featured interfaces across all platforms on which Selenium is supported make this a superior option.


Jun 14, 2023, 4:09:11 PMJun 14
to Selenium Developers
Grid 4 supports both TOML and JSON. However, we have opted to recommend TOML because it is easier to read for humans and most use cases require simple configurations. For more complex configurations, JSON is accepted as well. We also lack documentation for the JSON format, that is true. But hey, this is always an opportunity to contribute!

There appears to be no native ability to dynamically assemble or modify configurations in Selenium 4, a process that was easily accomplished in Selenium 3.
It would be great to understand better what you mean and also the use case. Why don't you create a feature proposal explaining us?

Scott Babcock

Jun 15, 2023, 3:44:22 AMJun 15
to Selenium Developers
Thanks for the response. My use case is the programmatic local Grid management performed by my Selenium framework. I use a local Grid to supply browser instances because it provides much better control of resource utilization than just setting thread count, and this greatly improves behavior during parallel execution. My Grid implementation builds hub and node configuration files programmatically, which is relatively straightforward in Selenium 3 API. I'm finally incorporating Selenium 4 support, but I'm having difficulty building hub and node configuration files that the Grid 4 server implementation is happy with. The hub launches, but the node throws this error:

org.openqa.selenium.grid.config.ConfigException: No 'display-name' keyword was found in the provided configs!
        at org.openqa.selenium.grid.node.config.NodeOptions.lambda$addDriverConfigs$16(NodeOptions.java:352)
        at java.util.Optional.ifPresent(Optional.java:159)
        at org.openqa.selenium.grid.node.config.NodeOptions.addDriverConfigs(NodeOptions.java:325)
        at org.openqa.selenium.grid.node.config.NodeOptions.getSessionFactories(NodeOptions.java:218)
        at org.openqa.selenium.grid.node.local.LocalNodeFactory.create(LocalNodeFactory.java:81)

The process of assembling the Grid 4 node configuration is much more primitive, requiring me to build a nested Map object that I then convert to JSON and serialize into a file.
Here's the node configuration I'm providing:

  "node": {
    "detect-drivers": false,
    "driver-configuration": [
        "display-name": "htmlunit",
        "stereotype": {
          "browserName": "htmlunit",
          "browserVersion": "chrome",
          "maxInstances": 5,
          "seleniumProtocol": "WebDriver"
    "hub": "http:\u002f\u002f192.168.254.20:4446\u002fwd\u002fhub"

I'm clearly providing a "display-name" property, but my structure is apparently not correct. I'm going to add remote debugging options to my Java command line so I can trace through the execution to figure out exaclty what it is that the NodeOptions class is looking for.

Scott Babcock

Jun 16, 2023, 3:55:49 AMJun 16
to Selenium Developers
I've traced into NodeOptions, and it's doing stuff that doesn't make very much sense. My JSON configuration seems to be deserialized properly, but the code in NodeOptions uses the expression:

.filter(index -> drivers.get(index).startsWith("display-name"))

... which is expecting each driver configuration as a String to begin with "display-name". Here's my configuration as it's being extracted from the Config object:

[{display-name=htmlunit, stereotype={browserName=htmlunit, browserVersion=chrome, maxInstances=5, seleniumProtocol=WebDriver}}]

Clearly, this string doesn't start with "display-string", which makes sense given that the value from which it was derived in an array of JSON objects.
It seems that this code is attempting to parse structured data via the string representation of this data, rather than walking through the structure in a systematic way.
This is a fragile approach, and it's clearly unable to handle JSON configurations.


Jun 16, 2023, 3:56:19 AMJun 16
to Selenium Developers
Please report this as a bug and we will have a look. Thank you.

⇜Krishnan Mahadevan⇝

Jun 16, 2023, 7:18:06 AMJun 16
to selenium-...@googlegroups.com
I have raised a PR to fix this problem : https://github.com/SeleniumHQ/selenium/pull/12209

Thanks & Regards
Krishnan Mahadevan

"All the desirable things in life are either illegal, expensive, fattening or in love with someone else!"
My Scribblings @ http://wakened-cognition.blogspot.com/
My Technical Scribblings @ https://rationaleemotions.com/

You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to selenium-develo...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/72516487-f928-4cdb-9bd4-967a528df1b5n%40googlegroups.com.
Reply all
Reply to author
0 new messages