Realm Builder

Rust

將 Rust Realm Builder 程式庫新增至 BUILD.gn 檔案

deps = [
  "//src/lib/fuchsia-component-test",

  # ...
]

C++

將 C++ Realm Builder 程式庫新增至 BUILD.gn 檔案

deps = [
  "//sdk/lib/sys/component/cpp/testing:cpp",

  # ...
]

Rust

本節假設您要編寫非同步測試，且元件的某些部分看起來會像這樣：

#[fuchsia::test]
async fn test() -> Result<(), Error> {
    // ...
}

匯入 Realm Builder 程式庫

use {
    // ...
    fuchsia_component_test::{
        Capability, ChildOptions, LocalComponentHandles, RealmBuilder, Ref, Route,
    },
    futures::{StreamExt, TryStreamExt},
};

初始化 RealmBuilder 結構

為測試中的每個測試案例建立新的 RealmBuilder 執行個體。這會建立不重複的獨立子項領域，確保單一測試案例的副作用不會影響其他測試案例的副作用。

let builder = RealmBuilder::new().await?;

C++

本節假設您要編寫非同步測試，且測試會在訊息迴圈中執行。這類情況通常如下所示：

#include <lib/async-loop/cpp/loop.h>
#include <lib/async-loop/default.h>

TEST(SampleTest, CallEcho) {
    async::Loop loop(&kAsyncLoopConfigAttachToCurrentThread);
    // Test code below
}

匯入 Realm Builder 程式庫

#include <lib/sys/component/cpp/testing/realm_builder.h>

使用程式庫命名空間 此為選用步驟。它會匯入整個程式庫的命名空間，方便您編寫及讀取測試。

// NOLINTNEXTLINE
using namespace component_testing;

初始化 Realm::Builder 類別

為測試中的每個測試案例建立新的 Realm::Builder 執行個體。這會建立不重複的獨立子項領域，確保單一測試案例的副作用不會影響其他測試案例的副作用。

auto builder = RealmBuilder::Create();

Rust

// Add component to the realm, which is fetched using a URL.
let echo_server = builder
    .add_child(
        "echo_server",
        "fuchsia-pkg://fuchsia.com/realm-builder-examples#meta/echo_server.cm",
        ChildOptions::new(),
    )
    .await?;
// Add component to the realm, which is fetched using a fragment-only URL.
// The child is not exposing a service, so the `eager` option ensures the
// child starts when the realm is built.
let echo_client = builder
    .add_child("echo_client", "#meta/echo_client.cm", ChildOptions::new().eager())
    .await?;

C++

// Add component server to the realm, which is fetched using a URL.
builder.AddChild("echo_server",
                 "fuchsia-pkg://fuchsia.com/realm-builder-examples#meta/echo_server.cm");
// Add component to the realm, which is fetched using a fragment-only URL. The
// child is not exposing a service, so the `EAGER` option ensures the child
// starts when the realm is built.
builder.AddChild("echo_client", "#meta/echo_client.cm",
                 ChildOptions{.startup_mode = StartupMode::EAGER});

Rust

在 Rust 中，模擬元件是透過具有下列簽名的函式實作：

/// The implementation for a mock component. The contained function is called when the framework
/// asks the mock to run, and the function is given the component's handles for its namespace and
/// outgoing directory. The mock component may then use this handles to run a ServiceFs, access
/// capabilities as the mock, or perform other such actions.
#[derive(Clone)]
pub struct Mock(
    Arc<dyn Fn(MockHandles) -> BoxFuture<'static, Result<(), Error>> + Sync + Send + 'static>,
);

MockHandles 是一個結構體，包含元件傳入和傳出功能的控制代碼：

/// The handles from the framework over which the mock should interact with other components.
pub struct MockHandles {
    namespace: HashMap<String, fio::DirectoryProxy>,

    /// The outgoing directory handle for a mock component. This can be used to run a ServiceFs for
    /// the mock.
    pub outgoing_dir: ServerEnd<fio::DirectoryMarker>,
}

模擬元件的實作如下所示：

