Google is committed to advancing racial equity for Black communities. See how.

Integration testing

Integration testing focuses on validating your component's behavior as it interacts with other components on the system. Because of this, integration tests are typically built separately from the main component and may declare the component under test and other dependencies as children. Depending on the nature of the test, dependency components may be provided as mocks or stubs to promote that the test cases remain hermetic.

Test components

Below is an example component manifest for a simple integration test component:

meta/integration_tests.cml:

{
    include: [
        "syslog/client.shard.cml",
        "//src/sys/test_runners/rust/default.shard.cml",
    ],
    program: {
        binary: "bin/client_test",
    },
    children: [
        {
            name: "service",
            url: "fuchsia-pkg://fuchsia.com/foo-package-tests#meta/mock_service.cm",
        },
        {
            name: "client",
            url: "fuchsia-pkg://fuchsia.com/foo-package-tests#meta/foo_client.cm",
        },
    ],
    offer: [
        {
            protocol: "fuchsia.example.Foo",
            from: "#service",
            to: [ "#client" ],
        },
    ],
}

This test component declaration contains the following key elements:

  1. An include of the necessary language-specific test runner shard. This enables the test manager to properly execute the test suite.
  2. Listing the component under test and dependent components as children.
  3. Routing required capabilities between components in the test realm.

The Fuchsia build system provides the fuchsia_test_package() GN target for distinct test components such as integration tests. This rule enables you to declare the components containing tests separately from those required as dependencies, and describes the target device environment where the tests should run.

Here is an example of how the above integration test could be included in the BUILD.gn file:

import("//build/components.gni")
...

// Component under test
fuchsia_component("foo_client") {
  deps = [ ... ]
  manifest = "meta/foo_client.cml"
}

// Test dependencies
fuchsia_component("mock_service") {
  deps = [ ... ]
  manifest = "meta/mock_service.cml"
  testonly = true
}

// Component containing integration tests
fuchsia_component("integration_tests") {
  deps = [ ":bin_test" ]
  manifest = "meta/integration_tests.cml"
  testonly = true
}

fuchsia_test_package("hello-world-tests") {
  test_components = [ ":integration_tests" ]
  deps = [
    ":foo_client",
    ":mock_service",
  ]
}

Exercise: Echo server integration test

In this exercise, you'll add an integration test component to exercise the FIDL protocol interface of the echo_server component with the Test Runner Framework and run those tests in a FEMU environment.

Add an integration test component

To begin, create a new integration test scaffold under the echo-integration directory:

fx create component test \
   --path vendor/fuchsia-codelab/echo-integration --lang rust

This creates a project directory structure with an integration test component template:

echo-integration
  |- BUILD.gn
  |- meta
  |   |- echo_integration.cml
  |
  |- src
      |- lib.rs
  • BUILD.gn: GN build targets for the test binaries, component, and package.
  • meta/echo_integration.cml: Manifest declaring the components under test and their capabilities.
  • src/lib.rs: Source code for the Rust integration tests.

Update the test component manifest

The generated manifest for the test component applies the baseline dependencies, such as the Rust test runner. Update the echo_integration.cml file to declare the echo-server component as a child and route the Echo protocol capability to the test component.

echo-integration/meta/echo_integration.cml:

{
    // ...

    // Child components orchestrated by the integration test.
    children: [
        {
            name: "echo_server",
            url: "#meta/echo_server.cm",
        },
    ],

    // Capabilities used by this component.
    use: [
        {
            protocol: [ "fidl.examples.routing.echo.Echo" ],
            from: "#echo_server",
        },
    ],

    // Capabilities required by components under test.
    offer: [
        {
            protocol: [ "fuchsia.logger.LogSink" ],
            from: "parent",
            to: "#echo_server",
        },
    ],
}

Notice that the echo-server instance comes from the same package as the integration test. This practice promotes test packages that are hermetic by avoiding dependencies on components from other packages.

Update the fuchsia_test_package() rule to include the echo-server component as a dependency:

echo-integration/BUILD.gn:

fuchsia_test_package("package") {
  package_name = "echo-integration-tests"
  test_components = [ ":component" ]
  deps = [ "//vendor/fuchsia-codelab/echo-server:component" ]
}

Implement the integration test

The integration test connects to the Echo protocol exposed by the echo-server in the same way as the client component, sends a string request, and validates the expected response.

Add the following contents to the src/lib.rs file:

echo-integration/src/lib.rs:

use {
    anyhow::{self, Error},
    fidl_fidl_examples_routing_echo as fecho,
    fuchsia_component::client,
};

#[fuchsia::test]
async fn echo_integration_test() -> Result<(), Error> {
    const ECHO_STRING: &str = "Hello, world!";

    let echo = client::connect_to_protocol::<fecho::EchoMarker>()
        .expect("error connecting to echo server");
    let out = echo.echo_string(Some(ECHO_STRING)).await.expect("echo_string failed");

    assert_eq!(ECHO_STRING, out.unwrap());
    Ok(())
}

Include the Rust bindings for the Echo protocol to the BUILD.gn file as a dependency:

echo-integration/BUILD.gn:

rustc_test("bin") {
  name = "echo-integration"

  deps = [
    "//vendor/fuchsia-codelab/echo-fidl:echo-rustc",
    ...
  ]

  sources = [ "src/lib.rs" ]
}

Update the build configuration

Add the integration test package to the build configuration:

fx set workstation.qemu-x64 \
    --with //vendor/fuchsia-codelab/echo-fidl:echo \
    --with //vendor/fuchsia-codelab/echo-server \
    --with //vendor/fuchsia-codelab/echo-client \
    --with //vendor/fuchsia-codelab/echo-realm \
    --with //vendor/fuchsia-codelab/echo-integration:tests

Run fx build and verify that the build completes successfully:

fx build

Run the integration test

The fuchsia_test_package() rule generates a package with the test component and its dependencies. The integration test component has the following URL:

fuchsia-pkg://fuchsia.com/echo-integration-tests#meta/echo_integration.cm

Use the ffx test command to execute the integration tests. Verify that the tests pass:

ffx test run \
    fuchsia-pkg://fuchsia.com/echo-integration-tests#meta/echo_integration.cm