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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
name	fuchsia.component/child_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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
name	fuchsia.component/child_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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
name	fuchsia.component/child_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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
name	fuchsia.component/child_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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

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.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
name	fuchsia.component/child_name

Response

Name	Type
result	Realm_GetComponentDecl_Result

GetRealmDecl

Returns the component decl for this realm.

Errors:

• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

<EMPTY>

Response

Name	Type
result	Realm_GetRealmDecl_Result

ReadOnlyDirectory

Offers a directory capability to a component in this realm. The directory will be read-only (i.e. have r* rights), and will have the contents described in directory_contents.

Errors:

• NO_SUCH_TARGET: offer-to references a non-existent child.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
name	fuchsia.component/name
to	vector<fuchsia.component.decl/Ref>
directory_contents	DirectoryContents

Response

Name	Type
result	Realm_ReadOnlyDirectory_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.
• INVALID_COMPONENT_DECL: component_decl failed validation.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

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

Response

Name	Type
result	Realm_ReplaceComponentDecl_Result

ReplaceConfigValue

Replaces the configuration value for a field specified by key. The component specified should have a config schema with this field. The value must conform to all constraints as defined by the schema.

Errors:

• NO_CONFIG_SCHEMA: component does not have a config schema
• NO_SUCH_CONFIG_FIELD: key could not be found in component's config schema
• CONFIG_VALUE_INVALID: value does not meet config schema constraints

Request

Name	Type
name	fuchsia.component/name
key	fuchsia.component.decl/ConfigKey
value	fuchsia.component.config/ValueSpec

Response

Name	Type
result	Realm_ReplaceConfigValue_Result

ReplaceRealmDecl

Replaces the component decl for this realm.

Errors:

• INVALID_COMPONENT_DECL: component_decl failed validation.
• BUILD_ALREADY_CALLED: The Builder.Build function has been called for this realm, and thus this Realm channel can no longer be used.

Request

Name	Type
component_decl	fuchsia.component.decl/Component

Response

Name	Type
result	Realm_ReplaceRealmDecl_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

Name	Type
result	RealmBuilderFactory_Create_Result

CreateFromRelativeUrl

Identical to Create, but instead of the realm being empty by default it contains the contents of the manifest located at relative_url within pkg_dir_handle.

Request

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

Response

Name	Type
result	RealmBuilderFactory_CreateFromRelativeUrl_Result

STRUCTS

Builder_Build_Response

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
root_component_url	string[4096]		No default

DirectoryContents resource

Defined in fuchsia.component.test/realm_builder.fidl

The contents of a directory that should be provided by the realm builder server.

Field	Type	Description	Default
entries	vector<DirectoryEntry>[1024]		No default

DirectoryEntry resource

Defined in fuchsia.component.test/realm_builder.fidl

Field	Type	Description	Default
file_path	fuchsia.component/name	The path to the file. Valid examples include foo.txt and foo/bar.json.	No default
file_contents	fuchsia.mem/Buffer	The contents of the file.	No default

RealmBuilderFactory_CreateFromRelativeUrl_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

RealmBuilderFactory_Create_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

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_GetRealmDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

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

Realm_ReadOnlyDirectory_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_ReplaceComponentDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_ReplaceConfigValue_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

Realm_ReplaceRealmDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

<EMPTY>

ENUMS

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.
URL_IS_NOT_RELATIVE	16	The URL provided to RealmBuilderFactory.CreateFromRelativeURL is not a relative URL.
INVALID_PKG_DIR_HANDLE	17	The handle the client provided for the test's pkg directory is not usable.
NO_CONFIG_SCHEMA	18	The component does not have a config schema defined. Attempting to set a config value is not allowed.
NO_SUCH_CONFIG_FIELD	19	The component's config schema does not have a field with that name.
CONFIG_VALUE_INVALID	20	A config value is invalid. This may mean a type mismatch or an issue with constraints like string/vector length.

TABLES

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	subdir	string[1024]
5	rights	fuchsia.io/Rights
6	path	string[1024]

Event

Defined in fuchsia.component.test/realm_builder.fidl

An event capability

Ordinal	Field	Type	Description
1	name	fuchsia.component/name
2	as	fuchsia.component/name
3	filter	fuchsia.data/Dictionary

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
4	path	string[1024]

Service

Defined in fuchsia.component.test/realm_builder.fidl

A service capability

Ordinal	Field	Type	Description
1	name	fuchsia.component/name
2	as	fuchsia.component/name
3	path	string[1024]

Storage

Defined in fuchsia.component.test/realm_builder.fidl

A storage capability

Ordinal	Field	Type	Description
1	name	fuchsia.component/name
2	as	fuchsia.component/name
3	path	fuchsia.component/name

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

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
3	storage	Storage
4	service	Service
5	event	Event

RealmBuilderFactory_CreateFromRelativeUrl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal	Variant	Type	Description
1	response	RealmBuilderFactory_CreateFromRelativeUrl_Response
2	err	RealmBuilderError2

RealmBuilderFactory_Create_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal	Variant	Type	Description
1	response	RealmBuilderFactory_Create_Response
2	err	RealmBuilderError2

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_GetRealmDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal	Variant	Type	Description
1	response	Realm_GetRealmDecl_Response
2	err	RealmBuilderError2

Realm_ReadOnlyDirectory_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal	Variant	Type	Description
1	response	Realm_ReadOnlyDirectory_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

Realm_ReplaceConfigValue_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal	Variant	Type	Description
1	response	Realm_ReplaceConfigValue_Response
2	err	RealmBuilderError2

Realm_ReplaceRealmDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal	Variant	Type	Description
1	response	Realm_ReplaceRealmDecl_Response
2	err	RealmBuilderError2

CONSTANTS

Name	Value	Type	Description
LOCAL_COMPONENT_NAME_KEY	LOCAL_COMPONENT_NAME	String
MAX_DIRECTORY_ENTRIES	1024	uint32