example_tester/

lib.rs

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

use anyhow::{Context, Error};
use component_events::events::*;
use component_events::matcher::*;
use component_events::sequence::*;
use diagnostics_data::{Data, Logs};
use diagnostics_reader::{ArchiveReader, LogsArchiveReader};
use fuchsia_async as fasync;
use fuchsia_component_test::{Capability, ChildOptions, ChildRef, RealmBuilder, Ref, Route};
use regex::Regex;
use std::future::Future;

/// Represents a component under test. The `name` is the test-local name assigned to the component,
/// whereas the path is the relative path to its component manifest (ex: "#meta/client.cm").
pub trait Component {
    fn get_name(&self) -> String;
    fn get_path(&self) -> String;
    fn get_regex_matcher(&self) -> String;
    fn matches_log(&self, raw_log: &Data<Logs>) -> bool;
}

/// Represents the client component under test.
#[derive(Clone)]
pub struct Client<'a> {
    name: String,
    path: &'a str,
    regex: Regex,
    matcher: String,
}

impl<'a> Client<'a> {
    /// Create a new instance of a client component, passing in two string references: the name of
    /// the test that created this component, and the path to the `*.cm` file describing this
    /// component in the current package:
    ///
    ///   Client::new("my_test_case", "#meta/some_client.cm");
    ///
    pub fn new(test_prefix: &str, path: &'a str) -> Self {
        let name = format!("{}_client", test_prefix);
        let matcher = format!("{}$", name);
        Self { regex: Regex::new(matcher.as_str()).unwrap(), name, path, matcher }
    }
}

impl<'a> Component for Client<'a> {
    fn get_name(&self) -> String {
        self.name.clone()
    }
    fn get_path(&self) -> String {
        self.path.to_owned()
    }
    fn get_regex_matcher(&self) -> String {
        self.matcher.clone()
    }
    fn matches_log(&self, raw_log: &Data<Logs>) -> bool {
        self.regex.is_match(raw_log.moniker.to_string().as_ref())
    }
}

/// Represents a proxy component under test.
#[derive(Clone)]
pub struct Proxy<'a> {
    name: String,
    path: &'a str,
    regex: Regex,
    matcher: String,
}

impl<'a> Proxy<'a> {
    /// Create a new instance of a proxy component, passing in two string references: the name of
    /// the test that created this component, and the path to the `*.cm` file describing this
    /// component in the current package:
    ///
    ///   Proxy::new("my_test_case", "#meta/some_proxy.cm");
    ///
    pub fn new(test_prefix: &str, path: &'a str) -> Self {
        let name = format!("{}_proxy", test_prefix);
        let matcher = format!("{}$", name);
        Self { regex: Regex::new(matcher.as_str()).unwrap(), name, path, matcher }
    }
}

impl<'a> Component for Proxy<'a> {
    fn get_name(&self) -> String {
        self.name.clone()
    }
    fn get_path(&self) -> String {
        self.path.to_string()
    }
    fn get_regex_matcher(&self) -> String {
        self.matcher.clone()
    }
    fn matches_log(&self, raw_log: &Data<Logs>) -> bool {
        self.regex.is_match(raw_log.moniker.to_string().as_ref())
    }
}

/// Represents a server component under test.
#[derive(Clone)]
pub struct Server<'a> {
    name: String,
    path: &'a str,
    regex: Regex,
    matcher: String,
}

impl<'a> Server<'a> {
    /// Create a new instance of a server component, passing in two string references: the name of
    /// the test that created this component, and the path to the `*.cm` file describing this
    /// component in the current package:
    ///
    ///   Server::new("my_test_case", "#meta/some_server.cm");
    ///
    pub fn new(test_prefix: &str, path: &'a str) -> Self {
        let name = format!("{}_server", test_prefix);
        let matcher = format!("{}$", name);
        Self { regex: Regex::new(matcher.as_str()).unwrap(), name, path, matcher }
    }
}

impl<'a> Component for Server<'a> {
    fn get_name(&self) -> String {
        self.name.clone()
    }
    fn get_path(&self) -> String {
        self.path.to_string()
    }
    fn get_regex_matcher(&self) -> String {
        self.matcher.clone()
    }
    fn matches_log(&self, raw_log: &Data<Logs>) -> bool {
        self.regex.is_match(raw_log.moniker.to_string().as_ref())
    }
}

/// This framework supports three kinds of tests:
///  - 3 components: client <-> proxy <-> server
///  - 2 components: client <-> server
///  - 1 component: standalone client
pub enum TestKind<'a> {
    StandaloneComponent { client: &'a Client<'a> },
    ClientAndServer { client: &'a Client<'a>, server: &'a Server<'a> },
    ClientProxyAndServer { client: &'a Client<'a>, proxy: &'a Proxy<'a>, server: &'a Server<'a> },
}

