Testability
Information about testability:
- All changes within Fuchsia need to adhere to the Testability rubric.
- See also: general Fuchsia testing documentation
Scenic test packages
You can specify packages in these ways:
Everything:
--with //bundles:tests
Individually, if you want to build less packages:
--with //garnet/packages/tests:scenic --with //garnet/packages/tests:scenic_cpp --with //garnet/packages/tests:escher --with //garnet/packages/tests:ui --with //garnet/packages/tests:e2e_input_tests --with //garnet/packages/tests:vulkan --with //garnet/packages/tests:magma
Scenic and CQ
Tests are automatically run before submission by trybots for every CL in Fuchsia. See the
fuchsia-x64-release
and fuchsia-x64-debug
bots on
https://ci.chromium.org/p/fuchsia/builders.
Add a new test suite to existing CQ tests
Most of the Scenic and Escher tests are written in
Googletest.
If you need to add test suites or test cases, you need to create test source files and add
them as a source of the test executables in corresponding BUILD.gn
files.
Adding a test package to CQ
To add a test package to CQ, you need to:
- Create test components;
- Reference the test package;
- Specify test environments.
Create test components
To add a new test package to CQ, you need to create a test component including source files,
metadata and BUILD.gn file. See the
testing documentation.
You can include multiple test executables in one single test package, and all of them will be
executed if you run fx run-test <test_package>
on host.
Examples of test packages:
- scenic_tests: //src/ui/scenic:scenic_tests
- escher_tests: //src/ui/lib/escher:escher_tests
Reference the test package
To ensure the test is run on CQ, it requires an unbroken chain of dependencies that roll up to your
fx set
command's available packages (expandable using the --with
flag), typically
going through the all target of //<layer>/packages/tests/BUILD.gn
, such as
//garnet/packages/tests:all
.
You need to make sure that there is a dependency chain from //<layer>/packages/tests:all
to
your test package. For more information, see
Testing FAQ documentation.
Specify test environments
To ensure that the test is run on CQ, you also need to specify a
test environment
for each test executable in the package inside the test's BUILD.gn
file.
Generally the environment is set to environments = basic_envs
.
This specifies the test should be run on both QEMU (for x64 + arm64) and NUC (for x64), and using
both debug and release builds. For running on other environments, please refer to
the Test Envinronment doc.
Reference the test package transitively. For example, the packages above are
referenced by //garnet/packages/tests:all
.
Unit tests and integration tests
To run tests locally during development:
Running on device
Some of these tests require the test Scenic to connect to the real display controller.
Run fx shell killall scenic.cmx
to kill an active instance of Scenic.
Run all Scenic tests:
From host workstation, ensure
fx serve
is running, then:fx run-test scenic_tests fx run-test escher_tests fx run-test flutter_screencap_test
From Fuchsia target device:
runtests -t gfx_apptests,gfx_unittests,escher_unittests,input_unittests,a11y_manager_apptests
Run a specific test binary:
From host workstation, ensure
fx serve
is running, then:fx run-test scenic_tests -t gfx_unittests # -t <test binary name>
From Fuchsia target device:
runtests -t gfx_unittests
Run a single test:
From host workstation, ensure
fx serve
is running, then:fx run-test scenic_tests -t gfx_unittests -- --gunit_filter=HostImageTest.FindResource
From Fuchsia target device:
runtests -t gfx_unittests -- --gtest_filter=HostImageTest.FindResource
See more documentation about the glob pattern for the filter arg.
Run a specific component
From your host workstation:
fx shell run-test-component fuchsia-pkg://fuchsia.com/scenic_tests#meta/gfx_unittests.cmx
Pixel tests
If you get an error connecting to a display controller, first kill all UI services.
From your host workstation, run:
fx shell "killall base_mgr.cmx; killall root_presenter.cmx; killall scenic.cmx; killall tiles.cmx; killall present_view"
Then run the pixel tests:
fx shell run fuchsia-pkg://fuchsia.com/scenic_tests#meta/gfx_pixeltests.cmx
Alternatively, run:
fx shell runtests -t gfx_pixeltests
Running on emulator
From your host workstation:
fx set terminal.x64 --release --with-base //garnet/packages/tests:scenic
Then, start an emulator:
Start QEMU:
fx qemu
Start AEMU:
fx emu -N
Then, in the QEMU or EMU shell:
runtests -t gfx_apptests,gfx_unittests,escher_unittests,input_unittests,a11y_manager_apptests
Host tests
fx run-host-tests
runs all the host tests, but you probably only want to run Escher tests.- Escher: To run
escher_unittests
locally on Linux: follow instructions in Escher documentation.
Manual UI tests
After making big Scenic changes, you may want to do manual UI testing by running some example applications to see if there is any regression.
UI Examples
There are some examples available:
bouncing_ball
- Basic example of creating
ViewProvider
andView
, and creating a UI by using Scenic commands. - Source:
//src/ui/examples/bouncing_ball
- Build dependency:
//src/ui/examples:bouncing_ball
- Package URI:
fuchsia-pkg://fuchsia.com/bouncing_ball#meta/bouncing_ball.cmx
- Basic example of creating
spinning_square_view
- Example that shows the use of
BaseView
. - Source:
//src/ui/examples/spinning_square
- Build dependency:
//src/ui/examples:spinning_square_view
- Package URI:
fuchsia-pkg://fuchsia.com/spinning_square_view#meta/spinning_square_view.cmx
- Example that shows the use of
spinning_square_rs
- An example written in Rust that shows the use of Carnelian, a prototype framework for writing Fuchsia modules in Rust.
- Source:
//garnet/public/rust/carnelian/examples/spinning_square.rs
- Build dependency:
//garnet/public/rust/carnelian:spinning_square_rs
- Package URI:
fuchsia-pkg://fuchsia.com/spinning_square_rs#meta/spinning_square_rs.cmx
spinning_cube
- An example written in Dart and Flutter, showing how to create a Flutter app in Fuchsia.
- Source:
//src/experiences/examples/spinning_cube
- Build dependency:
//topaz/app/spinning_cube
- Package URI:
fuchsia-pkg://fuchsia.com/spinning_cube#meta/spinning_cube.cmx
simplest_app
- An application which changes background color with every user touch input, which uses root
presenter for its implementation of
BaseView
. It tracks input callbacks from Scenic and draws elements usingscenic::Material
. - Source:
//src/ui/examples/simplest_app
- Build dependency:
//src/ui/examples:simplest_app
- Package URI:
fuchsia-pkg://fuchsia.com/simplest_app#meta/simplest_app.cmx
- An application which changes background color with every user touch input, which uses root
presenter for its implementation of
yuv_to_image_pipe
- An application which updates the scene using an ImagePipe.
- Source:
//src/ui/examples/yuv_to_image_pipe
- Build dependency:
//src/ui/examples:yuv_to_image_pip
- Package URI:
fuchsia-pkg://fuchsia.com/yuv_to_image_pipe#meta/yuv_to_image_pipe.cmx
To run these applications, you need to include the following dependency in your fx set
configuration:
fx set terminal.x64 --with "//src/ui/examples:ui,//topaz/app/spinning_cube,//garnet/public/rust/carnelian"
You can replace the product with workstation.x64
as well; you can also use an all-in-one bundle
--with //bundles:kitchen_sink
to replace the --with
argument above so that you can include all
tests, tools and examples without any extra dependency.
Running UI examples
Running in shell
You can launch the stories (modules) in any shell you are in:
In Ermine shell, you can run modules by typing in the package name (e.g.
simplest_app
, orspinning_cube
) in the [ASK] bar to run modules; orUse command
sessionctl add_mod <mod_name>
to launch a story.From your host workstation, run:
fx shell "sessionctl add_mod fuchsia-pkg://fuchsia.com/spinning_cube#meta/spinning_cube.cmx"
This adds a tab displaying a spinning cube on your current shell.
Note:
sessionctl
supports package URI auto completion if there is only one package matching the<mod_name>
pattern. So the command above is equivalent tofx shell "sessionctl add_mod spinning_cube"
Running a module standalone
You can also launch a module standalone without any existing shells, this works for configurations
where there's no existing shell (e.g. in terminal
or core
products).
Use command
present_view <mod_name>
command to launch a module standalone.From your host workstations, run:
fx shell "present_view fuchsia-pkg://fuchsia.com/spinning_square_view#meta/spinning_square_view.cmx"
to present the
View
provided inspinning_square_view
package.The
present_view
command also allows command auto completion if there is only one package matching the<mod_name>
; so the command above is equivalent tofx shell present_view spinning_square_view
You can also use package
tiles
to create a tiled view and add or delete modules to the tile.- In order to use
tiles
, first you need to ensure that you already have//src/ui/tools/tiles
and//src/ui/tools/tiles_ctl
included in your--with
argument offx set
command.
Or you can use
--with //garnet/packages:all
or--with //bundles:tools
(huge build may be expected) wheretiles
related packages will be included as well.- To display the tiles view, from your host workstations, run:
fx shell "run -d fuchsia-pkg://fuchsia.com/tiles#meta/tiles.cmx"
This runs
tiles.cmx
package as a daemon.- From your host workstation, run the following command to add tiles:
fx shell "tiles_ctl add fuchsia-pkg://fuchsia.com/spinning_square_view#meta/spinning_square_view.cmx"
You can see outputs like:
Tile added with key 1
You can add as many shells as you want by running
tiles_ctl add
command.tiles_ctl remove <key>
command removes existing tile by the given key value. For example, you can run this command on host to remove the spinning square view we created previously:
fx shell tiles_ctl remove 1
- In order to use
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.