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

NameType
runner fuchsia.component.runner/ComponentRunner

Response

NameType
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

NameType
name fuchsia.component/name
url fuchsia.url/Url
options ChildOptions

Response

NameType
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

NameType
name fuchsia.component/name
decl fuchsia.component.decl/Component
options ChildOptions

Response

NameType
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

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

Response

NameType
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

NameType
name fuchsia.component/name
legacy_url fuchsia.url/Url
options ChildOptions

Response

NameType
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

NameType
name fuchsia.component/name
options ChildOptions

Response

NameType
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

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

Response

NameType
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

NameType
name fuchsia.component/name

Response

NameType
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

NameType
name fuchsia.component/name
component_decl fuchsia.component.decl/Component

Response

NameType
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

NameType
result RealmBuilder_Commit_Result

Contains

Returns true if the component exists in this realm.

Request

NameType
moniker string[4096]

Response

NameType
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

NameType
moniker string[4096]

Response

NameType
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

NameType
pkg_dir_handle fuchsia.io/Directory

Response

NameType
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

NameType
moniker string[4096]

Response

NameType
result RealmBuilder_MarkAsEager_Result

OnMockRunRequest

The component framework is requesting that a mock component start running

Response

NameType
mock_id string[1000]
start_info MockComponentStartInfo

OnMockStopRequest

The component framework is requesting that a mock component stop running

Response

NameType
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

NameType
route CapabilityRoute

Response

NameType
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

NameType
moniker string[4096]
component Component

Response

NameType
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

NameType
moniker string[4096]

Response

NameType
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

NameType
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

FieldTypeDescriptionDefault
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

FieldTypeDescriptionDefault
root_component_url string[4096] No default

RealmBuilder_GetComponentDecl_Response

Defined in fuchsia.component.test/realm_builder.fidl

FieldTypeDescriptionDefault
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

FieldTypeDescriptionDefault
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

FieldTypeDescriptionDefault
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

NameValueDescription
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.

NameValueDescription
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.

OrdinalFieldTypeDescription
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

OrdinalFieldTypeDescription
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

OrdinalFieldTypeDescription
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

OrdinalFieldTypeDescription
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.

OrdinalFieldTypeDescription
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

OrdinalFieldTypeDescription
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

OrdinalFieldTypeDescription
1 name string[100]

ServiceCapability

Defined in fuchsia.component.test/realm_builder.fidl

A service capability

OrdinalFieldTypeDescription
1 name string[100]

StorageCapability

Defined in fuchsia.component.test/realm_builder.fidl

A storage capability

OrdinalFieldTypeDescription
1 name string[100]
2 path string[1024]

UNIONS

Builder_Build_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Builder_Build_Response
2 err RealmBuilderError2

Capability flexible

Defined in fuchsia.component.test/realm_builder.fidl

A capability to be routed

Ordinal
VariantTypeDescription
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
VariantTypeDescription
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
VariantTypeDescription
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
VariantTypeDescription
1 response RealmBuilder_Commit_Response
2 err RealmBuilderError

RealmBuilder_GetComponentDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response RealmBuilder_GetComponentDecl_Response
2 err RealmBuilderError

RealmBuilder_Init_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response RealmBuilder_Init_Response
2 err RealmBuilderError

RealmBuilder_MarkAsEager_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response RealmBuilder_MarkAsEager_Response
2 err RealmBuilderError

RealmBuilder_RouteCapability_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response RealmBuilder_RouteCapability_Response
2 err RealmBuilderError

RealmBuilder_SetComponent_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response RealmBuilder_SetComponent_Response
2 err RealmBuilderError

RealmBuilder_SetMockComponent_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response RealmBuilder_SetMockComponent_Response
2 err RealmBuilderError

Realm_AddChildFromDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_AddChildFromDecl_Response
2 err RealmBuilderError2

Realm_AddChildRealm_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_AddChildRealm_Response
2 err RealmBuilderError2

Realm_AddChild_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_AddChild_Response
2 err RealmBuilderError2

Realm_AddLegacyChild_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_AddLegacyChild_Response
2 err RealmBuilderError2

Realm_AddLocalChild_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_AddLocalChild_Response
2 err RealmBuilderError2

Realm_AddRoute_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_AddRoute_Response
2 err RealmBuilderError2

Realm_GetComponentDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
1 response Realm_GetComponentDecl_Response
2 err RealmBuilderError2

Realm_ReplaceComponentDecl_Result strict

Defined in fuchsia.component.test/realm_builder.fidl

Ordinal
VariantTypeDescription
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
VariantTypeDescription
1 component string[1024]
2 above_root AboveRoot
3 debug Debug

CONSTANTS

NameValueTypeDescription
MAX_LEN_ROUTE_ENDPOINTS 100 uint32
MAX_MOCK_ID_LENGTH 1000 uint32