fuchsia.component.test

PROTOCOLS

Builder

Defined in fuchsia.component.test/realm_builder.fidl

Build

Assembles the realm being constructed and returns the URL for the root component in the realm, which may then be used to create a new component in any collection where fuchsia-test-component is properly set up. Once this is called, any Realm channels for the realm will no longer be usable. The runner argument must be provided if the AddLocalChild function has been used in this realm, as this runner channel will be used to inform the client when to start and stop running any local component implementations.

Errors:

• INVALID_COMPONENT_DECL: A component declaration failed validaiton.
• BUILD_ALREADY_CALLED: The Build function has been called multiple times on this channel.

Request

Name	Type
runner	fuchsia.component.runner/ComponentRunner

Response

Name	Type
result	Builder_Build_Result

Realm

Defined in fuchsia.component.test/realm_builder.fidl

AddChild

Adds a component to the realm.

Errors:

• CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
• INVALID_MANIFEST_EXTENSION: url ends with .cmx, and thus should be used with AddLegacyChild instead of AddChild.
• DECL_NOT_FOUND: The test package does not contain the component declaration referenced by a relative URL.
• DECL_READ_ERROR: Encountered an I/O error when attempting to read a component declaration referenced by a relative URL from the test package.

Request

Name	Type
name	fuchsia.component/name
url	fuchsia.url/Url
options	ChildOptions

Response

Name	Type
result	Realm_AddChild_Result

AddChildFromDecl

Adds a component to this realm whose declaration is set to decl. When launched, the component will share the test package as its package directory, and may access any resources from it.

Errors:

• CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
• INVALID_COMPONENT_DECL: decl failed validation.

Request

Name	Type
name	fuchsia.component/name
decl	fuchsia.component.decl/Component
options	ChildOptions

Response

Name	Type
result	Realm_AddChildFromDecl_Result

AddChildRealm

Adds a child realm which can be built with the client end of child_realm.

Errors:

• CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.

Request

Name	Type
name	fuchsia.component/name
options	ChildOptions
child_realm	request<Realm>

Response

Name	Type
result	Realm_AddChildRealm_Result

AddLegacyChild

Adds a legacy component to the realm. When the component is launched, RealmBuilder will reach out to appmgr to assist with launching the component, and the component will be able to utilize all of the features of the legacy component framework. Note that only protocol capabilities may be routed to this component. Capabilities of any other type (such as a directory) are unsupported for legacy components launched by RealmBuilder, and this legacy component should instead use the CMX features to access things such as storage.

Errors:

• CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.
• INVALID_MANIFEST_EXTENSION: url does not end with .cmx, and thus should be used with AddChild instead of AddLegacyChild.

Request

Name	Type
name	fuchsia.component/name
legacy_url	fuchsia.url/Url
options	ChildOptions

Response

Name	Type
result	Realm_AddLegacyChild_Result

AddLocalChild

Adds a component to the realm whose implementation will be provided by the client. When this component should be started, the runner channel passed into Build will receive a start request for a component whose ProgramDecl contains the relative moniker from the root of the constructed realm for the child that is to be run under the program key LOCAL_COMPONENT_NAME.

Errors:

• CHILD_ALREADY_EXISTS: this realm already contains a child with the given name.

Request

Name	Type
name	fuchsia.component/name
options	ChildOptions

Response

Name	Type
result	Realm_AddLocalChild_Result

AddRoute

Mutates component manifests in the realm such that every component in to will have a valid capability route for each item in capabilities provided by from.

Errors:

• NO_SUCH_SOURCE: from references a non-existent child.
• NO_SUCH_TARGET: to references a non-existent child.
• CAPABILITIES_EMPTY: capabilities is empty.
• TARGETS_EMPTY: to is empty.
• SOURCE_AND_TARGET_MATCH: from is equal to one of the elements in to.
• INVALID_COMPONENT_DECL: The requested route caused one of the involved manifests to fail validation.

Request