/// Runs a test of the specified protocol, using one of the `TestKind`s enumerated above. The
/// `input_setter` closure may be used to pass structured config values to the client, which is how
/// the test is meant to receive its inputs. The `logs_reader` closure provides the raw logs
/// collected from all child processes under test, allowing test authors to assert against the
/// logged values. Note that these are raw logs - most users will want to process the logs into
/// string form, which can be accomplished by passing the raw log vector to the `logs_to_str` helper
/// function.
pub async fn run_test<'a, Fut, FutLogsReader>(
    protocol_name: &str,
    test_kind: TestKind<'a>,
    input_setter: impl FnOnce(RealmBuilder, ChildRef) -> Fut,
    logs_reader: impl Fn(LogsArchiveReader) -> FutLogsReader,
) -> Result<(), Error>
where
    Fut: Future<Output = Result<(RealmBuilder, ChildRef), Error>> + 'a,
    FutLogsReader: Future<Output = ()> + 'a,
{
    // Subscribe to started events for child components.
    let event_stream = EventStream::open().await.unwrap();

    // Create a new empty test realm.
    let builder = RealmBuilder::new().await?;

    // Add the client to the realm, and make the client eager so that it starts automatically.
    let (client_name, client_path, client_regex_matcher) = match test_kind {
        TestKind::StandaloneComponent { client, .. }
        | TestKind::ClientAndServer { client, .. }
        | TestKind::ClientProxyAndServer { client, .. } => {
            (client.get_name(), client.get_path(), client.get_regex_matcher())
        }
    };
    let client =
        builder.add_child(client_name.clone(), client_path, ChildOptions::new().eager()).await?;

    // Apply the supplied configs to the client to allow the test runner to pass "arguments" in.
    let (builder, client) = input_setter(builder, client).await?;

    // Route the LogSink to all children so that all realm members are able to send us logs.
    let mut log_sink_route = Route::new()
        .capability(Capability::protocol_by_name("fuchsia.logger.LogSink"))
        .from(Ref::parent())
        .to(&client);

    // Take note of child names - we'll use these to setup logging filters further down the line.
    let mut child_names = vec![client_name];

    // Create event listeners waiting on client component startup.
    let mut start_event_matchers =
        vec![EventMatcher::ok().moniker_regex(client_regex_matcher.clone())];

    // Setup the test in each of the three supported configurations.
    if !std::matches!(test_kind, TestKind::StandaloneComponent { .. }) {
        // We have a server - add it to the realm.
        let (server_name, server_path, server_regex_matcher) = match test_kind {
            TestKind::ClientAndServer { server, .. }
            | TestKind::ClientProxyAndServer { server, .. } => {
                (server.get_name(), server.get_path(), server.get_regex_matcher())
            }
            _ => panic!("unreachable!"),
        };
        let server =
            builder.add_child(server_name.clone(), server_path, ChildOptions::new()).await?;
        child_names.push(server_name);

        // Setup logging.
        log_sink_route = log_sink_route.to(&server);

        // Add event matchers waiting on server component startup/shutdown.
        start_event_matchers.push(EventMatcher::ok().moniker_regex(server_regex_matcher));

        if std::matches!(test_kind, TestKind::ClientAndServer { .. }) {
            // If there is no proxy, connect the client to the server directly.
            builder
                .add_route(
                    Route::new()
                        .capability(Capability::protocol_by_name(protocol_name))
                        .from(&server)
                        .to(&client),
                )
                .await?;
        } else {
            // We have a proxy - add it to the realm.
            let (proxy_name, proxy_path, proxy_regex_matcher) = match test_kind {
                TestKind::ClientProxyAndServer { proxy, .. } => {
                    (proxy.get_name(), proxy.get_path(), proxy.get_regex_matcher())
                }
                _ => panic!("unreachable!"),
            };
            let proxy =
                builder.add_child(proxy_name.clone(), proxy_path, ChildOptions::new()).await?;
            child_names.insert(1, proxy_name);

            // Setup logging.
            log_sink_route = log_sink_route.to(&proxy);

            // Add event matchers waiting on server component startup/shutdown. The proxy watcher needs to be
            // inserted prior to the server watcher, as the startup sequence for 3 process tests is
            // client then proxy then server.
            start_event_matchers.insert(1, EventMatcher::ok().moniker_regex(proxy_regex_matcher));

            // Route the capabilities from the server to the proxy.
            builder
                .add_route(
                    Route::new()
                        .capability(Capability::protocol_by_name(protocol_name))
                        .from(&server)
                        .to(&proxy),
                )
                .await?;

            // Route the capabilities from the proxy to the client.
            builder
                .add_route(
                    Route::new()
                        .capability(Capability::protocol_by_name(protocol_name))
                        .from(&proxy)
                        .to(&client),
                )
                .await?;
        }
    }

    // Route the LogSink to all children so that all realm members are able to send us logs.
    builder.add_route(log_sink_route.to_owned()).await?;

    // Create the realm instance.
    let realm_instance = builder.build().await?;

    // Verify that we get expected start and stop (clean) events.
    EventSequence::new()
        .has_subset(start_event_matchers, Ordering::Unordered)
        .has_subset(
            vec![EventMatcher::ok()
                .stop(Some(ExitStatusMatcher::Clean))
                .moniker_regex(client_regex_matcher)],
            Ordering::Unordered,
        )
        .expect(event_stream)
        .await
        .unwrap();

    // Setup the archivist link, but don't read the logs yet!
    let mut archivist_reader = ArchiveReader::logs();
    child_names.iter().for_each(|child_name| {
        let moniker = format!("realm_builder:{}/{}", realm_instance.root.child_name(), child_name);
        archivist_reader.select_all_for_component(moniker.as_str());
    });

    // Clean up the realm instance, and close all open processes.
    realm_instance.destroy().await?;

    // Read all of the logs out to the test, and exit.
    logs_reader(archivist_reader);
    Ok(())
}

