Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / tests / web_test / worker_modes.lucb

#==============================================================================================
#
#   worker_modes - one test in the worker: the Layout, Ref and Crash modes
#
#   DESCRIPTION:
#       What test-web does with a test once the page is loaded (Tests/LibWeb/test-web/main.cpp
#       run_dump_test, run_ref_test), natively:
#
#       Layout: afterFontsAndPaint, a screenshot ("to force the lazy layout of SVG-as-image
#       documents"), then the page's internal info for LayoutTree | PaintTree |
#       StackingContextTree (Services/WebContent/ConnectionFromClient.cpp
#       request_internal_page_info: append_layout_tree, append_paint_tree,
#       append_stacking_context_tree, joined by a newline). Each part is written as soon as it
#       is made, so a worker that traps on the way leaves the parts it finished.
#
#       --no-rendering is a diagnostic for the driver's second try at a Layout test that did not
#       get to its dumps: the page is one that is never rendered, as Ladybird's pages of
#       SVG-as-image documents are (its client answers is_svg_page_client, so its navigables
#       have no backing stores or rendering thread and "update the rendering" skips its
#       documents), and it stays hidden; document.fonts.ready and the animation frames are not
#       awaited, and the dumps are taken as soon as the document has loaded:
#       Document::update_layout lays it out and LayoutState::commit makes its paintables, but
#       nothing is painted. It tells whether the layout is right while painting is not ported;
#       it is not the test.
#
#       Ref: afterFontsAndPaint and a screenshot of the test; its reference metadata
#       (Libraries/LibWeb/Internals/Internals.cpp load_reference_test_metadata: the
#       `<link rel=match|mismatch>` references and `<meta name=fuzzy>` configurations); the
#       first reference loaded into the same page, waited for and taken a screenshot of; the
#       two compared (fuzzy.lucb). The result is a line "pass" or "fail"; a failed comparison
#       writes its images (worker_screenshot). A reference that is an image is decoded and
#       compared as it is (worker_screenshot).
#
#       Screenshot: worker_screenshot.
#
#       A test or reference is loaded as the type its file name says (worker_load): HTML, or
#       XML (.svg, .xht, .xhtml, .xml); another type (PDF) traps `unported`, naming it.
#
#       Crash: afterFontsAndPaint; the result is "pass" (a test fails only by not getting
#       there: a trap, a signal or the driver's timeout).
#
#       Copyright (c) 2024-2026, the Ladybird developers.
#       Copyright (c) 2026 the luce-browser authors.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: The result ==============================================================================

## Where the worker writes its result: the --out file, or standard output.
struct WorkerOutput:
    var file: files.File?

    ## Writes `text` (all of it).
    func put(text: str):
        var bytes = text.bytes
        while bytes.length > 0:
            var written: usize = 0
            if self.file != none:
                var file = self.file else trap("unreachable")
                written = file.write(bytes) catch failure: trap("web_test: cannot write the result")
            else:
                written = io.stdout().write(bytes) catch failure: trap("web_test: cannot write the result")
            bytes = bytes[written..]

## The output of `path` (replaced), or standard output without one.
func worker_open_output(path: str?) -> WorkerOutput:
    if let output_path = path:
        let file = files.File.open(c_path(output_path), files.OpenMode.replace) catch failure: trap("web_test: cannot open the result file")
        return WorkerOutput(file = file)
    return WorkerOutput(file = none)

## Writes the text of `builder` and empties it.
func worker_put_builder(output: WorkerOutput*, builder: ak.StringBuilder*):
    let view = ak.string_builder_string_view(builder)
    output.put(ak.string_view_text(view))
    ak.string_builder_clear(builder)

# mark: Reading tests ===========================================================================

## The absolute form of `path` (test-web loads tests by their real path).
func worker_absolute_path(path: str) -> str:
    if strings.starts_with(path, "/"):
        return path
    let directory = os.cwd() catch failure: trap("web_test: no working directory")
    let pieces: str[3] = [directory, "/", path]
    return strings.join(pieces, "") catch failure: trap("out of memory")

