Skip to main content
Ladybird can run without any graphical window, making it straightforward to integrate into automated pipelines, regenerate test expectations, and inspect how the engine interprets a page without ever opening a display. Three headless output modes are available — plain text, layout tree dumps, and screenshot capture — and a dedicated test-web runner coordinates the full LibWeb test suite against all of them.

​
Headless Output Modes

Pass --headless with an output mode to load a page without opening the browser UI:

​
Screenshot Tests and —test-mode

Screenshot tests compare a rendered screenshot of a test page against a reference image. To generate a reference screenshot for a new test, run Ladybird in headless mode with --test-mode and point it at the test HTML file:
Ladybird will save the screenshot and log its location:
Move the file into the expected images directory:
Screenshot tests require a <link rel="match" href="../expected/my-test-ref.html" /> tag in the test HTML to tell the runner which reference page to compare against. The reference page itself is a simple <img> element pointing at the .png file generated above.

​
Running the Full Test Suite

The LibWeb test suite (Text, Layout, Ref, and Screenshot tests) is run by the test-web binary. The easiest way to invoke it is through ladybird.py:
You can also run all tests registered with CMake at once:

​
Rebaselining Text and Layout Tests

After changing behavior, regenerate expected output files with --rebaseline:

​
Running via ctest

For CI environments that call ctest directly:
Set LADYBIRD_SOURCE_DIR to the repository root if the tests require it:
To surface stdout/stderr from failing tests:

​
Use Cases

CI Automation

Run test-web in a pipeline to catch regressions on every commit. Text and Layout tests produce deterministic text output that is trivial to diff.

Screenshot Generation

Use --headless --test-mode to produce reference screenshots for new visual tests without needing a display server.

Layout Inspection

Use --headless=layout-tree to examine how Ladybird builds the layout tree for any HTML file during development.

​
Troubleshooting

​
Race condition on systems with llvmpipe

On UNIX systems where the llvmpipe software rasterizer is the active GPU driver — common in virtual machines — running --headless=text or --headless=layout-tree occasionally causes Ladybird to crash on exit with:
The likely cause is that atexit handlers are registered twice due to llvmpipe and fork/exec interaction issues when the WebContent process is spawned.
Pass --force-cpu-painting to work around the race condition:
This flag bypasses the GPU path entirely, preventing the double-registration of exit handlers triggered by llvmpipe.