Name	Type
capabilities	vector<Capability2>
from	fuchsia.component.decl/Ref
to	vector<fuchsia.component.decl/Ref>

Response

Name	Type
result	Realm_AddRoute_Result

GetComponentDecl

Returns the component decl for the given component. name must refer to a component that is one of the following:

• A component with a local implementation
• A legacy component
• A component added with a relative URL
• An automatically generated realm (ex: the root)

Errors:

• NO_SUCH_CHILD: This realm does not contain a child with the given name.
• CHILD_DECL_NOT_VISIBLE: The component decl cannot be fetched for the referenced child, because the child was added to the realm using an absolute (not-relative) and modern (not legacy) URL.

Request

Name	Type
name	fuchsia.component/name

Response

Name	Type
result	Realm_GetComponentDecl_Result

ReplaceComponentDecl

Replaces the component decl for the given component. name must refer to a component that is one of the following:

• A component with a local implementation
• A legacy component
• A component added with a relative URL
• An automatically generated realm (ex: the root)

Errors:

• NO_SUCH_CHILD: This realm does not contain a child with the given name.
• CHILD_ALREADY_EXISTS: The component whose decl is being replaced has had a child added to it through realm builder with the same name as an element in component_decl.children.
• CHILD_DECL_NOT_VISIBLE: The component decl cannot be manipulated for the referenced child, because the child was added to the realm using an absolute (not relative) and modern (not legacy) URL.

Request

Name	Type
name	fuchsia.component/name
component_decl	fuchsia.component.decl/Component

Response

Name	Type
result	Realm_ReplaceComponentDecl_Result

RealmBuilder

Defined in fuchsia.component.test/realm_builder.fidl

This stateful protocol can be used to construct a new component realm at runtime. This new realm is built iteratively by calling the methods on this protocol to add new components and capability routes between them. Due to the stateful nature of this protocol, one realm may be constructed per connection.

Once the realm details are successfully processed, Commit should be called to produce a URL which can be used to create the component.

Commit

Assembles the realm being constructed and returns the URL for the root component in the realm, which may then be used to create a new component in any collection where fuchsia-test-component is properly set up.

Request

<EMPTY>

Response

Name	Type
result	RealmBuilder_Commit_Result

Contains

Returns true if the component exists in this realm.

Request

Name	Type
moniker	string[4096]

Response

Name	Type
exists	bool

GetComponentDecl

Returns the current value of a component decl in the realm being constructed. Note that this cannot retrieve decls through external URLs, so for example if SetComponent is called with Component::url and then GetComponentDecl is called with the same moniker, an error will be returned.

Request

Name	Type
moniker	string[4096]

Response

Name	Type
result	RealmBuilder_GetComponentDecl_Result

Init

Initializes this connection to the framework intermediary. This function should be called at the stat of every new RealmBuilder connection, with the pkg_dir_handle argument providing a connection to the test's package with rx* permissions. Components that are added with a relative URL are loaded from this directory handle. If this call is not made, any call to SetComponent with a relative URL will return an error.

Request

Name	Type
pkg_dir_handle	fuchsia.io/Directory

Response

Name	Type
result	RealmBuilder_Init_Result

MarkAsEager

Marks the component and any ancestors of it as eager, ensuring that the component is started immediately once the realm is bound to.

Request

Name	Type
moniker	string[4096]

Response

Name	Type
result	RealmBuilder_MarkAsEager_Result

OnMockRunRequest

The component framework is requesting that a mock component start running

Response

Name	Type
mock_id	string[1000]
start_info	MockComponentStartInfo

OnMockStopRequest

The component framework is requesting that a mock component stop running

Response

Name	Type
mock_id	string[1000]

RouteCapability

Adds a capability route to the realm being constructed, adding any necessary offers, exposes, uses, and capability declarations to any component involved in the route. Note that components added with Component::url can not be modified, and they are presumed to already have the declarations needed for the route to be valid. If an error is returned some of the components in the route may have been updated while others were not.

Request

Name	Type
route	CapabilityRoute

Response

Name	Type
result	RealmBuilder_RouteCapability_Result