## The Screenshot expectation of the test at `path` under the test root `root`:
## ROOT/Screenshot/input/T/N.html's is ROOT/Screenshot/expected/T/N.png (driver_collect).
func worker_screenshot_expectation_path(root: str, path: str) -> str:
    let prefix = cat([root, "/Screenshot/input/"])
    if not strings.starts_with(path, prefix):
        trap(f"web_test: a Screenshot test is not under {prefix}: {path}")
    let trail = (str)path.bytes[prefix.length..]
    return cat([root, "/Screenshot/expected/", path_title(trail), ".png"])

## The bytes of the file `path`, never released: the page loaded from them may keep them, and a
## worker exits after its test.
func worker_read_file(path: str) -> const u8[]:
    let data = files.read(c_path(path)) catch failure: trap(f"web_test: cannot read {path}")
    return data.value

# mark: The page's internal info ================================================================

## The active document of the page's top-level browsing context.
func worker_active_document(page: const WorkerPage*) -> web.DomDocument*?:
    return web.html_browsing_context_active_document(web.page_top_level_browsing_context(page.page))

## append_layout_tree (WebContent/ConnectionFromClient.cpp).
func worker_append_layout_tree(page: const WorkerPage*, builder: ak.StringBuilder*):
    if let document = worker_active_document(page):
        web.dom_document_update_layout(document, web.DomUpdateLayoutReason.debugging)
        if let layout_root = web.dom_document_layout_node(document):
            web.dump_tree_string_builder_layout_node(builder, (web.LayoutNode*)layout_root)
        else:
            ak.string_builder_append(builder, "(no layout tree)")
    else:
        ak.string_builder_append(builder, "(no DOM tree)")

## append_paint_tree (WebContent/ConnectionFromClient.cpp).
func worker_append_paint_tree(page: const WorkerPage*, builder: ak.StringBuilder*):
    if let document = worker_active_document(page):
        web.dom_document_update_layout(document, web.DomUpdateLayoutReason.debugging)
        if let layout_root = web.dom_document_layout_node(document):
            if let first_paintable = web.layout_node_first_paintable((web.LayoutNode*)layout_root):
                web.dump_tree_string_builder_paint_paintable(builder, first_paintable)
            else:
                ak.string_builder_append(builder, "(no paint tree)")
        else:
            ak.string_builder_append(builder, "(no layout tree)")
    else:
        ak.string_builder_append(builder, "(no DOM tree)")

## append_stacking_context_tree (WebContent/ConnectionFromClient.cpp).
func worker_append_stacking_context_tree(page: const WorkerPage*, builder: ak.StringBuilder*):
    if let document = worker_active_document(page):
        web.dom_document_update_layout(document, web.DomUpdateLayoutReason.debugging)
        if let layout_root = web.dom_document_layout_node(document):
            if web.layout_node_first_paintable((web.LayoutNode*)layout_root) == none:
                ak.string_builder_append(builder, "(no paint tree)")
                return
            let paintable_box = web.layout_box_paintable_box((web.LayoutBox*)layout_root) else trap("VERIFY: the viewport has a paintable box")
            let viewport_paintable = web.as_paint_viewport_paintable(paintable_box)
            web.paint_viewport_paintable_build_stacking_context_tree_if_needed(viewport_paintable)
            if let stacking_context = web.paint_paintable_box_stacking_context((web.PaintPaintableBox*)viewport_paintable):
                web.paint_stacking_context_dump(stacking_context, builder)
        else:
            ak.string_builder_append(builder, "(no layout tree)")
    else:
        ak.string_builder_append(builder, "(no DOM tree)")

# mark: The modes ===============================================================================

## The Layout mode: the dumps of the loaded page (see the header).
func worker_run_layout(page: const WorkerPage*, event_loop: WorkerEventLoop*, document: web.DomDocument*, output: WorkerOutput*, rendering: bool):
    if rendering:
        worker_after_fonts_and_paint(page, event_loop, document)
        _ = worker_take_screenshot(page, event_loop)

    var builder = ak.string_builder_new()
    worker_append_layout_tree(page, &builder)
    worker_put_builder(output, &builder)
    worker_stage("layout-tree")
    ak.string_builder_append(&builder, "\n")
    worker_append_paint_tree(page, &builder)
    worker_put_builder(output, &builder)
    worker_stage("paint-tree")
    ak.string_builder_append(&builder, "\n")
    worker_append_stacking_context_tree(page, &builder)
    worker_put_builder(output, &builder)
    worker_stage("stacking-context-tree")

