src/testing/trf_codegen/CODEWALK.md

# 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.