async fn echo_server_mock(handles: LocalComponentHandles) -> Result<(), Error> {
    // Create a new ServiceFs to host FIDL protocols from
    let mut fs = fserver::ServiceFs::new();

    // Add the echo protocol to the ServiceFs
    fs.dir("svc").add_fidl_service(IncomingService::Echo);

    // Run the ServiceFs on the outgoing directory handle from the mock handles
    fs.serve_connection(handles.outgoing_dir)?;

    fs.for_each_concurrent(0, move |IncomingService::Echo(stream)| async move {
        stream
            .map(|result| result.context("Request came with error"))
            .try_for_each(|request| async move {
                match request {
                    fecho::EchoRequest::EchoString { value, responder } => {
                        responder
                            .send(value.as_ref().map(|s| &**s))
                            .expect("failed to send echo response");
                    }
                }
                Ok(())
            })
            .await
            .context("Failed to serve request stream")
            .unwrap_or_else(|e| eprintln!("Error encountered: {:?}", e))
    })
    .await;

    Ok(())
}

C++

在 C++ 中，系統會建立繼承 LocalComponent 介面的類別並覆寫 Start 方法，藉此實作模擬元件。

// The interface for backing implementations of components with a Source of Mock.
class LocalComponentImpl {
 public:
  virtual ~LocalComponentImpl();

  // Invoked when the Component Manager issues a Start request to the component.
  // |mock_handles| contains the outgoing directory and namespace of
  // the component.
  virtual void OnStart() = 0;

  // The LocalComponentImpl derived class may override this method to be informed if
  // ComponentController::Stop() was called on the controller associated with
  // the component instance. The ComponentController binding will be dropped
  // automatically, immediately after LocalComponentImpl::OnStop() returns.
  virtual void OnStop() {}

  // The component can call this method to terminate its instance. This will
  // release the handles, and drop the |ComponentController|, informing
  // component manager that the component has stopped. Calling |Exit()| will
  // also cause the Realm to drop the |LocalComponentImpl|, which should
  // destruct the component, and the handles and bindings held by the component.
  // Therefore the |LocalComponentImpl| should not do anything else after
  // calling |Exit()|.
  //
  // This method is not valid until |OnStart()| is invoked.
  void Exit(zx_status_t return_code = ZX_OK);

  // Returns the namespace provided to the mock component.
  //
  // This method is not valid until |OnStart()| is invoked.
  fdio_ns_t* ns();

  // Returns a wrapper around the component's outgoing directory. The mock
  // component may publish capabilities using the returned object.
  //
  // This method is not valid until |OnStart()| is invoked.
  sys::OutgoingDirectory* outgoing();

  // Convenience method to construct a ServiceDirectory by opening a handle to
  // "/svc" in the namespace object returned by `ns()`.
  //
  // This method is not valid until |OnStart()| is invoked.
  sys::ServiceDirectory svc();

 private:
  friend internal::LocalComponentRunner;
  // The |LocalComponentHandles| are set by the |LocalComponentRunner| after
  // construction by the factory, and before calling |OnStart()|
  std::unique_ptr<LocalComponentHandles> handles_;
};

LocalComponentHandles 類別包含元件傳入和傳出功能的控制代碼：

// Handles provided to mock component.
class LocalComponentHandles final {
 public:
  // ...

  // Returns the namespace provided to the mock component. The returned pointer
  // will be invalid once *this is destroyed.
  fdio_ns_t* ns();

  // Returns a wrapper around the component's outgoing directory. The mock
  // component may publish capabilities using the returned object. The returned
  // pointer will be invalid once *this is destroyed.
  sys::OutgoingDirectory* outgoing();

  // Convenience method to construct a ServiceDirectory by opening a handle to
  // "/svc" in the namespace object returned by `ns()`.
  sys::ServiceDirectory svc();

  // ...
};

模擬元件的實作如下所示：

class LocalEchoServerImpl : public fidl::examples::routing::echo::Echo, public LocalComponentImpl {
 public:
  explicit LocalEchoServerImpl(async_dispatcher_t* dispatcher) : dispatcher_(dispatcher) {}

