<<../../_common/fidl/_testing_intro.md>>
Below is an example component manifest for a simple integration test component:
{Rust}
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" ], }, ], }
{C++}
meta/integration_tests.cml
:
{ include: [ "syslog/client.shard.cml", "//src/sys/test_runners/gtest/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:
include
of the necessary language-specific test runner shard. This enables the test manager to properly execute the test suite.children
.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", ] }
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.
To begin, create a project scaffold for a new integration test component called echo-integration
in the //vendor/fuchsia-codelab
directory:
mkdir -p vendor/fuchsia-codelab/echo-integration
Create the following file and directory structure in the new project directory:
{Rust}
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.{C++}
echo-integration |- BUILD.gn |- meta | |- echo_integration.cml | |- echo_integration_test.cc
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.echo_integration_test.cc
: Source code for the C++ integration tests.The manifest for the test component applies the baseline dependencies, such as test_runners
. 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.
{% set cml_rust %} {% includecode gerrit_repo=“fuchsia/fuchsia” gerrit_path=“examples/components/routing/integration_tests/rust/meta/echo_integration_test.cml” region_tag=“example_snippet” adjust_indentation=“auto” %} {% endset %}
{% set cml_cpp %} {% includecode gerrit_repo=“fuchsia/fuchsia” gerrit_path=“examples/components/routing/integration_tests/cpp/meta/echo_integration_test.cml” region_tag=“example_snippet” adjust_indentation=“auto” %} {% endset %}
{Rust}
echo-integration/meta/echo_integration.cml
:
{{ cml_rust|replace("echo_integration_test_rust","echo_integration_test")|trim() }}
{C++}
echo-integration/meta/echo_integration.cml
:
{{ cml_cpp|replace("echo_integration_test_cpp","echo_integration_test")|trim() }}
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.
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 code to implement an integration test:
{Rust}
echo-integration/src/lib.rs
:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/integration_tests/rust/src/lib.rs" region_tag="example_snippet" adjust_indentation="auto" %}
{C++}
echo-integration/echo_integration_test.cc
:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/integration_tests/cpp/echo_integration_test.cc" region_tag="example_snippet" adjust_indentation="auto" %}
Add the following build rules to your BUILD.gn
file to build and package the integration test component along with the echo server dependencies:
{% set gn_rust_binary %} {% includecode gerrit_repo=“fuchsia/fuchsia” gerrit_path=“examples/components/routing/integration_tests/rust/BUILD.gn” region_tag=“executable” adjust_indentation=“auto” %} {% endset %}
{% set gn_rust_component %} {% includecode gerrit_repo=“fuchsia/fuchsia” gerrit_path=“examples/components/routing/integration_tests/rust/BUILD.gn” region_tag=“component” adjust_indentation=“auto” %} {% endset %}
{% set gn_cpp_binary %} {% includecode gerrit_repo=“fuchsia/fuchsia” gerrit_path=“examples/components/routing/integration_tests/cpp/BUILD.gn” region_tag=“executable” adjust_indentation=“auto” %} {% endset %}
{% set gn_cpp_component %} {% includecode gerrit_repo=“fuchsia/fuchsia” gerrit_path=“examples/components/routing/integration_tests/cpp/BUILD.gn” region_tag=“component” adjust_indentation=“auto” %} {% endset %}
{Rust}
echo-integration/BUILD.gn
:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/integration_tests/rust/BUILD.gn" region_tag="imports" adjust_indentation="auto" %} {{ gn_rust_binary|replace("echo_integration_test_rust","echo-integration-test")|replace("//examples/components/routing/fidl","//vendor/fuchsia-codelab/echo-fidl")|trim() }} {{ gn_rust_component|replace("echo_integration_test_component","component")|replace("echo_integration_test","echo_integration")|trim() }} fuchsia_test_package("tests") { package_name = "echo-integration-tests" test_components = [ ":component" ] deps = [ "//vendor/fuchsia-codelab/echo-server:component" ] }
{C++}
echo-integration/BUILD.gn
:
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/integration_tests/cpp/BUILD.gn" region_tag="imports" adjust_indentation="auto" %} {{ gn_cpp_binary|replace("echo_integration_test_cpp","echo-integration-test")|replace("//examples/components/routing/fidl","//vendor/fuchsia-codelab/echo-fidl")|trim() }} {{ gn_cpp_component|replace("echo_integration_test_component","component")|replace("echo_integration_test","echo_integration")|trim() }} fuchsia_test_package("tests") { package_name = "echo-integration-tests" test_components = [ ":component" ] deps = [ "//vendor/fuchsia-codelab/echo-server:component" ] }
Add the integration test package to the build configuration:
fx set workstation_eng.x64 \ --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
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