Hi @mercmobily, I've done my best to render the spec in more accessible language at https://github.com/jlipps/simple-wd-spec, maybe that will help?

@jlipps Oh my. I spent the last 12 days battling the specs... and... I am not sure if I want to poke you for not telling me before (!), or build a statue in your honour :D
Oh my... you even explain ACTIONS! I ended up printing out the requests made by the selenium tests to have a vague idea of what the actions object should look like!!!

If there is any vote to place a link to this document in the OFFICIAL specs... well, you'd have my vote.

Now, about firstMatch and alwaysMatch... your document reads:

Basically, the remote end validates the alwaysMatch set and each set within the firstMatch list

I am not 100% sure what this means. But, if I understood the rest of your document and the specs right, it means I can write:

{
  "capabilities": {
    "alwaysMatch": {
       browserName: 'chrome'
    },
    "firstMatch": [
      {platformName: 'linux', pageLoadStrategy: 'eager'},
      {platformName: 'mac', pageLoadStrategy: 'eager'},
    ]
  }
}

The remote end will end up considering these capability objects in order:

// Choice (1)
{
  browserName: 'chrome'
  platformName: 'linux',
  pageLoadStrategy: 'eager'
}

// Choice (2)
{
  browserName: 'chrome'
  platformName: 'mac',
  pageLoadStrategy: 'eager'
}

...is that correct?
And what's a "typical" use-case here? I guess this would be handy when connecting to a proxy, matching out capabilities? What's a practical example of a capabilities object?

(FYI this WG has a policy that discussions should go on the mailing list.)

Capabilities negotiation of alwaysMatch and the set of firstMatch rules are related to RequiredCapabilities/DesiredCapabilities in Selenium, but under different names and with tighter semantics.

Capabilities are meant for defining a failsafe matrix selection of a browser configuration in a distributed WebDriver environment. When you communicate directly with an endpoint node (i.e. geckodriver) capabilities dictionaries are only used for carrying browser-specific configuration (i.e. moz:firefoxOptions), but in cases where you talk to an intermediary node multiplexer, that itself does not spin up a WebDriver session but that maybe forwards the request to another node, capabilities are used for selecting a node in this network that matches the capability requirements.

For example you might have a scenario where you need a Firefox instance but you don’t particularly care about what sort of Firefox you get: it can be any version of Firefox on any operating system:

{"alwaysMatch": {"browserName": "firefox"}}

If you did care about the operating system, and you needed it to be a Firefox on Windows or Linux:

{"alwaysMatch": {"browserName: "firefox"}, "firstMatch": [{"platformName": "windows"}, {"platformName: "linux"}]}

With this system you can create more complex matrix selections, say for example you need a browser that supports ignoring insecure TLS certificate, but if it’s Firefox it must also support changing the window dimensions but you don’t care about that with Safari:

{"alwaysMatch": {"acceptInsecureCerts": true}, "firstMatch": [{"browserName": "firefox", "setWindowRect": true}, {"browserName": "safari"}]}

As I mentioned the capabilities object is also used for communicating configuration. If we intersperse one of the previous examples with some fictious configuration for one of the intermediary nodes (maybe it runs on Sauce) and for the browser:

{"capabilities": {
  "alwaysMatch": {
    "browserName": "firefox",

    "sauce:token": "...",
    "moz:firefoxOptions": {
      "args": ["-headless"],
      "log": {"level": "trace"},
      "prefs": {
        "foo": "bar",
        "baz": false
      }
    }
  },
  "firstMatch": [
    {"platformName": "windows", "platformVersion": 10},
    {"platformName": "linux"}
  ]
}

I hope this helps.

I realise this is not a "help me! help me!" forum. I have really, honestly tried to gather this information from other sources; part of the problem is the terminology change (from Selenium). I just couldn't find anything that explained this.

Now... not only you explained it, but you also explained it amazingly well. would you mind me making a PR on the specs, adding this as an "Example"?

I don't want this to be lost in the quiet and hard-to-search sea of closed issues...

That is a good idea!

There is a pull request for this #1218