SetComponent

Sets the component to the provided component source. If the source is a Component::decl then a new node is added to the internal tree structure maintained for this connection. If the source is a Component::url then a new ChildDecl is added to the parent of the moniker. If any parents for the component do not exist then they are added. If a different component already exists under this moniker, then it is replaced.

Request

Name	Type
moniker	string[4096]
component	Component

Response

Name	Type
result	RealmBuilder_SetComponent_Result

SetMockComponent

Sets the component to be a mock component. A new Component decl is generated for the component, and assigned a new mock id. This id is returned by this function, and when the mock component should start running a new OnMockRunRequest is issued with this same id.

Request

Name	Type
moniker	string[4096]

Response

Name	Type
result	RealmBuilder_SetMockComponent_Result

RealmBuilderFactory

Defined in fuchsia.component.test/realm_builder.fidl

This protocol can be used to instruct the Realm Builder Server to begin creating a new realm.

Create

Creates a new RealmBuilder. The client end of realm_server_end can be used to mutate the realm that is being constructed, by doing things such as adding new children to the realm or adding capability routes between them. The client end of builder_server_end is used to finalize the realm, after which point it can be launched in a collection.

Request

Name	Type
pkg_dir_handle	fuchsia.io/Directory
realm_server_end	request<Realm>
builder_server_end	request<Builder>

Response

<EMPTY>

STRUCTS

AboveRoot

Defined in fuchsia.component.test/realm_builder.fidl

The capability route's endpoint exists above the constructed realm, and is offered to the realm's collection or will be accessed by the parent using fuchsia.component#Realm.

<EMPTY>

Builder_Build_Response

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
root_component_url	string[4096]		No default

Debug

Defined in fuchsia.component.test/realm_builder.fidl

The capability route's endpoint exists in the environment and is offered as "debug".

<EMPTY>

RealmBuilder_Commit_Response

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
root_component_url	string[4096]		No default

RealmBuilder_GetComponentDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
component_decl	fuchsia.component.decl/Component		No default

RealmBuilder_Init_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

RealmBuilder_MarkAsEager_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

RealmBuilder_RouteCapability_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

RealmBuilder_SetComponent_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

RealmBuilder_SetMockComponent_Response

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
mock_id	string[1000]		No default

Realm_AddChildFromDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_AddChildRealm_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_AddChild_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_AddLegacyChild_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_AddLocalChild_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_AddRoute_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_GetComponentDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
component_decl	fuchsia.component.decl/Component		No default

Realm_ReplaceComponentDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

ENUMS

RealmBuilderError strict

Type: uint32

Defined in fuchsia.component.test/realm_builder.fidl

Name	Value	Description
NODE_BEHIND_CHILD_DECL	0	An attempt was made to interact with a component declaration for a component which is located behind a child declaration, and is thus not directly available to RealmBuilder.
NO_SUCH_CHILD	1	An attempt was made to retrieve a child of a component which does not exist.
ROOT_CANNOT_BE_SET_TO_URL	2	The root component cannot have a URL-based source.
ROOT_CANNOT_BE_EAGER	3	The root component cannot be marked as eager.
BAD_FIDL	4	RealmBuilder failed to parse the FIDL from one of the arguments.
MISSING_FIELD	5	A required field was missing in the input.
ROUTE_TARGETS_EMPTY	6	The set of targets for a route is not allowed to be empty.
MISSING_ROUTE_SOURCE	7	The source for the route does not exist.
MISSING_ROUTE_TARGET	8	A target for the route does not exist.
ROUTE_SOURCE_AND_TARGET_MATCH	9	A target for the route is equal to the source, and it is impossible to route a component's capability to itself.
VALIDATION_ERROR	10	A component manifest has failed validation.
UNABLE_TO_EXPOSE	11	The requested route is impossible because the capability type cannot be exposed.
STORAGE_SOURCE_INVALID	12	The source of the route is invalid because currently "above root" is the only supported source for storage capabilities.
MONIKER_NOT_FOUND	13	There is no component in this realm with the given moniker.
PKG_DIR_ALREADY_SET	14	The package directory has already been set for this connection.
PKG_DIR_NOT_SET	15	Unable to load component from package, the package dir is not set.
PKG_DIR_IO_ERROR	16	Failed to load component from package due to IO error.
FAILED_TO_LOAD_COMPONENT_DECL	17	Failed to load the component decl.
INVALID_CAPABILITY_FROM_DEBUG	18	An invalid capability was requested from the "debug" route endpoint. Only protocols may be requested from the "debug" route endpoint in RealmBuilder.

