skip to content

Remote Run Mechanics

3 roadmaps7 questions

What changes in your test code once the browser lives on another machine: the client endpoint, files crossing the gap in both directions, and the endpoints that explain a stuck session.

on this pageshow

explore

questions

7

In Selenium Grid 4, what does the /status endpoint return and what does its ready flag mean?

level: juniorimportance: must knowfreq 66%

answer

  1. One GET tells you the grid's mood
  2. The reply is a JSON envelope
  3. A boolean, a message, a node list
  4. It asks whether any slot is free
  5. A fully booked grid is not ready

basics

~20 s

Selenium Grid's /status returns JSON holding a boolean ready flag, a message, and a nodes array describing every registered node and its slots. Ready is true only when at least one node is up and has a free slot.

solid answer

~40 s

A `GET` on a Selenium 4 Grid's `/status` — for example `http://localhost:4444/status` — returns a WebDriver-style envelope: a `value` object holding `ready`, `message` and `nodes`. The router computes `ready` as *at least one registered node is `UP` and still has a free slot*, so it answers "can a session start right now", not "is the grid healthy": a perfectly sound but fully booked grid reports `ready: false` with `Selenium Grid not ready.`. Each `nodes` entry carries `id`, `uri`, `maxSessions`, `sessionTimeout`, `heartbeatPeriod`, `availability`, `version`, `osInfo` and a `slots` array, where each slot has a `stereotype` and either a session object or `null`. The HTTP status stays `200` either way; the separate `/readyz` endpoint is the one that returns `503` when the grid's own components are not up.

go deeper

for a junior

Be ready to name the endpoint, show the curl, and say what ready means. Knowing that a full grid reports ready false is enough to stop you from reporting a healthy grid as broken.

for a middle

Explain the mechanics: ready is one anyMatch over registered nodes for UP plus a free slot, the HTTP status is always 200, and slots with a null session are the free ones.

for a senior

Show how you use it in operations: parse value.ready rather than the status code, watch the nodes array for missing registrations, and distinguish saturation from a distributor read timeout.

for a principal

Own the policy question of what readiness should gate. Decide whether a capacity signal belongs in a deployment gate at all, and where a capability-blind boolean stops being a useful contract for teams sharing one grid.

## What the endpoint is Every **Selenium 4 Grid** — started as `standalone`, as a `hub`, or as a separate `router` — serves a small read-only readiness document at `GET /status` on its public HTTP port. It is the cheapest question you can ask a grid: no client library, no session, one request. Selenium deliberately exempts `/status` (and `/readyz`) from the Origin and Content-Type header checks it applies to session traffic, so a bare `curl` or a container health probe reaches it without setting any headers. ## The shape of the document The body is a **WebDriver-style envelope**: one top-level `value` object holding three keys. - `ready` — a boolean, and the whole point of the endpoint. - `message` — either `Selenium Grid ready.` or `Selenium Grid not ready.`, a human-readable echo of `ready`. - `nodes` — an array with one entry per node the **distributor** currently knows about. ```json { "value": { "ready": true, "message": "Selenium Grid ready.", "nodes": [ { "id": "4b2f...", "uri": "http://10.0.0.7:5555", "maxSessions": 4, "sessionTimeout": 300000, "heartbeatPeriod": 60000, "availability": "UP", "version": "4.49.0", "osInfo": { "arch": "amd64", "name": "Linux", "version": "6.8.0" }, "slots": [ { "id": {}, "lastStarted": "1970-01-01T00:00:00Z", "session": null, "stereotype": { "browserName": "chrome" } } ] } ] } } ``` ## What `ready` actually computes The router builds `ready` with a single rule: **at least one registered node is `UP` and still has a free slot.** Concretely: 1. Ask the distributor for its status — every node it has registered, with that node's slots. 2. For each node, check `availability == UP` and that the count of slots holding a session is below the node's `maxSessions`. 3. If any node passes both, `ready` is `true`; otherwise it is `false`. Three things `ready` therefore is **not**: - It is **not** "every node is healthy". One `UP` node with a spare slot makes the whole grid `ready`, even when its neighbours are `DOWN`. - It is **not** "the queue is empty". Queue depth never enters the calculation. - It is **not** "a slot matching *your* capabilities is free". `ready` is **capability-blind**: it counts free slots, never their stereotypes. Two mechanical details bite people. First, the HTTP status is **always 200**, including when `ready` is `false` — the verdict lives in the body, so a probe that only looks at the status code learns nothing. Second, the router gives the distributor two seconds to answer; on timeout it returns `ready: false` with `Unable to read distributor status.` and **no `nodes` key at all**, which is a very different situation from a merely busy grid. ## Reading the `nodes` array | Field | What it tells you | |---|---| | `id`, `uri` | which node this is and where the router reaches it | | `availability` | `UP`, `DRAINING` or `DOWN` | | `maxSessions` | how many sessions this node will run at once | | `slots` | one entry per slot, each with a `stereotype` and a `session` | | `sessionTimeout`, `heartbeatPeriod` | both reported in **milliseconds** | | `version`, `osInfo` | node build and host platform, useful for spotting a stale node | A slot whose `session` is `null` is **free**; a slot with a session object is **busy**. Counting free slots per stereotype is how you turn `/status` from a yes/no into an actual capacity picture. ## `/status` versus `/readyz` | | `/status` | `/readyz` | |---|---|---| | Answers | can a session start right now? | did this process's own components come up? | | Body | JSON `value` envelope | short text, e.g. `Standalone is true` | | HTTP status | always `200` | `200` when ready, `503` when not | | Sees nodes | yes, the whole list | no | `/readyz` is the liveness signal for the grid **process**; `/status` is the capacity signal for the grid **fleet**. Confusing them is the classic mistake: a grid whose components are all healthy but whose slots are all busy reports `readyz` 200 and `/status` `ready: false` at the same instant, and both are correct. ## A worked read A team runs a nightly regression over a **construction-permit checklist** application against a grid of three nodes. The run stalls, and `/status` shows `ready: false`. The `nodes` array still lists all three nodes with `availability: UP`, and every slot carries a session object. Nothing is broken — the grid is simply full, and the pending requests are sitting in the session queue waiting for a checklist test to release a slot. Had the array instead come back empty, the diagnosis would be the opposite: the distributor knows about no nodes at all, so nothing has registered.

  • Your grid reports ready false but every node shows availability UP — what happened?
    `ready` is `true` only while some `UP` node still has a free slot. If every slot on every node holds a session, the grid is saturated rather than broken: `/status` says `ready: false` and `Selenium Grid not ready.` while each node's `availability` stays `UP`. New requests wait in the session queue until a slot frees.
  • How does a node's own /status differ from the router's?
    A Selenium 4 node serves `/status` on its own port and reports only itself. Its `ready` is that node's free-slot check, its `message` is `Ready` or `No free slots available`, and it adds a `registered` boolean saying whether the node has joined the grid, plus a `node` object with its slots. The router's `/status` instead aggregates every node the distributor knows about.
  • Why is a 200 response from /status a poor health check on its own?
    The router returns `200` whether `ready` is `true` or `false`, so a probe that inspects only the status code cannot tell a working grid from a saturated one. Parse the body and assert `value.ready`. If the distributor cannot be read within two seconds, the response is `ready: false` with `Unable to read distributor status.` and no `nodes` key.

