Implementation:SeleniumHQ Selenium UrlChecker

Knowledge Sources	SeleniumHQ_Selenium
Domains	WebDriver, Infrastructure
Last Updated	2026-02-12 00:00 GMT

Overview

UrlChecker polls one or more URLs until they return HTTP 200 (available) or stop returning HTTP 200 (unavailable), with configurable timeout and exponential backoff.

Description

UrlChecker is a utility class in the org.openqa.selenium.net package that provides two polling methods: waitUntilAvailable and waitUntilUnavailable. It uses a cached thread pool of daemon threads to submit polling tasks that repeatedly open HTTP connections to the target URLs. The polling uses exponential backoff starting from 10ms up to a maximum of 320ms between attempts. Connections use a 500ms connect timeout and 1000ms read timeout. Response streams are fully consumed and closed to allow socket reuse. If the polling exceeds the specified timeout, a UrlChecker.TimeoutException is thrown.

Usage

Use UrlChecker to wait for Selenium Grid hub, node, or standalone server endpoints to become available before running tests, or to confirm that a server has fully shut down before cleanup. It is commonly used in server lifecycle management within Selenium infrastructure.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: java/src/org/openqa/selenium/net/UrlChecker.java

Signature

public class UrlChecker {

    static final int CONNECT_TIMEOUT_MS = 500;

    public void waitUntilAvailable(long timeout, TimeUnit unit, final URL... urls)
        throws TimeoutException

    public void waitUntilUnavailable(long timeout, TimeUnit unit, final URL url)
        throws TimeoutException

    public static class TimeoutException extends Exception {
        public TimeoutException(String s, Throwable throwable)
    }
}

Import

import org.openqa.selenium.net.UrlChecker;

I/O Contract

Method	Input	Output	Description
waitUntilAvailable(long timeout, TimeUnit unit, URL... urls)	timeout: max wait time; unit: time unit; urls: one or more URLs to poll	void (returns on success)	Polls all provided URLs with exponential backoff (10ms to 320ms). Returns as soon as any URL responds with HTTP 200. Throws UrlChecker.TimeoutException if none respond within the timeout.
waitUntilUnavailable(long timeout, TimeUnit unit, URL url)	timeout: max wait time; unit: time unit; url: URL to poll	void (returns on success)	Polls the URL with exponential backoff. Returns when the URL no longer responds with HTTP 200 (non-200 response or connection failure). Throws UrlChecker.TimeoutException if the URL remains available past the timeout.

Constant	Value	Description
CONNECT_TIMEOUT_MS	500	Connection timeout in milliseconds for each HTTP request
READ_TIMEOUT_MS (private)	1000	Read timeout in milliseconds for each HTTP request
MAX_POLL_INTERVAL_MS (private)	320	Maximum backoff interval between poll attempts
MIN_POLL_INTERVAL_MS (private)	10	Initial backoff interval between poll attempts

Usage Examples

import org.openqa.selenium.net.UrlChecker;
import java.net.URL;
import java.util.concurrent.TimeUnit;

UrlChecker checker = new UrlChecker();

// Wait for a Selenium Grid hub to become available
URL hubUrl = new URL("http://localhost:4444/wd/hub/status");
try {
    checker.waitUntilAvailable(30, TimeUnit.SECONDS, hubUrl);
    System.out.println("Hub is ready");
} catch (UrlChecker.TimeoutException e) {
    System.err.println("Hub did not start in time: " + e.getMessage());
}

// Wait for a server to shut down
try {
    checker.waitUntilUnavailable(10, TimeUnit.SECONDS, hubUrl);
    System.out.println("Hub has stopped");
} catch (UrlChecker.TimeoutException e) {
    System.err.println("Hub did not stop in time");
}

Related Pages

• Implementation:SeleniumHQ_Selenium_PortProber -- Port-level availability checking (lower level than URL checking)
• Implementation:SeleniumHQ_Selenium_NetworkUtils -- Network address resolution utility in the same package
• Implementation:SeleniumHQ_Selenium_Urls -- URL encoding and URI construction utilities in the same package