GEMINI.md

1# Customizing the Flutter Web Engine
2 
3This document describes how to build the engine and run tests for the Flutter Web Engine using the `felt` tool.
4 
5## `felt`: Flutter Engine Local Tester
6 
7`felt` is a command-line tool for building and testing the Flutter web engine. To use it, you need to add `FLUTTER_ROOT/engine/src/flutter/lib/web_ui/dev` to your `PATH`.
8 
9Before building the engine, ensure your dependencies are up to date by running the following command from the root of your Flutter checkout:
10 
11```bash
12gclient sync -D
13```
14 
15### Building the Engine with `felt`
16 
17The `felt build` command builds web engine targets. You can specify targets to build, or build all of them by default.
18 
19**Common Targets:**
20 
21*   `sdk`: The Flutter Web SDK.
22*   `canvaskit`: Flutter's version of CanvasKit.
23*   `canvaskit_chromium`: A Chromium-optimized version of CanvasKit.
24*   `skwasm`: Experimental Skia Wasm module renderer.
25 
26**Examples:**
27 
28Build all web engine targets:
29 
30```bash
31felt build
32```
33 
34Build the `sdk` and `canvaskit` targets:
35 
36```bash
37felt build sdk canvaskit
38```
39 
40### Testing with `felt`
41 
42The `felt test` command compiles and runs web engine unit tests.
43 
44**Useful Flags:**
45 
46*   `--compile`: Compiles test bundles.
47*   `--run`: Runs unit tests.
48*   `--copy-artifacts`: Copies build artifacts needed for tests.
49*   `--list`: Lists all test suites and bundles.
50*   `--verbose`: Outputs extra debugging information.
51*   `--start-paused`: Pauses tests before starting to allow setting breakpoints.
52*   `--browser`: Filters tests by browser (e.g., `chrome`, `firefox`, `safari`).
53*   `--compiler`: Filters tests by compiler (e.g., `dart2js`, `dart2wasm`).
54*   `--renderer`: Filters tests by renderer (e.g., `canvaskit`, `skwasm`).
55 
56**Examples:**
57 
58Run all test suites:
59 
60```bash
61felt test
62```
63 
64Run a specific test file:
65 
66```bash
67felt test test/engine/util_test.dart
68```
69 
70Run tests that use the `dart2wasm` compiler:
71 
72```bash
73felt test --compiler dart2wasm
74```
75 
76Run tests on Chrome using the CanvasKit renderer:
77 
78```bash
79felt test --browser chrome --renderer canvaskit
80```
81 
82### Generating Golden Files
83 
84To update the golden files for screenshot tests, use the `--update-screenshot-goldens` flag with the `felt test` command. This is useful when a browser update or other change affects the rendering of a test.
85 
86The generated golden files are placed in the `.dart_tool/skia_gold` directory, under subdirectories for each test configuration (e.g., `chrome-dart2js-canvaskit-ui`).
87 
88**Example:**
89 
90```bash
91felt test --update-screenshot-goldens test/ui/some_golden_test.dart
92```
93 
94### Test Directory Structure
95 
96The `test` directory contains the following subdirectories:
97 
98*   `canvaskit`: Tests for the CanvasKit backend.
99*   `common`: Common utilities for tests.
100*   `engine`: Core engine logic tests.
101*   `fallbacks`: Tests for fallback mechanisms (like fonts).
102*   `ui`: Tests for the `dart:ui` layer implementation for the web, including most of the golden tests.
103*   `webparagraph`: Tests related to paragraph and text layout on the web.
104