Workaround to record video in Selenium headless mode, including when using Selenium Gri

[testervippro]

How to Record Video in Selenium Headless Mode (Works with Selenium Grid)

By default, when using:

options.addArguments("--headless=new");

in Selenium—especially with Selenium Grid—you may get a completely black video. This happens because Chrome in headless mode doesn’t render a visible UI for the screen recorder to capture.

---

Workaround I Found (Tested)

Although it’s not the perfect solution, here’s a working approach:

1. Run Chrome in remote debugging mode
2. Start a desktop app in the background that continuously captures screenshots
3. After the test run, convert the captured images into a video

---

Key Details

• The test duration and screen recording duration must match
  Example: If the test runs for 10 seconds → record ~10 seconds of screenshots
• You should aim to capture around 250 screenshots in 10 seconds
• Convert them into a video(use ffmpeg) at 25 frames per second

---

Demo Available

You can try a working example in this GitHub repository:
https://github.com/testervippro/selenium-headless-mode-demo

Other frameworks like Cypress and Playwright already make it much easier to record videos, even in headless mode. It would be great to see Selenium catch up in this area.

[diemol]

What is the point of running a headless browser inside a container?

[testervippro]

Actually, I still use the image standalone-chrome:4.34.0-20250707 and simply add the screencastlinuxv2 app to run in the background.
This helps capture every frame using Chrome's debug mode in port 9222
Then after test finish ,i will convert it to videos
I'm just curious and want to use a headless browser.

Dockerfile

FROM selenium/standalone-chrome:4.34.0-20250707

# Set working directory for app scripts
WORKDIR /usr/src/app

# Copy screencast binary with execution permission
COPY --chmod=755 screencastlinuxv2 /usr/src/app/screencastlinuxv2

[VietND96]

I took a few minutes to read through. I guess people come to headless browser for a few reasons, like run faster, less resource consumption, web scraping, etc (top Google results mentioned this). However, come to the solution is taking screenshot continuously and cast to a video (might it impact above benefits?).
Come to the initial demo, thanks for your initiative. However, to me, it is still complex since it requires many steps from client code to tooling.

• Key things is CDP and debug port enabled. Let's say expose container port 9222, then script controller app.js, binary screencast can run on host and be controlled in part of test fixtures. No need extra Dockerfile to copy banary screencast to container and start app.js on host, also need consider host is using which OS to run particular shell script. But I know this is not easy, since it requires FFmpeg, which also needs to install on host, so reasonable that you let it reuse FFmpeg in browser node.
• If come to containerization principle, better is consider to wrap everything and make everything is ready to use. So, from client code, user just add browser args to enable debug port, and the rest of works (app.js, binary running in container, trigger if dedicated port is open, similar way current video recording works) and then mount container volume to get output files on host.

[VietND96]

Btw, sometime before I also tried to evaluate the popularity of "video recording in browser headless", there were many people also curious, few tutorials there but might not be up-to-date, Selenide also applied this screencast approach (selenide/selenide#2145).
I also would like to use containerization to solve this. However, to bring it here, need to consider that the solution is simple, maintainable, extendable (for someone who wants to customize their own), and independent (easy to remove once it's no longer supported).

[diemol]

Where can I see performance metrics that prove headless uses less resources?

Also, the containers can record video already. Why not using a regular browser?

[testervippro]

Thanks, @VietND96 — that's correct. The key point is CDP, and it seems Playwright and Cypress also use it.
I also agree with you: every solution should be simple, maintainable, extendable,Customers shouldn't need to configure too much.

[OnlineProxy-io]

When you're using Selenium in headless mode and try to record the screen, you’ll probably just get a big ol’ black screen. That’s because headless browsers don’t actually render the UI - they skip all the visual stuff to run faster. So yeah, there's nothing for your recording software to see. Chrome in headless mode is all about speed, not looks. It skips hardware acceleration and leaves out a bunch of graphical elements, which totally messes with screen recording. On the flip side, tools like Playwright and Cypress were built with this in mind - they’ve got video capture baked right in, even in headless mode. Selenium leans on external tools like FFmpeg to handle recording, which means setting it all up is a bit more work and can get pretty messy, especially in headless mode.

[diemol]

Of course, you don't get anything if it is headless. I mean running the regular headed browser inside a container. @OnlineProxy-io do you have any metrics showing how much faster headless browsers are?

Also, please check how Playwright and Cypress do it. You will find ffmpeg in their dependencies as well (hard to notice when downloading over 300 MB). They also use it and that is why many users avoid video recording because there is a performance hit.

[VietND96]

You can inspect FFmpeg dependency and handle in Playwright via https://github.com/microsoft/playwright/blob/main/packages/playwright-chromium/install.js, https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/videoRecorder.ts
You will see it is similar the way docker selenium record headed browser, just different on input stream, they are image2pipe and we are VNC X11 streaming
As above comments, the key point is CDP, approach to cast screenshot to video, and script controller to do those complex tasks in the background to deliver a pretty feature to end users