This guide shows you how to capture screenshots using Selenium Grid with headless Chrome, a setup that lets you run browser tests in parallel across multiple machines without a visible UI. You’ll learn the exact configuration, code, and commands to take full-page or element-specific screenshots, plus how to handle common pitfalls.
What You’ll Need
- Java 8 or later (for Selenium Grid) – download from a trusted source if not installed.
- Selenium Server (Grid) JAR file – the standalone JAR includes both hub and node.
- Chrome browser and ChromeDriver – versions must match your Chrome version.
- A programming language with Selenium bindings (Python, Java, C#, etc.) – examples here use Python.
- Basic familiarity with running commands in a terminal.
Step-by-Step
- Download and verify ChromeDriver
Go to the Chrome for Testing website, download the ChromeDriver that matches your installed Chrome version, and place it in a known directory. On Linux/macOS, make it executable withchmod +x chromedriver. - Start the Selenium Grid hub
Open a terminal and run:java -jar selenium-server-4.27.0.jar hub
This starts the hub on port 4444 by default. You should see a message like “Selenium Grid hub is up and running”. - Start a Grid node with Chrome
In another terminal, run:java -jar selenium-server-4.27.0.jar node --detect-drivers --hub http://localhost:4444
This registers a node that can run Chrome, Edge, and Firefox. To force headless mode, add--driver-implementation chromeand set the environment variableSE_OPTSif needed, but we’ll handle headless via code. - Verify the Grid is up
Openhttp://localhost:4444in your browser. You should see the Grid console with your node listed as available. - Write your test script
Create a Python file (e.g.,screenshot.py) with the following code:from selenium import webdriver from selenium.webdriver.chrome.options import Options options = Options() options.add_argument("--headless") options.add_argument("--window-size=1920,1080") driver = webdriver.Remote( command_executor="http://localhost:4444", options=options ) driver.get("https://example.com") driver.save_screenshot("homepage.png") driver.quit() - Run the script
Executepython screenshot.py. If successful, you’ll see ahomepage.pngfile in the same directory. - Capture full-page screenshots (optional)
By default,save_screenshotcaptures only the viewport. To get the full page, use:from selenium.webdriver.common.by import By element = driver.find_element(By.TAG_NAME, "body") element.screenshot("fullpage.png")Or use a helper like
driver.execute_script("return document.body.scrollHeight")to resize the window. - Clean up
Always calldriver.quit()to release the session. In a real test suite, use afinallyblock or context manager.
Common Mistakes
- Version mismatch between Chrome and ChromeDriver – causes “session not created” errors. Always match them exactly.
- Not setting headless mode – if you omit
--headless, the node will try to open a visible browser, which may fail on servers without a display. - Forgetting to start the node – the hub alone cannot run tests; you need at least one node.
- Using the wrong URL for the hub – the node must point to the hub’s address, and your script must point to the hub’s /wd/hub endpoint (Selenium 4 uses the root).
- Not waiting for page load – screenshots taken before the page finishes loading will be blank or partial. Use explicit waits.
Tips
- Use
--window-size=1920,1080to ensure consistent viewport dimensions across all nodes. - For parallel screenshots, start multiple nodes on different ports (e.g.,
--port 5555) and register them all to the same hub. - In CI/CD, run the hub and node as Docker containers using the official Selenium images to avoid local setup issues.
- Use
driver.get_screenshot_as_png()to get the image as bytes, which is useful for embedding in reports. - Always set a reasonable timeout for the remote connection, e.g.,
options.page_load_strategy = 'eager'for faster loading.
Troubleshooting
- “Could not start a new session” error – Check the Grid console for node status. If the node is not registered, restart it. Also verify ChromeDriver is in PATH or specify its location via
--driver-config. - Blank or white screenshot – The page may not have finished rendering. Add an explicit wait for an element or use
time.sleep(2)as a quick fix. - Chrome crashes on the node – Ensure the node has enough memory and that Chrome is allowed to run as root (add
--no-sandboxto options if needed). - Port 4444 already in use – Kill the existing process or use
--port 4445for the hub, and update your script accordingly. - Node shows “unavailable” – The node may have crashed. Check the node’s terminal logs for stack traces, often related to missing browser binaries.
Frequently Asked Questions
Do I need a separate node for headless Chrome?
No, the same node can run both headless and headed Chrome. You just need to pass the --headless argument in your test script.
Can I take screenshots of a specific element?
Yes, use element.screenshot("filename.png") after locating the element with find_element.
How do I capture a full-page screenshot?
Set the window size to the full page height using driver.set_window_size() after loading the page, or use a library like Selenium’s built-in save_screenshot with a large window size.
What if my Chrome version is different on each node?
Use the same Chrome and ChromeDriver version on all nodes. Alternatively, use Selenium Manager (included in Selenium 4.6+) to auto-download the correct driver.
Can I run this on a CI server without a display?
Yes, headless mode is designed for that. Just ensure the node has no X server required; headless Chrome runs without one.
Is there a way to capture screenshots in parallel?
Yes, start multiple nodes and use a test framework like pytest-xdist or Selenium Grid’s built-in parallelism to distribute tests.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- Spotify Jam Not Working on Mobile? Fixes That Work
- Windows 10 No Internet Secured WiFi Error Fix
- Multi-Cloud GPU Failover Design Guide
- Error Code Currant Destiny? Meaning & Fixes
- AirPlay with Roku Multi-Device Setup: A How-To
- How to Set a Timer on iPhone (iOS 18 & 17)