## The match or mismatch references and fuzzy configurations of a reftest
## (Internals::load_reference_test_metadata).
struct WorkerReferenceMetadata:
    var match_references: ak.Vector[web_url.Url]
    var mismatch_references: ak.Vector[web_url.Url]
    var fuzzy: ak.Vector[FuzzyMatch]

## The URLs of the `link[rel=type]` elements' hrefs (load_reference_test_metadata's
## collect_references).
func worker_collect_references(document: web.DomDocument*, selector: str) -> ak.Vector[web_url.Url]:
    var references: ak.Vector[web_url.Url]
    let reference_nodes = web.dom_parent_node_query_selector_all((web.DomParentNode*)document, ak.sv(selector)) else trap("MUST: query_selector_all")
    for i in 0..<web.dom_node_list_length(reference_nodes):
        let reference_node = web.dom_node_list_item(reference_nodes, i) else continue
        let href = web.dom_element_get_attribute_value(web.as_dom_element(reference_node), web.html_attribute_names_href)
        let href_view = ak.string_bytes_as_string_view(&href)
        let url = web.dom_document_encoding_parse_url(document, href_view) else trap(f"web_test: Failed to construct URL for '{ak.string_view_text(href_view)}'")
        ak.vector_append_t(&references, url)
    return references

## Internals::load_reference_test_metadata of the page's active document.
func worker_load_reference_test_metadata(page: const WorkerPage*) -> WorkerReferenceMetadata:
    let document = worker_active_document(page) else trap("web_test: No active document available")
    var metadata = WorkerReferenceMetadata(match_references = worker_collect_references(document, "link[rel=match]"),
                                           mismatch_references = worker_collect_references(document, "link[rel=mismatch]"))

    # Collect all <meta name="fuzzy" content=".."> values.
    let fuzzy_nodes = web.dom_parent_node_query_selector_all((web.DomParentNode*)document, ak.sv("meta[name=fuzzy]")) else trap("MUST: query_selector_all")
    for i in 0..<web.dom_node_list_length(fuzzy_nodes):
        let fuzzy_node = web.dom_node_list_item(fuzzy_nodes, i) else continue
        let content_string = web.dom_element_get_attribute_value(web.as_dom_element(fuzzy_node), web.html_attribute_names_content)
        var content = ak.string_view_text(ak.string_bytes_as_string_view(&content_string))
        var reference: web_url.Url? = none
        if let parts = strings.split_once(content, ":"):
            reference = web.dom_document_encoding_parse_url(document, ak.sv(parts.0))
            content = parts.1
        # test-web's on_reference_test_metadata: a configuration that does not parse is skipped.
        let fuzzy_match = parse_fuzzy_match(reference, content) catch failure:
            io.stderr().write(f"Failed to parse fuzzy configuration '{content}': {failure.message}\n") catch ignored: continue
            continue
        ak.vector_append_t(&metadata.fuzzy, fuzzy_match)
    return metadata

## Loads the file of `url` into the page and waits for it as test-web waits for a test.
func worker_load_and_wait(page: const WorkerPage*, event_loop: WorkerEventLoop*, vm: web.Vm*, url: web_url.Url) -> web.DomDocument*:
    # test-web navigates the view to the reference, and the event loop turns while the navigation runs, so an update
    # of the rendering the frame timer queued for the previous document (a running CSS animation requests a frame
    # on every one) runs while that document is still active. worker_load_document replaces the active document at
    # once: run such a task first, or it would stay queued and not runnable, and EventLoop's "a rendering task is
    # already queued" optimization would never queue another one.
    let task_queue = web.html_event_loop_task_queue(web.html_main_thread_event_loop())
    while web.html_task_queue_has_rendering_tasks(task_queue):
        _ = event_loop.pump(web.CoreEventLoopPumpMode.wait_for_events)

    let path_string = web_url.url_file_path(&url)
    let path = ak.string_view_text(ak.byte_string_view(&path_string))
    let bytes = worker_read_file(path)
    let document = worker_load_document(page, vm, url, bytes)
    worker_wait_for_load(page, event_loop, &url)
    return document

