Add WebGL browser tests to vello_sparse_tests (#1020)

Note: This PR currently branches off
#1021 as there is a lint error
on `main` and I wanted to ensure CI fully passed.

> [!TIP]
> This is ready to review and passes all tests in CI. 

### Context

This follows #1011 and is the
testing portion. In order to ensure renderer parity and correctness,
I've forked the `vello_hybrid` tests to also include a `_hybrid_webgl`
variant that use: `#[wasm_bindgen_test::wasm_bindgen_test]` and run via
the browser.

<details>
<summary>
As a demo of this PR, I locally introduced a "fake error" that reflects
the image. After running `wasm-pack test --chrome --features webgl` from
the `vello_sparse_tests` directory, I got the following very long
webpage. (unfurl details section by clicking this text, and scroll to
bottom of test results)
</summary>

![127 0 0
1_8000_](https://github.com/user-attachments/assets/d9033ede-ecac-4602-b329-07ee5b54f465)

</details>

### Features

 - Add headless and headed browser testing of the webgl backend.
- Because the browser can't read from the file system easily, reference
images are inlined into the binary via the proc macro and provided to
the `check_refs` function.
- Existing `_hybrid` tests are unchanged. I've added a `_hybrid_webgl`
test.
- For ease of debugging the diff'd images are appended to the document
after tests have run. This makes it much easier to understand the
failure.
- Add `check vello_hybrid webgl backend passes vello_sparse_tests suite`
CI step that uses headless browser.

These tests could be fancier, but they do the job right now. Debugging a
failure isn't easy, however the diff can be manually retrieved and
compared by a human by spinning up a browser.

The goal of having webgl tests automatically match the vello_hybrid
tests is to keep the `wgpu` and `webgl` renderer backends in sync.

### Test plan

This PR changes no business logic and is the test.

Note: Browser WebGL backend tests currently pass all of the same tests
as the vello_hybrid wgpu renderer. Can be seen in CI here:
https://github.com/linebender/vello/actions/runs/15211363959/job/42786078261?pr=1020

I tested the functionality of this change by introducing intentional
breakages and ensuring that headless tests failed, and diff images could
be found on the browser when run without headless.

### Risks

I'm not sure of any risks as this isn't user facing.

### Manually testing this change

Pull branch down locally. Then navigate the `vello_sparse_tests` and
run: `wasm-pack test --chrome --features webgl`. Navigate to the browser
URL and see 65 tests succeed.


### Followup work

#1026
#1025

---------

Co-authored-by: Daniel McNab <[email protected]>

Author: ajakubowicz-canva

.github/workflows/ci.yml

@@ -306,9 +306,27 @@ jobs:
 
   test-stable-wasm:
     name: cargo test (wasm32)
+    needs: prime-lfs-cache
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        # We intentionally do not use lfs: true here, instead using the caching method to save LFS bandwidth.
+
+      - name: Restore lfs cache
+        id: lfs-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: .git/lfs
+          # The files targeted with git lfs
+          key: vello-lfs-${{ needs.prime-lfs-cache.outputs.lfs-hash }}
+          enableCrossOsArchive: true
+  
+      - name: Checkout LFS files
+        # `git lfs checkout` requires that each individual glob is a separate command line argument.
+        # The string `''' '''` is how you write `' '` in GitHub's expression context (i.e. two quotes separated by a space)
+        # The quotes are to avoid the shell from evaluating the globs itself.
+        run: git lfs checkout '${{ join(fromJson(env.LFS_FILES), ''' ''') }}'
+        continue-on-error: true
 
       - name: install stable toolchain
         uses: dtolnay/rust-toolchain@master
@@ -337,6 +355,10 @@ jobs:
         run: wasm-pack test --headless --chrome
         working-directory: sparse_strips/vello_hybrid/examples/native_webgl
 
+      - name: Run vello_sparse_tests on Chrome
+        run: wasm-pack test --headless --chrome --features webgl
+        working-directory: sparse_strips/vello_sparse_tests
+
 
   check-stable-android:
     name: cargo check (aarch64-android)

Cargo.lock

@@ -61,6 +61,10 @@ pub(crate) fn vello_test_inner(attr: TokenStream, item: TokenStream) -> TokenStr
     let u8_fn_name = Ident::new(&format!("{}_cpu_u8", input_fn_name), input_fn_name.span());
     let f32_fn_name = Ident::new(&format!("{}_cpu_f32", input_fn_name), input_fn_name.span());
     let hybrid_fn_name = Ident::new(&format!("{}_hybrid", input_fn_name), input_fn_name.span());
+    let webgl_fn_name = Ident::new(
+        &format!("{}_hybrid_webgl", input_fn_name),
+        input_fn_name.span(),
+    );
 
     // TODO: Tests with the same names in different modules can clash, see
     // https://github.com/linebender/vello/pull/925#discussion_r2070710362.
@@ -70,6 +74,7 @@ pub(crate) fn vello_test_inner(attr: TokenStream, item: TokenStream) -> TokenStr
     let u8_fn_name_str = u8_fn_name.to_string();
     let f32_fn_name_str = f32_fn_name.to_string();
     let hybrid_fn_name_str = hybrid_fn_name.to_string();
+    let webgl_fn_name_str = webgl_fn_name.to_string();
 
     let Arguments {
         width,
@@ -83,6 +88,30 @@ pub(crate) fn vello_test_inner(attr: TokenStream, item: TokenStream) -> TokenStr
         no_ref,
     } = parse_args(&attrs);
 
+    // Wasm doesn't have access to the filesystem. For wasm, inline the snapshot bytes into the
+    // binary.
+    let reference_image_name = Ident::new(
+        &format!(
+            "{}_REFERENCE_IMAGE",
+            input_fn_name.to_string().to_uppercase()
+        ),
+        input_fn_name.span(),
+    );
+    let reference_image_const = if !no_ref {
+        quote! {
+            #[cfg(target_arch = "wasm32")]
+            const #reference_image_name: &[u8] = include_bytes!(
+                concat!(env!("CARGO_MANIFEST_DIR"), "/snapshots/", #input_fn_name_str, ".png")
+            );
+            #[cfg(not(target_arch = "wasm32"))]
+            const #reference_image_name: &[u8] = &[];
+        }
+    } else {
+        quote! {
+            const #reference_image_name: &[u8] = &[];
+        }
+    };
+
     let cpu_u8_tolerance = cpu_u8_tolerance + DEFAULT_CPU_U8_TOLERANCE;
     // Since f32 is our gold standard, we always require exact matches for this one.
     let cpu_f32_tolerance = DEFAULT_CPU_F32_TOLERANCE;
@@ -137,7 +166,7 @@ pub(crate) fn vello_test_inner(attr: TokenStream, item: TokenStream) -> TokenStr
                 let mut ctx = get_ctx::<RenderContext>(#width, #height, #transparent);
                 #input_fn_name(&mut ctx);
                 if !#no_ref {
-                    check_ref(&ctx, #input_fn_name_str, #fn_name_str, #tolerance, #is_reference, #render_mode);
+                    check_ref(&ctx, #input_fn_name_str, #fn_name_str, #tolerance, #is_reference, #render_mode, #reference_image_name);
                 }
             }
         }
@@ -161,6 +190,8 @@ pub(crate) fn vello_test_inner(attr: TokenStream, item: TokenStream) -> TokenStr
     let expanded = quote! {
         #input_fn
 
+        #reference_image_const
+
         #u8_snippet
 
         #f32_snippet
@@ -177,7 +208,24 @@ pub(crate) fn vello_test_inner(attr: TokenStream, item: TokenStream) -> TokenStr
             let mut ctx = get_ctx::<Scene>(#width, #height, #transparent);
             #input_fn_name(&mut ctx);
             if !#no_ref {
-                check_ref(&ctx, #input_fn_name_str, #hybrid_fn_name_str, #hybrid_tolerance, false, RenderMode::OptimizeSpeed);
+                check_ref(&ctx, #input_fn_name_str, #hybrid_fn_name_str, #hybrid_tolerance, false, RenderMode::OptimizeSpeed, #reference_image_name);
+            }
+        }
+
+        #ignore_hybrid
+        #[cfg(all(target_arch = "wasm32", feature = "webgl"))]
+        #[wasm_bindgen_test::wasm_bindgen_test]
+        async fn #webgl_fn_name() {
+            use crate::util::{
+                check_ref, get_ctx
+            };
+            use vello_hybrid::Scene;
+            use vello_cpu::RenderMode;
+
+            let mut ctx = get_ctx::<Scene>(#width, #height, #transparent);
+            #input_fn_name(&mut ctx);
+            if !#no_ref {
+                check_ref(&ctx, #input_fn_name_str, #webgl_fn_name_str, #hybrid_tolerance, false, RenderMode::OptimizeSpeed, #reference_image_name);
             }
         }
     };

sparse_strips/vello_dev_macros/src/test.rs

@@ -28,5 +28,24 @@ image = { workspace = true, features = ["png"] }
 skrifa = { workspace = true }
 smallvec = { workspace = true }
 
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+wasm-bindgen-test = "0.3.50"
+web-sys = { version = "0.3.77", features = [
+    "HtmlCanvasElement",
+    "WebGl2RenderingContext",
+    "Document",
+    "Window",
+    "Element",
+    "HtmlElement",
+    "HtmlImageElement",
+    "Blob",
+    "BlobPropertyBag",
+    "Url",
+] }
+wasm-bindgen = "0.2.100"
+
+[features]
+webgl = ["vello_hybrid/webgl"]
+
 [lints]
 workspace = true

sparse_strips/vello_sparse_tests/Cargo.toml

@@ -0,0 +1,54 @@
+<div align="center">
+
+# Vello Sparse Tests
+
+[![Apache 2.0 or MIT license.](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](#license)
+\
+[![Linebender Zulip chat.](https://img.shields.io/badge/Linebender-%23vello-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/channel/197075-vello)
+[![GitHub Actions CI status.](https://img.shields.io/github/actions/workflow/status/linebender/vello/ci.yml?logo=github&label=CI)](https://github.com/linebender/vello/actions)
+
+</div>
+
+This is a development-only crate for testing the sparse_strip renderers across a corpus of reference
+images:
+- CPU
+- WGPU
+- WASM32 WebGL
+
+The `vello_test` proc macro will create a snapshot test for each supported renderer target. See the
+below example usage.
+
+```rs
+// Draws a filled triangle into a 125x125 scene.
+#[vello_test(width = 125, height = 125)]
+fn filled_triangle(ctx: &mut impl Renderer) {
+    let path = {
+        let mut path = BezPath::new();
+        path.move_to((5.0, 5.0));
+        path.line_to((95.0, 50.0));
+        path.line_to((5.0, 95.0));
+        path.close_path();
+
+        path
+    };
+
+    ctx.set_paint(LIME);
+    ctx.fill_path(&path);
+}
+```
+
+See all the attributes that can be passed to `vello_test` in `vello_dev_macros/test.rs`.
+
+## Testing WebGL on the Browser
+
+Requirements:
+ - on MacOS, a minimum Clang major version of 20 is required.
+
+To run the `vello_sparse_tests` suite on WebGL headless:
+
+```sh
+wasm-pack test --headless --chrome --features webgl
+```
+
+To debug the output images in webgl, run the same command without `--headless`. Any tests that fail
+will have their diff image appended to the bottom of the page.

sparse_strips/vello_sparse_tests/README.md

@@ -21,6 +21,9 @@
 #![allow(missing_docs, reason = "we don't need docs for testing")]
 #![allow(clippy::cast_possible_truncation, reason = "not critical for testing")]
 
+#[cfg(target_arch = "wasm32")]
+wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);
+
 mod basic;
 mod blurred_rounded_rect;
 mod clip;

sparse_strips/vello_sparse_tests/tests/mod.rs

@@ -219,6 +219,7 @@ impl Renderer for Scene {
     // This method creates device resources every time it is called. This does not matter much for
     // testing, but should not be used as a basis for implementing something real. This would be a
     // very bad example for that.
+    #[cfg(not(all(target_arch = "wasm32", feature = "webgl")))]
     fn render_to_pixmap(&self, pixmap: &mut Pixmap, _: RenderMode) {
         // On some platforms using `cargo test` triggers segmentation faults in wgpu when the GPU
         // tests are run in parallel (likely related to the number of device resources being
@@ -362,6 +363,58 @@ impl Renderer for Scene {
         texture_copy_buffer.unmap();
     }
 
+    // vello_hybrid WebGL renderer backend.
+    #[cfg(all(target_arch = "wasm32", feature = "webgl"))]
+    fn render_to_pixmap(&self, pixmap: &mut Pixmap, _: RenderMode) {
+        use wasm_bindgen::JsCast;
+        use web_sys::{HtmlCanvasElement, WebGl2RenderingContext};
+
+        let width = self.width();
+        let height = self.height();
+
+        // Create an offscreen HTMLCanvasElement, render the test image to it, and finally read off
+        // the pixmap for diff checking.
+        let document = web_sys::window().unwrap().document().unwrap();
+
+        let canvas = document
+            .create_element("canvas")
+            .unwrap()
+            .dyn_into::<HtmlCanvasElement>()
+            .unwrap();
+
+        canvas.set_width(width.into());
+        canvas.set_height(height.into());
+
+        let mut renderer = vello_hybrid::WebGlRenderer::new(&canvas);
+        let render_size = vello_hybrid::RenderSize {
+            width: width.into(),
+            height: height.into(),
+        };
+
+        renderer.render(self, &render_size).unwrap();
+
+        let gl = canvas
+            .get_context("webgl2")
+            .unwrap()
+            .unwrap()
+            .dyn_into::<WebGl2RenderingContext>()
+            .unwrap();
+        let mut pixels = vec![0_u8; (width as usize) * (height as usize) * 4];
+        gl.read_pixels_with_opt_u8_array(
+            0,
+            0,
+            width.into(),
+            height.into(),
+            WebGl2RenderingContext::RGBA,
+            WebGl2RenderingContext::UNSIGNED_BYTE,
+            Some(&mut pixels),
+        )
+        .unwrap();
+
+        let pixmap_data = pixmap.data_as_u8_slice_mut();
+        pixmap_data.copy_from_slice(&pixels);
+    }
+
     fn width(&self) -> u16 {
         Self::width(self)
     }