  // Override `OnStart` from `LocalComponentImpl` class.
  void OnStart() override {
    // When `OnStart()` is called, this implementation can call methods to
    // access handles to the component's incoming capabilities (`ns()` and
    // `svc()`) and outgoing capabilities (`outgoing()`).
    ASSERT_EQ(outgoing()->AddPublicService(bindings_.GetHandler(this, dispatcher_)), ZX_OK);
  }

  // Override `EchoString` from `Echo` protocol.
  void EchoString(::fidl::StringPtr value, EchoStringCallback callback) override {
    callback(std::move(value));
  }

 private:
  async_dispatcher_t* dispatcher_;
  fidl::BindingSet<fidl::examples::routing::echo::Echo> bindings_;
};

Rust

let echo_server = builder
    .add_local_child(
        "echo_server",
        move |handles: LocalComponentHandles| Box::pin(echo_server_mock(handles)),
        ChildOptions::new(),
    )
    .await?;

C++

// Add component to the realm, providing a mock implementation
builder.AddLocalChild("echo_server",
                      [&]() { return std::make_unique<LocalEchoServerImpl>(dispatcher()); });

Rust

builder
    .add_route(
        Route::new()
            .capability(Capability::protocol_by_name("fidl.examples.routing.echo.Echo"))
            .from(&echo_server)
            .to(&echo_client),
    )
    .await?;

C++

builder.AddRoute(Route{.capabilities = {Protocol{"fidl.examples.routing.echo.Echo"}},
                       .source = ChildRef{"echo_server"},
                       .targets = {ChildRef{"echo_client"}}});

Rust

builder
    .add_route(
        Route::new()
            .capability(Capability::protocol_by_name("fidl.examples.routing.echo.Echo"))
            .from(&echo_server)
            .to(Ref::parent()),
    )
    .await?;

C++

builder.AddRoute(Route{.capabilities = {Protocol{"fidl.examples.routing.echo.Echo"}},
                       .source = ChildRef{"echo_server"},
                       .targets = {ParentRef()}});

Rust

builder
    .add_route(
        Route::new()
            .capability(Capability::protocol_by_name("fuchsia.logger.LogSink"))
            .from(Ref::parent())
            .to(&echo_server)
            .to(&echo_client),
    )
    .await?;

C++

builder.AddRoute(Route{.capabilities = {Protocol{"fuchsia.logger.LogSink"}},
                       .source = ParentRef(),
                       .targets = {ChildRef{"echo_server"}, ChildRef{"echo_client"}}});

Rust

let realm = builder.build().await?;

C++

auto realm = builder.Build(dispatcher());

Rust

let echo = realm.root.connect_to_protocol_at_exposed_dir::<fecho::EchoMarker>()?;
assert_eq!(echo.echo_string(Some("hello")).await?, Some("hello".to_owned()));

建議：在每次測試結束時對運作範圍執行個體呼叫 destroy()，以確保下一個測試案例前可拆除。

不建議：等待領域物件超出範圍，指示元件管理服務刪除領域及其子項。

C++

auto echo = realm.component().ConnectSync<fidl::examples::routing::echo::Echo>();
fidl::StringPtr response;
echo->EchoString("hello", &response);
ASSERT_EQ(response, "hello");

當領域物件超出範圍時，元件管理服務會刪除領域及其子項。

Rust

let mut root_decl = builder.get_realm_decl().await?;
// root_decl is mutated in whatever way is needed
builder.replace_realm_decl(root_decl).await?;

let mut a_decl = builder.get_component_decl("a").await?;
// a_decl is mutated in whatever way is needed
builder.replace_component_decl("a", a_decl).await?;

C++

auto root_decl = realm_builder.GetRealmDecl();
// ... root_decl is mutated as needed
realm_builder.ReplaceRealmDecl(std::move(root_decl));

auto a_decl = realm_builder.GetComponentDecl("a");
// ... a_decl is mutated as needed
realm_builder.ReplaceComponentDecl(std::move(a_decl));

Rust

println!("Child Name: {}", realm.root.child_name());

C++

std::cout << "Child Name: " << realm.component().GetChildName() << std::endl;