# How to Configure Headless Browser Execution for Chrome, Firefox, and Edge in Selenium

> Learn to configure headless browser execution for Chrome, Firefox & Edge in Selenium. Set HEADLESS=true in config.properties or override programmatically for effortless automation.

- Repository: [Anh Tester/automationframeworkselenium](https://github.com/anhtester/automationframeworkselenium)
- Tags: how-to-guide
- Published: 2026-02-24

---

**Set `HEADLESS=true` in `config.properties` or override `FrameworkConstants.HEADLESS` programmatically to enable headless mode for Chrome, Firefox, and Edge via the centralized `BrowserFactory`.**

The `anhtester/automationframeworkselenium` repository provides a centralized mechanism for configuring headless browser execution across multiple WebDriver instances. By leveraging the `BrowserFactory` class and global constants defined in `FrameworkConstants`, you can control headless behavior through external configuration files or runtime programmatic overrides without modifying core test logic.

## Understanding the Headless Configuration Architecture

The framework centralizes browser instantiation in **[`BrowserFactory.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/BrowserFactory.java)**, located at [`src/main/java/com/anhtester/driver/BrowserFactory.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/src/main/java/com/anhtester/driver/BrowserFactory.java). When creating driver instances, the factory checks the **`FrameworkConstants.HEADLESS`** flag to determine whether to append headless-specific arguments to the browser options.

The `HEADLESS` constant reads its value from the **`HEADLESS`** property key via `PropertiesHelpers.getValue("HEADLESS")`, as defined in [`src/main/java/com/anhtester/constants/FrameworkConstants.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/src/main/java/com/anhtester/constants/FrameworkConstants.java) (lines 20-23 and 47). During static initialization, `PropertiesHelpers.loadAllFiles()` aggregates properties from `config.properties`, `data.properties`, and CRM locators files into a single `Properties` object (see [`src/main/java/com/anhtester/helpers/PropertiesHelpers.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/src/main/java/com/anhtester/helpers/PropertiesHelpers.java), lines 25-31).

## Browser-Specific Headless Arguments

Each supported browser receives tailored headless arguments when the global flag is enabled:

### Chrome Headless Configuration

When `HEADLESS=true`, `BrowserFactory` appends the following arguments to `ChromeOptions` (lines 53-60):

- `--headless=new`
- `--no-sandbox`
- `--disable-dev-shm-usage`
- `--window-size=1920,1080`
- `--high-dpi-support=1`
- `--force-device-scale-factor=1`

### Edge Headless Configuration

Microsoft Edge inherits the same argument set as Chrome, applied in [`BrowserFactory.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/BrowserFactory.java) lines 91-98:

- `--headless=new`
- `--no-sandbox`
- `--disable-dev-shm-usage`
- `--window-size=1920,1080`
- `--high-dpi-support=1`
- `--force-device-scale-factor=1`

### Firefox Headless Configuration

Firefox uses Mozilla-specific arguments defined in lines 16-20 of [`BrowserFactory.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/BrowserFactory.java):

- `-headless`
- `--width=1920`
- `--height=1080`

### Safari Limitations

Safari does not support headless execution in this framework. Attempting to run Safari with `HEADLESS=true` throws a **`HeadlessNotSupportedException`** (see [`BrowserFactory.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/BrowserFactory.java), lines 35-37).

## Enabling Headless Mode via Configuration

### Using the Properties File

The simplest method involves editing `src/test/resources/config/config.properties`:

```properties

# src/test/resources/config/config.properties

HEADLESS = true

```

Set the value to `false` for visible browser execution. The framework reads this automatically during `DriverManager` initialization—no code recompilation required.

### Programmatic Override for CI/CD

For dynamic control in continuous integration pipelines, override the property before driver creation:

```java
import com.anhtester.constants.FrameworkConstants;
import com.anhtester.helpers.PropertiesHelpers;

// Override before DriverManager creates the driver
PropertiesHelpers.setValue("HEADLESS", "true");

// Subsequent DriverManager.getDriver() calls will use headless mode
WebDriver driver = DriverManager.getDriver();

```

## Manual Driver Creation Examples

While the factory handles most use cases, understanding the underlying configuration helps with custom implementations:

### Creating Headless Chrome Directly

```java
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
options.addArguments("--no-sandbox");
options.addArguments("--disable-dev-shm-usage");
options.addArguments("--window-size=1920,1080");
options.addArguments("--high-dpi-support=1");
options.addArguments("--force-device-scale-factor=1");

WebDriver driver = new ChromeDriver(options);
driver.get("https://example.com");

```

### Creating Headless Firefox Directly

```java
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.firefox.FirefoxOptions;

FirefoxOptions options = new FirefoxOptions();
options.addArguments("-headless");
options.addArguments("--width=1920");
options.addArguments("--height=1080");

WebDriver driver = new FirefoxDriver(options);
driver.get("https://example.com");

```

## Summary

- **Centralized control**: The `BrowserFactory` class manages headless arguments for all browser instances.
- **Configuration-driven**: Set `HEADLESS=true` in `src/test/resources/config/config.properties` to enable headless mode globally.
- **Browser coverage**: Chrome, Edge, and Firefox support headless execution with optimized window sizing arguments; Safari explicitly throws `HeadlessNotSupportedException`.
- **Runtime flexibility**: Use `PropertiesHelpers.setValue("HEADLESS", "true")` to override settings programmatically for CI/CD environments.

## Frequently Asked Questions

### How do I enable headless mode in the framework?

Edit the `HEADLESS` property in `src/test/resources/config/config.properties` and set it to `true`. The `BrowserFactory` automatically detects this value via `FrameworkConstants.HEADLESS` and applies the appropriate browser-specific arguments when creating WebDriver instances.

### What headless arguments does Chrome use in this framework?

According to [`BrowserFactory.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/BrowserFactory.java) (lines 53-60), Chrome receives `--headless=new`, `--no-sandbox`, `--disable-dev-shm-usage`, `--window-size=1920,1080`, `--high-dpi-support=1`, and `--force-device-scale-factor=1`. Edge inherits this identical argument set.

### Can I run Safari in headless mode with this framework?

No. The `BrowserFactory` explicitly throws a `HeadlessNotSupportedException` when attempting to instantiate Safari with headless mode enabled (lines 35-37). Safari does not support standard headless WebDriver execution in this implementation.

### How do I override headless settings for specific test runs?

Call `PropertiesHelpers.setValue("HEADLESS", "true")` (or `"false"`) before invoking `DriverManager.getDriver()`. This programmatic override takes precedence over the configuration file and is particularly useful for Jenkins pipelines or Docker containers where you need dynamic browser visibility control.