TRF Codegen Tool: Internal Codewalk

TRF (Test Realm Factory) is a system for authoring integration tests in Fuchsia by combining a Test Driver (TD), an Injectable Universe (IU), and a Component Under Test (CUT). However, doing this manually requires writing a lot of boilerplate CML and Rust setup code.

trf_codegen provides macro-based tooling to automatically generate this boilerplate for a test.

Codewalk (TLDR)

This module provides three main macros: #[trf::test], #[trf::mock], and #[trf::control], and an accompanying GN template (trf_test.gni).

  1. trf_test.gni (//src/testing/trf_codegen/trf_test.gni) This defines the build integration. Given a Rust source file and a Component Under Test (CUT), this template:

    • Invokes the trf_codegen tool on the source file to parse the macros and generate CML + FIDL components.
    • Generates the Injectable Universe (IU) and Test Driver (TD) components dynamically.
    • Packages them into a fuchsia_test_package containing the Test Driver and the RealmBuilder server, with the CUT passed natively as a subpackage.

  2. The Rust Codegen Tool (//src/testing/trf_codegen/bin)

    • parser.rs: Uses syn to parse the provided test source file, specifically extracting #[trf::test] entries, #[trf::mock] implementation blocks, and #[trf::control] methods requested on them.
    • consistency_checker.rs: Verifies that the implementation does not contain conflicting or invalid mock declarations.
    • generator.rs: Takes the parsed structure and generates:
      • mock_control.fidl: A dynamic FIDL control protocol that the Test Driver uses to talk to the Injectable Universe containing the Mocks.
      • Component manifests for both the test driver (test_driver.cml) and injectable universe (injectable_universe.cml).
      • Rust setup code for RealmBuilder (realm_builder_generated.rs).
      • A stub injected injectable_universe.rs containing the Realm Builder local setup code to connect the user's trf::mock handlers.

  3. User Experience (//src/testing/trf_codegen/lib/macro) The developer uses #[trf::test] to define the test entry point and overarching driver harness. They use #[trf::mock] for structs they implement as a mock FIDL protocol, and #[trf::control] on methods they want exposed for testing over the dynamic control FIDL. Inside the #[trf::test] handler, an implicit mock_control handle is available to steer and coordinate the mock logic from the test driver.

Usage Example

See //examples/components/reverser/trf_test for a concrete usage of these tools.