Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ladybirdBrowser/ladybird/llms.txt

Use this file to discover all available pages before exploring further.

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:
FlagOutput
--headless=textSerialized plain-text representation of the page
--headless=layout-treeDump of the internal layout tree
--headless + --test-modeScreenshot capture used for Screenshot tests
# Dump text output for a local file
./Meta/ladybird.py run ladybird --headless=text file:///path/to/page.html

# Dump the layout tree
./Meta/ladybird.py run ladybird --headless=layout-tree file:///path/to/page.html

​
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: 
./Meta/ladybird.py run ladybird --headless --test-mode Tests/LibWeb/Screenshot/input/your-test.html
Ladybird will save the screenshot and log its location: 
Saved screenshot to: ~/Downloads/screenshot-2025-06-07-08-37-45.png
Move the file into the expected images directory: 
mv ~/Downloads/screenshot-2025-06-07-08-37-45.png Tests/LibWeb/Screenshot/images/your-new-test-name.png
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: 
./Meta/ladybird.py run test-web
You can also run all tests registered with CMake at once: 
./Meta/ladybird.py test
# or just the LibWeb tests:
./Meta/ladybird.py test LibWeb

​
Rebaselining Text and Layout Tests

After changing behavior, regenerate expected output files with --rebaseline: 
./Meta/ladybird.py run test-web --rebaseline -f Text/input/your-new-test-name.html

​
Running via ctest

For CI environments that call ctest directly: 
cmake --preset Release
cmake --build --preset Release
ctest --preset Release
Set LADYBIRD_SOURCE_DIR to the repository root if the tests require it: 
export LADYBIRD_SOURCE_DIR=${PWD}
To surface stdout/stderr from failing tests: 
CTEST_OUTPUT_ON_FAILURE=1 ninja -C Build/release test

​
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:
double free or corruption (!prev)
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:
./Meta/ladybird.py run ladybird --headless=text --force-cpu-painting file:///path/to/page.html
This flag bypasses the GPU path entirely, preventing the double-registration of exit handlers triggered by llvmpipe.

Build docs developers (and LLMs) love

Get started for freeTalk to us