## The Ref mode (see the header): writes "pass" or "fail".
func worker_run_ref(page: const WorkerPage*, event_loop: WorkerEventLoop*, vm: web.Vm*, url: web_url.Url, document: web.DomDocument*, images: str?,
                    output: WorkerOutput*):
    worker_after_fonts_and_paint(page, event_loop, document)
    let actual = worker_take_screenshot(page, event_loop) else trap("web_test: the screenshot has no bitmap")

    let metadata = worker_load_reference_test_metadata(page)
    if ak.vector_is_empty(&metadata.match_references) and ak.vector_is_empty(&metadata.mismatch_references):
        trap("VERIFY_NOT_REACHED: no match or mismatch references")

    # FIXME (test-web): Currently we only support single match or mismatch reference.
    var should_match = true
    var reference_url: web_url.Url = ---
    if not ak.vector_is_empty(&metadata.match_references):
        reference_url = *ak.vector_at_const(&metadata.match_references, 0)
    else:
        should_match = false
        reference_url = *ak.vector_at_const(&metadata.mismatch_references, 0)

    var expected: gfx.Bitmap* = ---
    let reference_path_string = web_url.url_file_path(&reference_url)
    let reference_path = ak.string_view_text(ak.byte_string_view(&reference_path_string))
    if worker_is_image_path(reference_path):
        expected = worker_decode_png(reference_path) catch failure: trap(f"web_test: cannot decode the reference image {reference_path}: {failure.message}")
        worker_stage("reference-decoded")
    else:
        let reference_document = worker_load_and_wait(page, event_loop, vm, reference_url)
        worker_stage("reference-loaded")
        worker_after_fonts_and_paint(page, event_loop, reference_document)
        expected = worker_take_screenshot(page, event_loop) else trap("web_test: the screenshot has no bitmap")

    let test_url_string = web_url.url_serialize(&url)
    let test_url = ak.string_view_text(ak.string_bytes_as_string_view(&test_url_string))
    let screenshot_matches = fuzzy_screenshot_match(test_url, &reference_url, actual, expected, ak.vector_span_const(&metadata.fuzzy), should_match)
    if should_match == screenshot_matches:
        output.put("pass\n")
        return
    worker_write_failure_images(images, actual, expected)
    output.put("fail\n")

## The Crash mode: getting here is passing.
func worker_run_crash(page: const WorkerPage*, event_loop: WorkerEventLoop*, document: web.DomDocument*, output: WorkerOutput*):
    worker_after_fonts_and_paint(page, event_loop, document)
    output.put("pass\n")

# mark: The worker ==============================================================================

## Runs the test at `path` in `options.mode` (web_test --one PATH --mode MODE). Answers the
## exit status: 0 once the result is written (a failed comparison is a result too).
func worker_main(path: str, options: const Options*) -> i32:
    # The loop lives in this frame for the whole run (see worker_platform).
    var event_loop = WorkerEventLoop(next_timer_id = 0, exit_requested = false, exit_code = 0)
    let vm = worker_initialize_platform(&event_loop, options.root)
    let heap = web.vm_heap(vm)
    let allocator: memory.Allocator = heap
    with allocator:
        var output = worker_open_output(options.out)
        let page = worker_create_page(vm, &event_loop, not options.no_rendering)
        # WebContent's PageHost holds its client (GC::Root).
        var client_root = gc.root_create(page.client)
        defer gc.root_release(&client_root)
        worker_stage("page")

        let absolute_path = worker_absolute_path(path)
        let url = worker_file_url(absolute_path)
        let bytes = worker_read_file(absolute_path)
        let document = worker_load_document(&page, vm, url, bytes)
        worker_wait_for_load(&page, &event_loop, &url)

        match options.mode:
            .layout: worker_run_layout(&page, &event_loop, document, &output, not options.no_rendering)
            .ref: worker_run_ref(&page, &event_loop, vm, url, document, options.images, &output)
            .crash: worker_run_crash(&page, &event_loop, document, &output)
            .screenshot:
                let expectation_path = worker_screenshot_expectation_path(options.root, path)
                worker_run_screenshot(&page, &event_loop, url, document, expectation_path, options.images, &output)
        worker_stage("done")
    return 0