/// Takes a vector of raw logs, and returns an iterator over the string representations of said
/// logs. The second argument allows for optional filtering by component. For example, if one only
/// wants to see server logs, the invocation may look like:
///
///   logs_to_str(&raw_logs, Some(vec![&server_component_definition]));
///
pub fn logs_to_str<'a>(
    raw_logs: &'a Vec<Data<Logs>>,
    maybe_filter_by_process: Option<Vec<&'a dyn Component>>,
) -> impl Iterator<Item = &'a str> + 'a {
    logs_to_str_filtered(raw_logs, maybe_filter_by_process, |_raw_log| true)
}

/// Same as |logs_to_str|, except an additional filtering function may be used to trim arbitrary
/// logs. This is particularly useful if one or more languages produces logs that we don't want to
/// include in the final, common output to be compared across language implementations.
pub fn logs_to_str_filtered<'a>(
    raw_logs: &'a Vec<Data<Logs>>,
    maybe_filter_by_process: Option<Vec<&'a dyn Component>>,
    filter_by_log: impl FnMut(&&Data<Logs>) -> bool + 'a,
) -> impl Iterator<Item = &'a str> + 'a {
    raw_logs
        .iter()
        .filter(move |raw_log| match maybe_filter_by_process {
            Some(ref process_list) => {
                for process in process_list.iter() {
                    if process.matches_log(*raw_log) {
                        return true;
                    }
                }
                return false;
            }
            None => true,
        })
        .filter(filter_by_log)
        .map(|raw_log| {
            raw_log.payload_message().expect("payload not found").properties[0]
                .string()
                .expect("message is not string")
        })
}

/// Takes the logs for a single component and compares them to the appropriate golden file. The path
/// of the file is expected to match the template `/pkg/data/goldens/{COMPONENT_NAME}.log.golden`.
/// The {COMPONENT_NAME} is itself generally a template of the form `{TEST_NAME}_{COMPONENT_ROLE}`.
/// Thus, for the three-component `test_foo_bar`, we expect the following golden logs to exist:
///
///   /pkg/data/goldens/test_foo_bar_client.log.golden
///   /pkg/data/goldens/test_foo_bar_proxy.log.golden
///   /pkg/data/goldens/test_foo_bar_server.log.golden
///
pub async fn assert_logs_eq_to_golden<'a>(
    log_reader: &'a LogsArchiveReader,
    comp: &'a dyn Component,
) {
    assert_filtered_logs_eq_to_golden(&log_reader, comp, |_raw_log| true).await;
}

/// Same as |assert_logs_eq_to_golden|, except an additional filtering function may be used to trim
/// arbitrary logs. This is particularly useful if one or more languages produces logs that we don't
/// want to include in the final, common output to be compared across language implementations.
pub async fn assert_filtered_logs_eq_to_golden<'a>(
    log_reader: &'a LogsArchiveReader,
    comp: &'a dyn Component,
    filter_by_log: impl FnMut(&&Data<Logs>) -> bool + 'a + Copy,
) {
    // Extract the golden log data.
    let golden_path = format!("/pkg/data/goldens/{}.log.golden", comp.get_name());
    let golden_file = std::fs::read_to_string(golden_path.clone())
        .with_context(|| format!("Failed to load {golden_path}"))
        .unwrap();
    let golden_logs = golden_file.as_str().trim();

    const MAX_ATTEMPTS: usize = 10;
    let mut attempts = 0;
    while attempts < MAX_ATTEMPTS {
        attempts += 1;
        let raw_logs = log_reader.snapshot().await.expect("can read from the accessor");

        // Compare it to the actual components actual logs, asserting if there is a mismatch.
        let logs = logs_to_str_filtered(&raw_logs, Some(vec![comp]), filter_by_log)
            .collect::<Vec<&str>>()
            .join("\n");
        if logs == golden_logs.trim() {
            break;
        } else if attempts == MAX_ATTEMPTS {
            print!(
                "

Logs golden mismatch in '{}' ({})
Please copy the output between the '===' bounds into the golden file at {} in the fuchsia.git tree
====================================================================================================
{}
====================================================================================================


",
                comp.get_name(),
                comp.get_path(),
                golden_path,
                logs
            );
            assert_eq!(logs, golden_logs)
        }
        fasync::Timer::new(fasync::MonotonicInstant::after(zx::MonotonicDuration::from_millis(
            500,
        )))
        .await;
    }
}