src/examples/README.md

# Flutter embedder examples

These are example apps that can be used to manually
test the behavior of the Flutter embedder.

**TODO(akbiggs): Write integration tests that automatically
verify the behavior of these example apps on each commit.**

## How to run an example

Follow the setup in the
[root README](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/README.md#requirements),
then run from $FUCHSIA_EMBEDDER_DIR:

```sh
scripts/build_and_run_example.sh <example_folder_name>
```

For example:

```sh
scripts/build_and_run_example.sh hello_flutter
```

If the example is marked as `Headless` in the table below,
run the example with the `--headless` flag to turn off rendering
because the component does not support rendering (it is a Dart app
with no UI instead of a Flutter app). For example:

```sh
scripts/build_and_run_example.sh hello_dart --headless
```

This script relies on the `fuchsia_package` BUILD rule for the
example being called `<example_folder_name>_pkg`.

**TODO(akbiggs): Migrate this workflow to Bazel and remove
`build_and_run_example.sh`. The ideal workflow is
`$FUCHSIA_EMBEDDER_DIR/tools/bazel run //src/examples/my_example/my_example_pkg` because
it's consistent with other platforms and discoverable.**

**TODO(akbiggs): Headless examples will not work yet because
there's no environment with the JIT allowlist to run them in.
Find a suitable collection somewhere and run them there. For
now, you can run without `--headless`, which will lead to
an infinite loading spinner but run the app.**

## Example catalog

| Example           | Headless? | Desired behavior                    | Does it work?  |
|-------------------|-----------|-------------------------------------|----------------|
| animation_example | No        | Renders glowing square without jank | Janky (renders animation with glitches) |
| hello_dart        | Yes       | Prints "Hello World!" to `ffx log`  | Yes |
| hello_flutter     | No        | Renders with clickable button       | Yes |