Struct fuchsia_component_test::RealmBuilder

pub struct RealmBuilder { /* private fields */ }

The RealmBuilder struct can be used to assemble and create a component realm at runtime. For more information on what can be done with this struct, please see the documentation on fuchsia.dev

Implementations

impl RealmBuilder

pub async fn new() -> Result<Self, Error>

Creates a new, empty Realm Builder.

pub async fn with_params(params: RealmBuilderParams) -> Result<Self, Error>

pub async fn initialize(self) -> Result<(String, Task<()>), Error>

Initializes the realm, but doesn’t create it. Returns the root URL and the task managing local component implementations. The caller should pass the URL into fuchsia.component.Realm#CreateChild, and keep the task alive until after fuchsia.component.Realm#DestroyChild has been called.

pub async fn build(self) -> Result<RealmInstance, Error>

Creates this realm in a child component collection. By default this happens in the DEFAULT_COLLECTION_NAME collection with an autogenerated name for the instance.

Also by default, after creation it starts the child component by connecting to the fuchsia.component.Binder protocol exposed from the root realm, which gets added automatically by the server.

pub async fn with_nested_component_manager( self, component_manager_fragment_only_url: &str ) -> Result<(RealmBuilder, Task<()>), Error>

Initializes the created realm under an instance of component manager, specified by the given fragment-only URL. Returns the realm containing component manager.

This function should be used to modify the component manager realm. Otherwise, to directly build the created realm under an instance of component manager, use build_in_nested_component_manager().

Note that any routes with a source of parent in the root realm will need to also be used in component manager’s manifest and listed in namespace_capabilities in the config file passed to component_manager’s --config arg.

Note that any routes with a target of parent from the root realm will result in exposing the capability to component manager, which is rather useless by itself. Component manager does expose the hub though, which could be traversed to find an exposed capability.

Note that the returned fuchsia_async::Task must be kept alive until realm teardown.

pub async fn build_in_nested_component_manager( self, component_manager_fragment_only_url: &str ) -> Result<RealmInstance, Error>

Launches a nested component manager which will run the created realm (along with any local components in the realm). This component manager must be referenced by a fragment-only URL.

Note that any routes with a source of parent in the root realm will need to also be used in component manager’s manifest and listed in namespace_capabilities in the config file passed to component_manager’s --config arg.

Note that any routes with a target of parent from the root realm will result in exposing the capability to component manager, which is rather useless by itself. Component manager does expose the hub though, which could be traversed to find an exposed capability.

pub async fn add_child_realm( &self, name: impl Into<String>, options: ChildOptions ) -> Result<SubRealmBuilder, Error>

pub async fn add_local_child( &self, name: impl Into<String>, local_component_implementation: impl Fn(LocalComponentHandles) -> BoxFuture<'static, Result<(), Error>> + Sync + Send + 'static, options: ChildOptions ) -> Result<ChildRef, Error>

Adds a new component with a local implementation to the realm

pub async fn add_child( &self, name: impl Into<String>, url: impl Into<String>, options: ChildOptions ) -> Result<ChildRef, Error>

Adds a new component to the realm by URL

pub async fn add_child_from_decl( &self, name: impl Into<String>, decl: ComponentDecl, options: ChildOptions ) -> Result<ChildRef, Error>

Adds a new component to the realm with the given component declaration

pub async fn get_component_decl( &self, name: impl Into<ChildRef> ) -> Result<ComponentDecl, Error>

Returns a copy of the decl for a child in this realm. This operation is only supported for:

• A component with a local implementation
• A component added with a fragment-only component URL (typically, components bundled in the same package as the realm builder client, sharing the same /pkg directory, for example, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only).
• An automatically generated realm (such as the root)

pub async fn replace_component_decl( &self, name: impl Into<ChildRef>, decl: ComponentDecl ) -> Result<(), Error>

Replaces the decl for a child of this realm. This operation is only supported for:

• A component with a local implementation
• A component added with a fragment-only component URL (typically, components bundled in the same package as the realm builder client, sharing the same /pkg directory, for example, #meta/other-component.cm; see https://fuchsia.dev/fuchsia-src/reference/components/url#relative-fragment-only).
• An automatically generated realm (such as the root)

pub async fn get_realm_decl(&self) -> Result<ComponentDecl, Error>

Returns a copy the decl for this realm

pub async fn replace_realm_decl(&self, decl: ComponentDecl) -> Result<(), Error>

Replaces the decl for this realm

pub async fn add_route(&self, route: Route) -> Result<(), Error>

Adds a route between components within the realm

pub async fn init_mutable_config_from_package( &self, name: impl Into<ChildRef> ) -> Result<(), Error>

Load the component’s structured config values from its package before applying overrides.

pub async fn init_mutable_config_to_empty( &self, name: impl Into<ChildRef> ) -> Result<(), Error>

Allow setting config values without loading any packaged values first.

pub async fn set_config_value( &self, name: impl Into<ChildRef>, key: &str, value: ConfigValue ) -> Result<(), Error>

Replaces a value of a given configuration field

pub async fn read_only_directory( &self, directory_name: impl Into<String>, to: Vec<impl Into<Ref>>, directory_contents: DirectoryContents ) -> Result<(), Error>

Creates and routes a read-only directory capability to the given targets. The directory capability will have the given name, and anyone accessing the directory will see the given contents.

pub async fn add_capability( &self, capability: CapabilityDecl ) -> Result<(), Error>

Adds a Capability to the root realm.

Trait Implementations

impl Debug for RealmBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.