Run components in a test

This guide demonstrates how to run a test component.

A component instance is started in Fuchsia when other components request a capability from it. For instance, a test component is started by a test manager, which is also a component, on behalf of a request to run a test.

The guide uses the hello_world_bin_test component in the basic example package. When you run this package’s hello-world-tests test suite, the test manager starts the hello_world_bin_test component. As a result, the component’s test binary runs on a Fuchsia device.

To run this test component, the steps are:

Prerequisites

Verify the following requirements:

Build a Fuchsia image

Configure and build your Fuchsia image to include the test component:

  1. To include a specific component, run the fx set command with the --with option:

    fx set core.qemu-x64 --with //examples/components/basic:hello-world-tests
    

    //examples/components/basic is the directory of the example package and hello-world-tests is the name of the build target defined in the package's BUILD.gn file.

  2. Build your Fuchsia image:

    fx build
    

    When the fx build command completes, your new Fuchsia image now includes the hello_world_bin_test component that can be fetched and launched on-demand.

Start the emulator

Start the emulator with your Fuchsia image and run a package repository server:

  1. Configure an IPv6 network for the emulator (you only need to do this once):

    sudo ip tuntap add dev qemu mode tap user $USER && sudo ifconfig qemu up
    
  2. In a new terminal, start the emulator:

    fx emu -N
    
  3. Set the emulator to be your device:

    fx set-device
    

    If you have multiple devices, select step-atom-yard-juicy (the emulator’s default device name), for example:

    $ fx set-device
    
    Multiple devices found, please pick one from the list:
    1) rabid-snort-wired-tutu
    2) step-atom-yard-juicy
    #? 2
    New default device: step-atom-yard-juicy
    
  4. In another new terminal, start a package repository server:

    fx serve
    

    Keep the fx serve command running as a package server for your device.

Run the test suite

Run the hello-world-tests test suite:

fx test hello-world-tests

This command prints the following output:

$ fx test hello-world-tests

...

[0/1] 00:00 🤔  /home/fuchsia/.jiri_root/bin/fx shell run-test-suite fuchsia-pkg://fuchsia.com/hello-world-tests#meta/hello_world_bin_test.cm
 >> Runtime has exceeded 2 seconds (adjust this value with the -s|--slow flag)
Running test 'fuchsia-pkg://fuchsia.com/hello-world-tests#meta/hello_world_bin_test.cm'

[RUNNING]   tests::assert_0_is_0
[PASSED]    tests::assert_0_is_0
1 out of 1 tests passed...
fuchsia-pkg://fuchsia.com/hello-world-tests#meta/hello_world_bin_test.cm completed with result: PASSED

[1/1] 00:05 ✅  /home/fuchsia/.jiri_root/bin/fx shell run-test-suite fuchsia-pkg://fuchsia.com/hello-world-tests#meta/hello_world_bin_test.cm

🎉  Ran 1 tests with 0 failures (use the -v flag to see each test) 🎉

The output shows that the hello_world_bin_test component is fetched from the package repository server and the component instance runs the test binary on the Fuchsia device (the emulator). See hello_world.rs for the source code of this test binary.