This guide provides instructions on how to run Fuchsia tests using the fx test command.
In Fuchsia, a test can be a component that runs on a Fuchsia device (see Tests as components) or a standalone executable that runs on the host machine.
To run a Fuchsia test, use the fx test command with the name of the test:
fx test <TEST_NAME>
If TEST_NAME is a test component, fx test connects to your Fuchsia device to load and run the test component. That is, the command finds the component's corresponding component URI and calls run-test-component on the target device. However, if TEST_NAME is a host test, fx test directly invokes that test binary to run on the host machine.
Similar to a host test, an end-to-end test also runs on a host machine. The test then may interact with various services on a Fuchsia device for testing purposes (see Scripting Layer for Fuchsia). To run an end-to-end test, provide an additional flag (--e2e) to fx test:
fx test --e2e <END_TO_END_TEST_NAME>
fx test can run multiple tests or test suites at once. The command can also filter those tests to be only device, host, or end-to-end tests.
To customize fx test, you can add flags and provide a number of tests:
fx test <FLAGS> <TEST_NAME_01> <TEST_NAME_02> ...
Common ways to customize fx test are listed in the sections below.
If you want to run multiple sets of Fuchsia tests, configure your Fuchsia build to include several of the primary testing bundles, build Fuchsia, and then run all tests in the build. For example:
$ fx set core.x64 --with //bundles:tools,//bundles:tests $ fx build $ fx test
You can also provide multiple targets in a single invocation:
fx test <PACKAGE_01> <PACKAGE_02> <COMPONENT_01> <COMPONENT_02>
See Specify a test in multiple ways for various ways to specify tests.
Use the -- flag to pass additional arguments to test components.
Note: fx test passes these arguments to all selected tests. When you target many test components in a single command, this option may not be ideal.
The following example passes a timeout flag to a test:
$ fx test <TEST_NAME> -- --timeout=5
For example, the command above internally calls the following command on the device:
$ fx shell run-test-component <TEST_COMPONENT_URI> -- --timeout=5 $ fx shell run-test-suite <TEST_COMPONENT_URI> -- --timeout=5
fx test supports multiple ways to reference a specific test:
For a host test, provide a relative path to the test binary from the root of the Fuchsia build output directory. If the path points to a subdirectory, not a file, fx test runs all matching test binaries in that directory.
For example, you can provide a relative path to specify a test binary:
fx test host_x64/pm_cmd_pm_genkey_test
Or you can provide a relative path to a test directory:
fx test host_x64/gen/sdk
Provide a full Fuchsia component URL to specify a test component. For example:
fx test fuchsia-pkg://fuchsia.com/my_example_test_pkg#meta/my_example_test.cmx
Provide a partial package URL to match and run all test components in the package with the provided Fuchsia package URL. For example:
fx test fuchsia-pkg://fuchsia.com/my_example_test_pkg
Provide a package name to run all test components in that package. For example:
fx test my_example_test_pkg
To explicitly specify the input to be a package name, use the flag -p. For example:
fx test -p my_example_test_pkg
Provide a component name (or a resource path) to test a single component in a package. For example:
fx test my_example_test
To explicitly specify the input to be a component name, use the flag -c. For example:
fx test -c my_example_test
To run a component on a specific package, use both -p <PACKAGE_NAME> and -c <COMPONENT_NAME>. For example:
fx test -p my_example_test_pkg -c my_example_test
The fx run-test, fx run-host-tests and fx run-e2e-tests commands are being deprecated in favor of fx test. See the following instructions on how to use fx test in place of these commands:
Substitute fx run-test with fx test.
From:
fx run-test <TEST_PACKAGE_NAME>
To:
fx test <TEST_PACKAGE_NAME>
With run-test, you were able to use the -t flag to specify a single test component to run. For example:
fx run-test <PACKAGE_NAME> -t <NESTED_COMPONENT_NAME>
With fx test, this command becomes:
fx test -p <PACKAGE_NAME> -c <NESTED_COMPONENT_NAME>
If there are no name collisions for the test component, you can simply run:
fx test <NESTED_COMPONENT_NAME>
Substitute fx run-host-tests with fx test.
From:
fx run-host-tests <PATH_TO_HOST_TEST>
To:
fx test <PATH_TO_HOST_TEST>
Substitute fx run-e2e-tests with fx test and an additional --e2e flag.
From:
fx run-e2e-tests <END_TO_END_TEST>
To:
fx test --e2e <END_TO_END_TEST>
The fx smoke-test command automatically detects all tests that are known to the build system as affected by changes in your checkout. Try the following:
fx -i smoke-test --verbose
In the command above, --verbose will also print which tests fx smoke-test thinks are affected by your change. -i will automatically repeat this command every time you save your changes. For test-driven development, try launching this command in a separate shell and watching your code rebuild and retest as you're working on it.
fx smoke-test works best with hermetic test packages. A test package is hermetic if the package contains all the dependencies of any tests in it. That is to say, any code changes that affect the outcome of this test should require rebuilding that test's package as well.