Test Components (Components v2)


Integration Tests

This section defines various patterns commonly used to author integration tests. Note that test authors can use other patterns if it makes sense for their project.

Driver pattern for v2 component tests

This section demonstrates how to use the driver pattern to write your test. See this BUILD.gn file as an example:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/basic/integration_tests/BUILD.gn" region_tag="example_snippet" adjust_indentation="auto" %}

The topology for the example will look like:

Test driver topology

In this example the test package hello-world-integration-test contains four components:

  • hello-world-integration-test-component - Main entry point
  • hello-world - Component to test
  • hello-world-integration-test-driver - Test driver
  • archivist-for-embedding - Helper component which provides services to other components.

hello-world-integration-test-component has two children:

  • hello-world-integration-test-driver
  • archivist-for-embedding

This is a simple component realm which launches hello-world-integration-test-driver and offers it helper services.

Note that it exposes fuchsia.test.Suite from its child the test driver. The topmost component in a test realm must always expose this protocol to integrate with the Test Runner Framework.

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/basic/integration_tests/meta/hello-world-integration-test.cml" region_tag="example_snippet" adjust_indentation="auto" %}

hello-world-integration-test-driver contains the test logic and expectations. The component launches the hello-world component and asserts that it is writing the expected strings to the log.

Note that this is a Rust test, and therefore includes rust/default.shard.cml which sets up capability routing required to integrate with the Rust test framework.

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/basic/integration_tests/meta/hello-world-integration-test-driver.cml" region_tag="example_snippet" adjust_indentation="auto" %}

The code for this example can be found under //examples/components/basic/integration_tests.

Running the tests

To run a Fuchsia test use this command:

For more information, see Run Fuchsia tests.

Running test cases in parallel

Different test runtimes support different levels of parallelism. Their default behaviors might differ. For instance, GoogleTest C++ tests default to running serially (one at a time), while Rust tests run multiple tests concurrently.

You can specify the maximum parallelism for tests in the build definition to override the default behavior, as shown below.

  • {Using fuchsia_test_package}
fuchsia_component("my-package") {
  testonly = true
  manifest = "meta/my-test.cml"
  deps = [ ":my_test" ]

fuchsia_test_package("my-package") {
  test_specs = {
      parallel = 1
  test_components = [ ":my-test" ]
  • {Using test_package}
test_package("my-package") {
  deps = [

  meta = []
      path = rebase_path("meta/my-test.cml")
      dest = "my-test.cm"

  tests = [
      parallel = 1
      name = "my_test"
      environments = basic_envs

When running the test on a development device, prefer fx test to run the test. The tool automatically picks the configuration and passes it to run-test-suite. If for some reason you need to use run-test-suite, you need to pass the flag.

fx shell run-test-suite --parallel=5 <test_url>