This guide provides instructions on how to run an end-to-end test for testing a Fuchsia product.
This guide uses the Fuchsia emulator (FEMU) to emulate a device that runs Fuchsia. As for the end-to-end test, the guide uses the screen_is_not_black
end-to-end test.
The screen_is_not_black
end-to-end test reboots a device under test (DUT), waits 100 seconds, and takes a snapshot of the device’s screen. If the snapshot image is not a black screen, the test concludes that Fuchsia is successfully up and running on the device after reboot.
To run this end-to-end test, the steps are:
Also, to run any end-to-end test, see the Appendices section.
This guide requires that you've completed the following guides:
Before you can run the screen_is_not_black
end-to-end test, you first need to build your Fuchsia image to include the test in the build artifacts:
Note: The examples in this guide use the workstation
product. End-to-end tests work with most products except core
.
To add the end-to-end test, run the fx set
command with the following --with
option:
fx set workstation.qemu-x64 --with //src/tests/end_to_end/screen_is_not_black
//src/tests/end_to_end/screen_is_not_black
is a test directory in the Fuchsia source tree. The BUILD.gn file in this directory defines the screen_is_not_black target to include the screen_is_not_black end-to-end test in the build artifacts.
Build your Fuchsia image:
fx build
When the fx build
command completes, the build artifacts now include the screen_is_not_black
end-to-end test, which you can run from your host machine.
Start the emulator with your Fuchsia image and run a package repository server:
Note: The steps in this section assume that you don't have any terminals currently running FEMU or the fx serve
command.
Configure an IPv6 network for the emulator:
Note: This has to be completed once per machine.
sudo ip tuntap add dev qemu mode tap user $USER && sudo ip link set qemu up
Configure the upscript:
Note: If your machine is behind a firewall, you may need to apply some additional configuration to allow the emulator to access the network. This is typically accomplished by running an “upscript”, which sets up the interfaces and firewall access rules for the current process. If you‘re on a corporate network, check with your internal networking team to see if they have an existing upscript for you to use. If you’re not behind a firewall, there's still some configuration needed to enable tun/tap networking. The example upscript at {{ ‘’ }}FUCHSIA_ROOT{{ ‘’ }}/scripts/start-unsecure-internet.sh should work for the majority of non-corporate users.
ffx config set emu.upscript {{ '<var>' }}PATH_TO_UPSCRIPT{{ '</var>' }}
Replace the following:
PATH_TO_UPSCRIPT
: The path to a FEMU network setup script; for example, ~/fuchsia/scripts/start-unsecure-internet.sh
.Start the package server
fx serve
Start the emulator:
ffx emu start --net tap
When startup is complete, the emulator prints the following message and opens a shell prompt:
Logging to "{{ '<var>' }}$HOME{{ '</var>' }}/.local/share/Fuchsia/ffx/emu/instances/fuchsia-emulator/emulator.log" Waiting for Fuchsia to start (up to 60 seconds)........Emulator is ready.
The --net
flag requires a value to indicate which kind of networking to implement. --net
has the following possible values:
tap
: Attaches a Tun/Tap interface.user
: Sets up mapped ports through SLiRP.none
: Disables networking.auto
: Checks the host system's capabilities and selects tap
if it is available or user
if a tap interface is unavailable. auto
is the default.auto
is the default if the flag is not specified on the command line. The upscript is automatically executed only if the user selects tap
mode.
If auto
is used, the launcher checks for a tap interface on the device. If it finds a tap interface, it uses tap
mode; otherwise it uses user
mode.
Run the fx set-device
command and select fuchsia-emulator
(the emulator's default device name) to be your device, for example:
Run the screen_is_not_black
end-to-end test:
fx test --e2e screen_is_not_black
When the test passes, this command prints output similar to the following:
Saw a screen that is not black; waiting for 0:00:59.924543 now. ... [FINE]: Running over ssh: killall sl4f.cmx 01:46 +1: All tests passed!
Use the fx test --e2e
command to run an end-to-end test from your host machine:
fx test --e2e <TEST_NAME>
Some product configurations may include a set of end-to-end tests by default (see Examine product configuration files). However, if you want to run an end-to-end test that is not part of your product configuration, configure your Fuchsia image to include the specific test:
fx set <PRODUCT>.<BOARD> --with <TEST_DIRECTORY>:<TARGET>
For example, the following commands configure and build your Fuchsia image with all the end-to-end tests in the //src/tests/end_to_end/perf test directory:
$ fx set workstation.qemu-x64 --with //src/tests/end_to_end/perf:test $ fx build
Note: Some end-to-end tests are designed to run only on specific product configurations.
For the list of all available end-to-end tests in the Fuchsia repository, see the //src/tests/end_to_end directory.
To find out which end-to-end tests are included in a specific product configuration, examine product configuration files (.gni
) in the Fuchsia repository's //products directory.
The following example shows the product configurations files in the //products
directory:
~/fuchsia/products$ ls *.gni bringup.gni core.gni terminal.gni workstation.gni
To see the list of all available product configurations, you can run the following command:
fx list-products
Among these product configurations, terminal and workstation include end-to-end tests by default. The following example shows the end-to-end tests included in terminal.gni
:
cache_package_labels += [ ... "//src/tests/end_to_end/bundles:end_to_end_deps", "//src/tests/end_to_end/bundles:terminal_end_to_end_deps", ] ... universe_package_labels += [ "//src/tests/end_to_end/screen_is_not_black", "//src/tests/end_to_end/sl4f:test", "//src/tests/end_to_end/perf:test", ... ]