[🚀 Feature]: Selenium 4 Grid Slot Matching RFC

[sbabcoc]

Selenium 4 Grid Slot Matching RFC

Background

A core feature of Selenium 4 Grid is slot matching – the process of pairing a client “new session” request with a node that can satisfy the request. This process involves evaluating the client’s desired capabilities against the stereotypes of available nodes to determine which (if any) matches the request. The default implementation is defined in a class named DefaultSlotMatcher.

Implementation Details of DefaultSlotMatcher

• Step 1: Initial match – evaluate request against defined stereotype values:
  • Filter out extension capabilities (names that contain “:”)
  • Filter out platformName capability
  • Evaluate stereotype value against desired capability value:
    • If desired value is a string, perform case-insensitive comparison…
    • … else if desired value is defined, perform object comparison…
    • … else ignore capability with undefined desired value
• Step 2: Evaluate managed download capability:
  • Match if desired value is undefined or ‘false’…
  • … else match if stereotype supports managed downloads
• Step 3: Evaluate platformVersion capability:
  • Evaluate desired capabilities with names containing platformVersion
  • Match if a stereotype capability with identical name has the same value
• Step 4: Evaluate request against defined extension capability values:
  • Filter out capabilities containing goog:, moz:, ms:, or se:
  • Evaluate stereotype value against desired capability value:
    • If desired value is a string, perform case-insensitive comparison…
    • … else if desired value is defined, perform object comparison…
    • … else ignore capability with undefined desired value
• Step 5: Evaluate browserName capability:
  • Match if desired browserName value is undefined or empty
  • Match if stereotype browserName capability has the desired value
• Step 6: Evaluate browserVersion capability:
  • Match if desired browserVersion value is undefined, empty, or “stable”
  • Match if desired value is equivalent to stereotype browserVersion
• Step 7: Evaluate platformName capability:
  • Match if desired platformName value is undefined
  • Match if stereotype platformName capability has the desired value
  • Match if desired value is equivalent to stereotype platformName

Current Issue – Extension Capability Handling

As currently implemented, DefaultSlotMatcher has one obvious issue at Step 4 in its handling of extension capabilities. It ignores the extension capabilities of three vendors (Google, Mozilla, and Microsoft), but considers the extension capabilities of every other vendor (including Appium and Apple). This produces inconsistent slot matching behavior, with Appium extension capabilities causing slot matching to fail while similar Google extension capabilities would have no ill effect.

Solution – Capability Type Differentiation

The existing handling of extension capabilities for the three “special” vendors suggests that capabilities might be divided into two distinct categories: “identity” values that are considered for slot matching and configuration options that are transmitted to the matched node without analysis.

Patterns from Current Usage

In current usage, values defined within “options” extension capability objects should be ignored for slot matching (i.e. – configuration options). Two additional extension capabilities are also currently ignored: <prefix>:debuggerAddress and <prefix>:loggingPrefs. Every other defined capability for the three “special” vendors is treated as an “identity” value. However, these categories are merely incidental, not formally defined within the specifications. Consequently, there’s no defined mechanism for vendors to add new “identity” values or configuration options.

Proposal: Formally Define Capability Type Differentiation

Formalizing the current implied categorization of capabilities into “identity” values and configuration options will provide two distinct benefits:

1. Consistent treatment of extension capabilities will provide consistent behavior for all vendors.
2. Defining explicit patterns for “identity” values and configuration options enables each vendor to select the desired treatment for their extension capabilities, allowing them to add new capabilities and options as needed and get the expected handling without the need for custom slot matchers.

Definition of configuration options

The proposed definition for configuration options, which will be ignored for purposes of slot matching:

• Any extension capability with prefix se: (Selenium).
• Any extension capability with one of the following suffixes:
  • options
  • Options
  • loggingPrefs
  • debuggerAddress

Definition of “identity” values

All capabilities that don’t conform with the definition of configuration options as defined above will be treated as “identity” values, which will be considered for purposes of slot matching. This includes extension capabilities with “special” prefixes that would previously have been ignored. This change is merely academic, though, given that there are no currently defined “special” extension capabilities that are affected by the revised behavior.

Written with StackEdit.

Usage example

This feature will be implemented in DefaultSlotMatcher. Consequently, anyone using Selenium 4 Grid without explicitly configuring a custom slot matcher will encounter the revised behavior.

[github-actions]

@sbabcoc, thank you for creating this issue. We will troubleshoot it as soon as we can.

---

Info for maintainers

Triage this issue by using labels.

If information is missing, add a helpful comment and then I-issue-template label.

If the issue is a question, add the I-question label.

If the issue is valid but there is no time to troubleshoot it, consider adding the help wanted label.

If the issue requires changes or fixes from an external project (e.g., ChromeDriver, GeckoDriver, MSEdgeDriver, W3C), add the applicable G-* label, and it will provide the correct link and auto-close the issue.

After troubleshooting the issue, please add the R-awaiting answer label.

Thank you!

[titusfortner]

Wait, how do we match on platformVersion if that isn't even a valid capability?

If we filter out platformName in step 1 how are we matching it in step 7?

I don't like the idea of artificially declaring some values to be identity and some to be configuration. It's an arbitrary distinction that isn't in the spec.

I'd like to go the other direction and not treat any capabilities as special. Everything that I know of implements platformName, but Appium sessions don't always have browserName and browserVersion value is completely ignored by chromedriver regardless of what you put.

My question is: why do we need to treat any of these keys as special if the user isn't going to manually put them the stereotype? Is there some place where a more complicated stereotype is automatically generated?

[sbabcoc]

@titusfortner The check for platformVersion is performed in the existing DefaultSlotMatcher implementation. This isn't a new feature being proposed in this RFC, but it may have been added for the benefit of a specific vendor. As described in the Current Issues section, the existing implementation is inconsistent, treating extension capabilities with "special" prefixes differently than it treats extension capabilities with any other prefix.

As stated in this RFC, the purpose of capability differentiation is to enable vendors to decide which capabilities should be considered for slot matching, and which should be passed on to selected end nodes without analysis. This is currently only possible via custom slot matchers, which are mutually exclusive per hub. Another possible mechanism to enable vendor-specific behavior would be to add another method to WebDriverInfo to enable vendors to extend or override the matching performed by DefaultSlotMatcher.

Regarding the concept of formally defining two distinct capability categories versus how things are defined in the specification, I'm unaware of any detailed specifications for Selenium Grid, let alone the esoteric details of slot matching. As such, the implementation is the spec. The W3C WebDriver spec provides a lot of wiggle room regarding the handling of extension capabilities. It even presents the option of defining routing-specific capabilities to control how intermediate nodes match "new session" requests with compatible end nodes. This feature could potentially introduce an additional capability category (routing options), but I don't think this is strictly necessary.

[titusfortner]

I know I'm trying to understand why the existing implementation is like that. (and we probably need to wait until after the conference for the Grid experts to have time to answer) 😄