It is the sign at a permitting office counter: it tells you whether a window is open right now, not whether the building is on fire.

saying these in an interview costs you the question

  • Reads ready false as a crashed grid rather than a fully booked one
  • Thinks ready true guarantees a free slot for the requested browser
  • Expects /status to answer HTTP 503 while ready is false
  • Looks for queued session requests inside the /status document
  • Forgets the payload is wrapped in a value envelope
open as a page

In Selenium 4, how do you point a test at a Grid endpoint instead of starting a local browser?

level: juniorimportance: must knowfreq 76%

basics

~20 s

Build a RemoteWebDriver with two arguments: the Grid's URL and an options object such as ChromeOptions. Those options become the session request the Grid routes, and every line of test code after that is unchanged.

open as a page

How do you tell an unreachable Selenium Grid apart from a Grid with no slot matching your request?

level: seniorimportance: must knowfreq 62%

basics

~20 s

Ask who produced the error. A transport failure has a network cause such as connection refused or unknown host and no WebDriver error body; a Grid that answered returns a session-not-created error whose message echoes the capabilities you asked for.

open as a page

How does a client query Selenium Grid's /graphql endpoint to read live session and queue state?

level: middleimportance: should knowfreq 44%

basics

~10 s

Selenium 4's Grid exposes a read-only GraphQL API at /graphql. You POST a JSON body holding a query string, and the schema offers four roots: grid, nodesInfo, sessionsInfo and session by id.

open as a page

In Selenium Grid, what does the se: capability namespace hold, and what do se:name and se:recordVideo do?

level: middleimportance: should knowfreq 38%

basics

~20 s

se: is Selenium's own capability prefix, read by the Grid and its nodes rather than by the browser. se:name labels the session in the Grid console and in any recording's file name; se:recordVideo asks a node that can record to capture that session.

open as a page

A Selenium Grid request stays queued: how do you tell a busy slot from a missing stereotype?

level: seniorimportance: should knowfreq 54%

basics

~20 s

Compare what was asked for with what is advertised. Read the pending capabilities from Selenium Grid's GraphQL sessionQueueRequests, then list every node's stereotypes and occupancy: a full match means saturation, no match means the request can never be served.

open as a page

A Selenium Grid suite stopped getting sessions after browserVersion was pinned in the client's options. Why?

level: seniorimportance: should knowfreq 47%

basics

~20 s

Everything the client sends that the Grid matches on narrows the set of slots that may serve it. A pinned version string no node advertises can never match, so the request becomes unroutable and comes back as a session-not-created failure.

open as a page