RealmBuilderError2 strict

Type: uint32

Defined in fuchsia.component.test/realm_builder.fidl

Errors that may be returned by the Realm and Builder protocols.

Will be renamed to RealmBuilderError once the other definition under this name earlier in this file is removed.

Name	Value	Description
CHILD_ALREADY_EXISTS	0	Child cannot be added to the realm, as there is already a child in the realm with that name.
INVALID_MANIFEST_EXTENSION	1	A legacy component URL was given to AddChild, or a modern component url was given to AddLegacyChild.
INVALID_COMPONENT_DECL	2	A component declaration failed validation.
NO_SUCH_CHILD	3	The referenced child does not exist.
CHILD_DECL_NOT_VISIBLE	4	The component declaration for the referenced child cannot be viewed nor manipulated by RealmBuilder, because the child was added to the realm using an URL that was neither a relative nor a legacy URL.
NO_SUCH_SOURCE	5	The source does not exist.
NO_SUCH_TARGET	6	A target does not exist.
CAPABILITIES_EMPTY	7	The capabilities field is empty.
TARGETS_EMPTY	8	The targets field is empty.
SOURCE_AND_TARGET_MATCH	9	The from value is equal to one of the elements in to.
DECL_NOT_FOUND	10	The test package does not contain the component declaration referenced by a relative URL.
DECL_READ_ERROR	11	Encountered an I/O error when attempting to read a component declaration referenced by a relative URL from the test package.
BUILD_ALREADY_CALLED	12	The Build function has been called multiple times on this channel.
CAPABILITY_INVALID	13	A capability is invalid. This may occur if a required field is empty or if an unsupported type is received.
INVALID_CHILD_REALM_HANDLE	14	The handle the client provided for the child realm is not usable
IMMUTABLE_PROGRAM	15	ReplaceComponentDecl was called on a legacy or local component with a program declaration that did not match the one from the old component declaration. This could render a legacy or local component non-functional, and is disallowed.

TABLES

CapabilityRoute

Defined in fuchsia.component.test/realm_builder.fidl

A capability route, denoting where a capability comes from and where it goes to.

Ordinal	Field	Type	Description
1	capability	Capability	The capability to route
2	source	RouteEndpoint	Where the capability comes from
3	targets	vector<RouteEndpoint>[100]	Where the capability goes to
4	force_route	bool	If true any components loaded in from the package will be modified as needed to make the route valid. If false the package-local components will not be modified.

ChildOptions

Defined in fuchsia.component.test/realm_builder.fidl

Properties that may be set on a child when it is added to a realm

Ordinal	Field	Type	Description
1	startup	fuchsia.component.decl/StartupMode
2	environment	fuchsia.component/name
3	on_terminate	fuchsia.component.decl/OnTerminate

Directory

Defined in fuchsia.component.test/realm_builder.fidl

A directory capability

Ordinal	Field	Type	Description
1	name	fuchsia.component/name
2	as	fuchsia.component/name
3	type	fuchsia.component.decl/DependencyType
4	rights	fuchsia.io2/Rights
5	subdir	string[1024]

DirectoryCapability

Defined in fuchsia.component.test/realm_builder.fidl

A directory capability

Ordinal	Field	Type	Description
1	name	string[100]
2	path	string[1024]
3	rights	fuchsia.io2/Rights

MockComponentStartInfo resource

Defined in fuchsia.component.test/realm_builder.fidl

