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

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, located at 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 (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, 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 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:

• -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, lines 35-37).

Enabling Headless Mode via Configuration

Using the Properties File

The simplest method involves editing src/test/resources/config/config.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:

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

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

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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}