Project: /_project.yaml Book: /_book.yaml

fuchsia.modular.testing

PROTOCOLS

TestHarness {:#TestHarness}

Defined in fuchsia.modular.testing/test_harness.fidl

The TestHarness service is used to run the modular runtime under a hermetic environment and drive integration tests under it. Tests may use this service to intercept components and assume their role. Additionally, tests may use TestHarness/ConnectToModularService() to get capabilities for controlling stories (using PuppetMaster) and connecting to agents (using ComponentContext).

Closing the TestHarness connection will kill the TestHarness environment including the modular runtime running under it.

On error, this connection is closed with the following epitaphs:

  • ZX_ERR_INVALID_ARGS: Run() failed to execute succesfully.
  • ZX_ERR_BAD_STATE: Other methods are called before Run() is called.
  • ZX_ERR_ALREADY_BOUND: Run() was already called.
  • ZX_ERR_ALREADY_EXISTS: The same environment service is being provided twice.

Run {:#Run}

Initializes an instance of the modular runtime in an enclosed environment, configured with parameters provided in spec. Closing the TestHarness connection will kill the enclosed environment.

This protocol connection is closed if Run() fails, with the following epitaphs:

  • ZX_ERR_INVALID_ARGS: spec is mal-formed.
  • ZX_ERR_ALREADY_EXISTS: The same environment service is being provided twice in spec.env_services
  • ZX_ERR_ALREADY_BOUND: Run() was already called.

Request

OnNewComponent {:#OnNewComponent}

This event is sent when a component specified in TestHarnessSpec.components_to_intercept is created. startup_info.launch_info.url contains the component URL.

Closing intercepted_component will signal to the component manager that this component has exited unexpectedly. Prefer to use InterceptedComponent/Exit to provide exit code and reason.

Response

ConnectToModularService {:#ConnectToModularService}

Tests may use this method to connect to services provided by the modular runtime. These services share the same component namespace for any resources they create (e.g., entities, message queues, and module names).

This protocol connection is closed with the following epitaphs:

  • ZX_ERR_BAD_STATE: if ConnectToModularService() is called before Run().
  • ZX_ERR_INVALID_ARGS: if service is not set to a value.

Request

ConnectToEnvironmentService {:#ConnectToEnvironmentService}

Connects to environment services injected into the TestHarness environment.

Request

ParseConfig {:#ParseConfig}

Parses a modular configuration from string into BasemgrConfig and SessionmgrConfig

Request

Response

InterceptedComponent {:#InterceptedComponent}

Defined in fuchsia.modular.testing/test_harness.fidl

InterceptedComponent represents an intercepted component's lifecycle. Closing this connection causes the component to be killed, and is equivalent in behaviour to the ComponentController being closed.

Exit {:#Exit}

Signals that component has exit'd with the specified exit code. The values here are bubbled up to the fuchsia.sys.ComponentController.OnTerminated event. The OnKill event is sent, and this InterceptedComponent handle is closed.

Request

OnKill {:#OnKill}

The event is sent when the component is killed by the associated fuchsia.sys.ComponentController, or when Exit() is called.

Response

STRUCTS

ComponentService {:#ComponentService}

Defined in fuchsia.modular.testing/test_harness.fidl

Describes a service to be provided by a component instance.

TABLES

TestHarnessSpec {:#TestHarnessSpec}

Defined in fuchsia.modular.testing/test_harness.fidl

Defines the setup of an environment running an instance of the modular framework used for testing purposes. This table is supplied to TestHarness.Run(). A malformed TestHarnessSpec will cause TestHarness connection to close with an epitaph of ZX_ERR_INVALID_ARGS.

By default, the following services are made available to the hermetic environment:

  • fuchsia.auth.account.AccountManager
  • fuchsia.devicesettings.DeviceSettingsManager

Additional services may be supplied using using TestHarnessSpec.env_services_to_inherit and TestHarnessSpec.injected_services. Additional services override the default services listed above.

The test harness will amend basemgr_config before passing it off to the modular runtime in the following way:

  • If basemgr_config.base_shell.app_config.url is not set, the test harness will use a base shell which automatically logs into the session.
  • If basemgr_config.session_shell_map[0].config.app_config.url is not set, the test harness will use a shell which automatically starts new stories.
  • If basemgr_config.story_shell.app_config.url is not set, the test harness use a minimally functioning story shell which displays all mods in a story.

To intercept and mock the shells, users may provide fake URLs for the shells and specify that the fake URL be intercepted using components_to_intercept.

Optional.

Optional.

EnvironmentServicesSpec {:#EnvironmentServicesSpec}

Defined in fuchsia.modular.testing/test_harness.fidl

Options for configuring the test harness environment with services.

If the same service is provided in more than one place, TestHarness connection is closed with a ZX_ERR_ALREADY_EXISTS epitaph.

Optional.

Optional.

InterceptSpec {:#InterceptSpec}

Defined in fuchsia.modular.testing/test_harness.fidl

Describes a component to intercept. Malformed parameters result in closing TestHarness with a ZX_ERR_INVALID_ARGS epitaph.

extra_cmx_contents must be a valid .cmx JSON. Example:

{ “sandbox”: { “services”: [ “fuchsia.sys.Launcher”, ] } }

XUNIONS

ModularService {:#ModularService}

Defined in fuchsia.modular.testing/test_harness.fidl

Describes which service to connect to using ConnectToModularService().