How to Run Selenide with Headless Chrome
Run Selenide tests with headless Chrome using its built-in setting or ChromeOptions. Configure CI, fix common startup errors, and keep browser runs reproducible.

Set Configuration.headless = true before Selenide opens its first browser. For a basic Chrome test, also set Configuration.browser = "chrome" and a fixed Configuration.browserSize. You usually do not need to construct Chrome options just to enable headless mode. Use Selenium’s ChromeOptions when you need a Chrome-specific flag such as --headless=new, a preference, an extension, or a nonstandard browser configuration.
Headless Chrome runs without displaying a browser window, but it still launches Chrome and executes the page. Your test code can continue to use Selenide’s regular APIs. For stable CI runs, make the viewport explicit, ensure Chrome and ChromeDriver are installed with compatible major versions, and configure all settings before the first browser session.
1. Use Selenide’s built-in headless setting
Selenide exposes headless mode as a boolean configuration option. Its documented default is false; the setting is documented for Chrome 59+ and Firefox 56+. For Chrome, set the browser name as well so the intended browser is unambiguous. The official [Selenide Configuration API](https://selenide.org/javadoc/current/com/codeborne/selenide/Configuration.html) documents the headless setting and related configuration values.
Here is a minimal JUnit-style test class. The static initializer runs before the test method opens a browser:
import com.codeborne.selenide.Configuration;
import org.junit.jupiter.api.Test;
import static com.codeborne.selenide.Selenide.$;
import static com.codeborne.selenide.Selenide.open;
import static com.codeborne.selenide.Condition.visible;
class LoginTest {
static {
Configuration.headless = true;
Configuration.browser = "chrome";
Configuration.browserSize = "1366x768";
}
@Test
void pageLoads() {
open("https://example.test");
$("h1").shouldBe(visible);
}
}
Replace the example URL and assertion with the page and behavior your test covers. The important ordering is that configuration happens before open() or any other operation that starts a browser.
Set it for a single Maven run
System properties are convenient for CI jobs because the same compiled test code can run in different modes:
mvn test \
-Dselenide.headless=true \
-Dselenide.browser=chrome \
-Dselenide.browserSize=1366x768
Set it for the project
For a project-wide default, create or update src/test/resources/selenide.properties:
selenide.headless=true
selenide.browser=chrome
selenide.browserSize=1366x768
Use one clear source for each setting where possible. When troubleshooting, check that a system property, properties file, and programmatic assignment are not giving you conflicting values. Also note that assigning Configuration.browserCapabilities can override values supplied through system properties, as described in the Selenide configuration API.
2. Use ChromeOptions for Chrome-specific flags
Choose ChromeOptions when you need to pass explicit Chrome arguments or configure browser-specific capabilities. Selenium’s Chrome documentation lists --headless=new as a common argument. Its browser options documentation says Selenium 4 uses browser-specific Options classes to configure capabilities. See [Selenium’s Chrome documentation](https://www.selenium.dev/documentation/webdriver/browsers/chrome/) and [Browser Options documentation](https://www.selenium.dev/documentation/webdriver/drivers/options/).
import com.codeborne.selenide.Configuration;
import org.openqa.selenium.chrome.ChromeOptions;
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
options.addArguments("--window-size=1366,768");
Configuration.browser = "chrome";
Configuration.browserCapabilities = options;
Configuration.browserSize = "1366x768";
Assign the options object directly to Configuration.browserCapabilities. This is the supported Selenide pattern shown in its release notes; older examples that wrap options in DesiredCapabilities should be updated to use the browser Options class directly.
Do not add Chrome flags just because a test runs in CI. Start with Selenide’s headless setting. If a specific environment needs a browser argument, add that argument deliberately and keep the options in one place. Multiple sources of browser configuration can make it difficult to tell which setting produced a session.
3. Configure headless Chrome in CI or a container
A reliable starting configuration has four parts:
- Enable headless mode with
Configuration.headlessorselenide.headless=true. - Set
browserSizeexplicitly so layout and responsive behavior use a predictable viewport. - Make sure the Chrome executable is present and accessible to the job.
- Use a ChromeDriver whose major version matches Chrome’s major version.
The right configuration depends on the runner image. There is no single extra Docker flag set established by the sources cited here, so add runtime-specific arguments only when your image requires them and you can identify the failure they address.
Choose a nonstandard Chrome binary
If Chrome is installed outside the standard location, set the binary path before the browser starts:
Configuration.browserBinary = "/opt/google/chrome/chrome";
You can also set it as a system property:
mvn test -Dselenide.browserBinary=/opt/google/chrome/chrome
Use the actual executable path in your build image. The Selenide API documents browserBinary for Chrome and Firefox.
Run on a remote WebDriver
If the machine running the test does not have a local browser, point Selenide at a remote WebDriver endpoint. For example:
mvn test \
-Dselenide.remote=http://localhost:4444/wd/hub \
-Dselenide.headless=true \
-Dselenide.browser=chrome \
-Dselenide.browserSize=1366x768
The endpoint must be reachable by the test process and configured to provide Chrome. Selenide’s remote setting supports Selenium Grid-style execution; its [FAQ](https://selenide.org/faq.html) also shows a hosted WebDriver endpoint example. When using a remote browser, check which side owns the browser installation and capabilities: the remote node starts Chrome, while your test sends configuration through WebDriver.
4. Make runs reproducible and diagnosable
Headless mode removes the visible browser window; it does not remove the sources of browser startup or page-rendering variation. Use a fixed viewport for screenshot or layout assertions. Keep Chrome and ChromeDriver versions aligned and inspect both versions when a session fails to start. Keep the binary path and capabilities explicit when the standard environment is not available.
| Need | Configuration to use | Why |
|---|---|---|
| Run Chrome without a visible window | Configuration.headless = true |
Selenide’s direct headless switch. |
Pass --headless=new or another Chrome argument |
ChromeOptions assigned to Configuration.browserCapabilities |
Chrome-specific browser configuration. |
| Use a fixed layout viewport | Configuration.browserSize = "1366x768" |
Reduces viewport-driven layout differences. |
| Chrome is installed at a custom path | Configuration.browserBinary |
Points Selenide at the executable to launch. |
| Use a browser on another host | Configuration.remote |
Connects the test to a remote WebDriver endpoint. |
5. Troubleshoot common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| A Chrome window appears | Headless mode was not set, was set too late, or a later capability configuration superseded it. | Set Configuration.headless = true before the first browser operation. Inspect selenide.properties, system properties, and browserCapabilities for conflicting configuration. |
SessionNotCreatedException at startup |
Chrome and ChromeDriver may have incompatible major versions, or Chrome may not start in the environment. | Inspect the installed Chrome and ChromeDriver versions and align their major versions. Confirm the binary exists and is executable. Selenium’s Chrome guidance says the browser and driver major versions must match. |
| Chrome cannot be found | The runner image does not install Chrome in the expected location. | Install Chrome in the image or set Configuration.browserBinary / -Dselenide.browserBinary=/path/to/chrome to the real executable. |
| Tests use the wrong viewport | No explicit size was configured or a capability setting changed it. | Set Configuration.browserSize or selenide.browserSize and check the effective browser capabilities. |
| Local run works but remote run fails | The endpoint is unreachable, the remote node lacks Chrome, or the requested capabilities are not accepted there. | Verify endpoint reachability, browser availability on the node, and the capabilities supported by that endpoint. Set Configuration.remote deliberately. |
| A custom flag appears to have no effect | Options were built but never assigned, or a different configuration source creates the session. | Assign the ChromeOptions instance to Configuration.browserCapabilities before opening the browser. Keep browser capability setup together. |
For version-related errors, Selenium’s Chrome documentation states that Selenium 4 is compatible with Chrome 75 and later and that the Chrome and ChromeDriver major versions must match. Treat this as a startup prerequisite; it does not guarantee that every runner image or browser combination is otherwise configured correctly. See [Selenium’s Chrome documentation](https://www.selenium.dev/documentation/webdriver/browsers/chrome/).
6. Performance, reliability, and cost considerations
Headless mode changes how Chrome is displayed, not what kind of test you are running. Browser automation still depends on launching a compatible browser, loading the page, and waiting for the behavior under test. A remote endpoint adds a network and service dependency; it can centralize browsers but should be included in failure diagnosis.
- Stabilize layout: set a fixed viewport when assertions depend on page layout.
- Stabilize startup: pin or otherwise control the browser and driver versions in the CI image, and confirm the binary path.
- Keep configuration explainable: set capabilities in one place and avoid accidental overrides between properties, system properties, and Java assignments.
- Plan CI resources: Chrome is still a running browser process in headless mode, so account for browser processes and the pages your tests load when sizing parallel jobs.
The research sources provide no universal runtime benchmark or fixed resource requirement for headless Selenide tests. Measure the workload in the runner you use rather than treating headless mode as a guaranteed speedup. Selenide, Selenium, Chrome, and any remote WebDriver service may also have separate licensing or hosting terms; check the terms relevant to your deployment.
7. Or skip the browser setup
If the task is to capture a website image or PDF rather than exercise browser interactions, ScreenshotNeo offers a one-request screenshot API. ScreenshotNeo is a website screenshot API and MCP server for developers by [Yorker Media](https://screenshotneo.com). See the [ScreenshotNeo API documentation](https://screenshotneo.com/docs/) for request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webp
The same endpoint can be called from Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)
Or Node.js:
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
- Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents. - The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
8. Frequently asked questions
Does Selenide support headless Firefox too?
The documented Selenide headless setting applies to Chrome 59+ and Firefox 56+. This guide focuses on Chrome-specific options and setup.
Should I set both Configuration.headless and --headless=new?
Start with Selenide’s built-in setting. Add the Chrome argument through ChromeOptions when you specifically need that browser flag or other Chrome-specific configuration.
Can headless tests use the same Selenide page interactions?
Yes. Headless mode controls browser display. Tests still use Selenide’s normal browser automation calls, such as open() and element assertions.
When should I use a screenshot API instead of Selenide?
Use Selenide when you need browser-driven test interactions and assertions. For a standalone website screenshot or PDF, a screenshot API can avoid managing a browser and driver in your test environment.