The handles a mock component uses to consume capabilities from and provide capabilities to the framework.

Ordinal	Field	Type	Description
1	ns	vector<fuchsia.component.runner/ComponentNamespaceEntry>[32]
2	outgoing_dir	request<fuchsia.io/Directory>

Protocol

Defined in fuchsia.component.test/realm_builder.fidl

A protocol capability

Ordinal	Field	Type	Description
1	name	fuchsia.component/name
2	as	fuchsia.component/name
3	type	fuchsia.component.decl/DependencyType

ProtocolCapability

Defined in fuchsia.component.test/realm_builder.fidl

A protocol capability

Ordinal	Field	Type	Description
1	name	string[100]

ServiceCapability

Defined in fuchsia.component.test/realm_builder.fidl

A service capability

Ordinal	Field	Type	Description
1	name	string[100]

StorageCapability

Defined in fuchsia.component.test/realm_builder.fidl

A storage capability

Ordinal	Field	Type	Description
1	name	string[100]
2	path	string[1024]

UNIONS

Builder_Build_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Builder_Build_Response
2	err	RealmBuilderError2

Capability flexible

Defined in fuchsia.component.test/realm_builder.fidl

A capability to be routed

Ordinal
Variant	Type	Description
1	protocol	ProtocolCapability
2	directory	DirectoryCapability
3	storage	StorageCapability
4	service	ServiceCapability

Capability2 flexible

Defined in fuchsia.component.test/realm_builder.fidl

A capability that can be routed around a realm using AddRoute.

Will be renamed to Capability once the other definition under this name earlier in this file is removed.

Ordinal
Variant	Type	Description
1	protocol	Protocol
2	directory	Directory

Component flexible

Defined in fuchsia.component.test/realm_builder.fidl

A component to be added to the realm, which is either a component declaration that RealmBuilder should provide or an external URL that should be referenced in a child decl.

Ordinal
Variant	Type	Description
1	decl	fuchsia.component.decl/Component
2	url	string[4096]
3	legacy_url	string[4096]

RealmBuilder_Commit_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_Commit_Response
2	err	RealmBuilderError

RealmBuilder_GetComponentDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_GetComponentDecl_Response
2	err	RealmBuilderError

RealmBuilder_Init_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_Init_Response
2	err	RealmBuilderError

RealmBuilder_MarkAsEager_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_MarkAsEager_Response
2	err	RealmBuilderError

RealmBuilder_RouteCapability_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_RouteCapability_Response
2	err	RealmBuilderError

RealmBuilder_SetComponent_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_SetComponent_Response
2	err	RealmBuilderError

RealmBuilder_SetMockComponent_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	RealmBuilder_SetMockComponent_Response
2	err	RealmBuilderError

Realm_AddChildFromDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_AddChildFromDecl_Response
2	err	RealmBuilderError2

Realm_AddChildRealm_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_AddChildRealm_Response
2	err	RealmBuilderError2

Realm_AddChild_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_AddChild_Response
2	err	RealmBuilderError2

Realm_AddLegacyChild_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_AddLegacyChild_Response
2	err	RealmBuilderError2

Realm_AddLocalChild_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_AddLocalChild_Response
2	err	RealmBuilderError2

Realm_AddRoute_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_AddRoute_Response
2	err	RealmBuilderError2

Realm_GetComponentDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_GetComponentDecl_Response
2	err	RealmBuilderError2

Realm_ReplaceComponentDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
Variant	Type	Description
1	response	Realm_ReplaceComponentDecl_Response
2	err	RealmBuilderError2

RouteEndpoint flexible

Defined in fuchsia.component.test/realm_builder.fidl

The endpoint of a capability route, describing either the provider or consumer of a capability.

Ordinal
Variant	Type	Description
1	component	string[1024]
2	above_root	AboveRoot
3	debug	Debug

CONSTANTS

Name	Value	Type	Description
MAX_LEN_ROUTE_ENDPOINTS	100	uint32
MAX_MOCK_ID_LENGTH	1000	uint32