In Selenium 4, how do you decide which capabilities belong in alwaysMatch and which belong in firstMatch?

## The two members are a policy statement, not just syntax A Selenium 4 new-session request splits what you want into `alwaysMatch`, one object of conditions every candidate session must satisfy, and `firstMatch`, an ordered array of alternatives merged with it one at a time. The remote end serves the first merged candidate it can and answers `session not created` when it can serve none. Mechanically that is the whole algorithm. The decision that actually matters is which of your wishes you are willing to convert into a run that does not happen, because that is precisely what `alwaysMatch` does: **it is the list of conditions under which you would rather have no result than the wrong one.** ## Deciding what is genuinely a requirement For a support-ticket queue suite, work down from what the run asserts rather than from what feels rigorous: 1. **What would a failure mean if this key were different?** A Chrome-only layout defect in the queue table is only meaningful on Chrome, so `browserName` is a requirement. A "closing a ticket removes it from the queue" assertion means the same thing everywhere, so nothing about the browser is required for it. 2. **Would I rather this run not happen at all?** If the honest answer is "no, run it and tell me what you got", the key belongs in a `firstMatch` entry or nowhere. 3. **Can I tell afterwards which way it went?** A preference you cannot see in the result is a preference you cannot reason about. Until the report shows what was negotiated, an unstated alternative is worse than a hard requirement. The keys most often over-committed are `browserVersion` and `platformName`. Both feel like discipline, and both convert an ordinary environment change into a red suite that had nothing to say about that change. ## The two failure shapes you are choosing between | | Over-constrained `alwaysMatch` | Under-constrained request | |---|---|---| | Typical symptom | `session not created` before the first navigation | a green run on a browser nobody expected | | Who notices | everybody, immediately | nobody, until a defect escapes to production | | Real cost | lost runs and pressure to loosen in a hurry | results that cannot be reproduced or attributed | | Right response | keep only the keys the assertions depend on | record the negotiated capabilities with every result | Neither column is safe by default, and the choice is not "strict versus lax". It is which failure your team can actually detect. Loud failures are cheap to fix and expensive to suffer; quiet ones are the other way round, and a suite whose results nobody can attribute to a browser is the quiet kind. ## Ordering firstMatch is a preference you must be able to see `firstMatch` entries are tried in order, so the array is a ranked list rather than a set of equals. That ranking is a real design decision — "Linux normally, Windows when Linux is unavailable" is a statement about what the ticket-queue suite is for — and it is invisible in the result unless you make it visible: - Log the response's negotiated `capabilities` with every result, not only with failures. - Surface `browserName`, `browserVersion` and `platformName` in the report a human reads, not only in a file nobody opens. - Treat a suite that silently fell through to its second entry every night for a week as a fleet problem to fix, not a suite quirk to live with. ## Where the policy lives Every suite writing its own capability map from scratch is how a fleet ends up with a dozen slightly different opinions about what a run requires, none of them written down. The cheaper arrangement is one shared baseline map that expresses the fleet's real requirements, with a suite overriding it only where it has a reason it can state: - The shared baseline names the browser and tolerates the environment; it does not pin builds. - A pin lives with the one suite that needs it, so it fails alone and loudly instead of taking the fleet with it. - Every override is reviewable in one place, which is what makes "why does this suite require that?" an answerable question. ## What to watch afterwards Capability policy is not a decision you make once. The signals worth watching are cheap: the rate of `session not created` failures over time, how often a run served a non-preferred `firstMatch` entry, and how often a suite's recorded `browserVersion` differs from the one the team believes it tests on. A rising first number means the requirements have drifted ahead of the fleet. A rising second or third means the fleet has drifted ahead of the requirements, and nobody found out from the test results — which is the failure that costs the most, because it is discovered by a customer rather than by a red build.