skip to content

A Selenium driver constructor throws in CI — how do you tell which startup stage failed?

level: seniorimportance: must knowfreq 50%

answer

  1. Not every constructor failure is alike
  2. Did anything answer at all?
  3. A refusal proves reachability
  4. The exception type separates two stages
  5. No object means nothing to close

basics

~20 s

Split it by what answered. A connection failure at the driver address means nothing was listening, so no session was requested. A session-not-created error means the endpoint answered and declined. A recorded session id means startup already finished.

solid answer

~40 s

In Selenium 4, constructing a driver is a chain, and the exception says which link broke. If the client could not reach the driver at all — a refused connection or no reply from the loopback port, or from the remote URL — nothing was ever asked to create a session, so the problem is getting a driver up or reaching the address. If a `SessionNotCreatedException` comes back, the endpoint was reachable and answered: it received the request and declined it, and the message it carries is the remote end's own explanation. If a session id was recorded, construction succeeded and the failure is later. A browser window appearing before the throw also rules out the first stage. Triage in that order rather than retrying blindly, because a stage-one failure repeats.

go deeper

for a junior

Recognise that a failure on the construction line happened before any test step ran, and that the exception message should be read and reported rather than the line simply re-run.

for a middle

Explain the stages construction passes through and what each exception type proves about how far it got, including why an answered-and-declined request is different from nothing answering.

for a senior

Show a repeatable triage: exception type first, then whether a session id or a window ever existed, then the remote end's own message, then a bare construction reproduced on the failing host.

for a principal

Own how startup failures are surfaced across a fleet: reported separately from assertion failures, carrying the endpoint and the remote end's message, so nobody spends a morning debugging a browser that never opened.

## Three stages, three different failures Constructing a driver in Selenium 4 is not one operation but a short chain, and a talk-submission suite that dies on `new ChromeDriver()` in a pipeline has failed at exactly one link of it: 1. **Getting an endpoint to answer.** A local constructor has to start a driver process and wait for the port it bound; a remote one has to reach the URL it was given. Until something answers, no session has been requested at all. 2. **Getting the session created.** The client sends the new-session command; the remote end either creates a browser session and returns a **session id**, or declines it. 3. **Everything after.** With an id in hand, construction is over. Anything failing now is the test, not startup. Telling them apart is the whole job, because each points somewhere different: stage one is about processes, ports and reachability, and stage two is about what the remote end was willing to give. ## The triage, in order 1. **Read the exception type, not only its message.** A `SessionNotCreatedException` proves the request arrived and something answered it. A `WebDriverException` complaining about a connection or a timeout to an address proves the opposite — nothing answered. 2. **Ask whether a session id ever existed.** If the run logged one, construction finished; look at the first command instead. 3. **Ask whether a browser window appeared.** A visible window means the driver got as far as launching a browser, which rules out stage one entirely. 4. **Read the remote end's message verbatim.** The client wraps the remote end's own text; that text, not the surrounding stack trace, names the reason. 5. **Reproduce the construction alone**, with no test around it. If a bare constructor fails identically on the same machine, the suite is not implicated and the environment is. ## Reading the stage from the symptom | Symptom | What it proves | Stage | |---|---|---| | Connection refused at the driver address | nothing was listening; no session requested | one | | The line hangs, then fails with no reply | something is there but never answered | one | | `SessionNotCreatedException` with a message | the endpoint answered and declined | two | | A window opened, then the line threw | the browser launched; the reply was the problem | two | | A session id appears in the log first | construction succeeded; look later | three | ## What a thrown constructor leaves behind - **No object.** The constructor never returned, so no variable was assigned and there is nothing to call an ending command on. - **Possibly a process.** A driver process, and sometimes a browser, may already be running when the failure lands. - **A misleading report.** Setup failures are often rendered as the test failing, which sends people reading the test body when the machine is at fault. ## Why the same line behaves differently on two machines Construction is the step most dependent on the host, because it is the only step that starts processes and binds ports; everything after it is HTTP to something already running. That asymmetry is why a line that has worked on a laptop for months can fail the first time it runs somewhere else, and why the useful question is never *why does this test fail* but *which stage of startup did this machine not complete*. ## What the message is telling you The Java client is deliberately a thin messenger here: `SessionNotCreatedException` extends `WebDriverException` and carries the remote end's explanation largely intact. The habit worth building is quoting that message when reporting the failure, because it already separates 'the endpoint refused this request' from 'the endpoint was not there' with no further investigation. The reason inside the message then routes the problem to whoever owns it — but that routing only becomes possible once the stage is settled. ## Habits that make this fast - Log the driver address and the session id at the start of every run; their presence or absence is the stage marker. - Never wrap construction in a blind retry: a stage-one failure repeats, and retrying only doubles the time to a red build. - Report startup failures distinctly from assertion failures, so nobody debugs a product that was never opened. - Keep a bare construction check that can be run on a host by itself, without the suite around it. - Capture the remote end's message into the run's evidence, not just the client's stack trace, since the client's frames are the same for every cause.

  • What does it tell you if the browser window appeared and then the constructor threw?
    That stage one is clean: the driver process was up, its port answered, and it got far enough to launch a browser. The failure is at or after the new-session reply, so the remote end's message is where the reason lives.
  • Why is a refused connection to a local driver address a different class of problem?
    Because nothing answered, so no session was ever requested. Either the driver process is not running, or it is not on the address the client expects. Nothing about the browser or the requested capabilities is implicated yet.
  • Why can a test not simply quit the driver when construction throws?
    The constructor never returned a reference, so there is no driver object to act on. Any cleanup has to be handled by the harness around construction, not by code holding a variable that was never assigned.

saying these in an interview costs you the question

  • Treats every constructor failure as one undifferentiated problem
  • Assumes a session-not-created error means nothing was listening
  • Retries construction blindly without reading the message thrown
  • Thinks a failed constructor still returns a usable driver object
  • Reads only the client stack trace, never the remote end's message