Google is committed to advancing racial equity for Black communities. See how.

fuchsia.test.manager

PROTOCOLS

Harness

Defined in fuchsia.test.manager/test_manager.fidl

Launches a test that implements the fuchsia.test.Suite protocol (either directly or via a runner adapter). The test must be a v2 component test.

Designed to be used by run_test_suite to execute v2 tests.

If test suite doesn't expose fuchsia.test.Suite protocol, this call will suceed but call on suite protocol will fail with PEER_CLOSED error.

LaunchSuite

Request

NameType
test_url fuchsia.url/Url
options LaunchOptions
suite request<fuchsia.test/Suite>
controller request<LegacySuiteController>

Response

NameType
result Harness_LaunchSuite_Result

LegacySuiteController

Defined in fuchsia.test.manager/test_manager.fidl

Controller for running suite. Suite would be destroyed when client end of this protocol is closed. Note: Plan to deprecate and remove this as soon as all the clients are moved to new protocol.

Kill

Destroys running suite.

Request

NameType

RunBuilder

Defined in fuchsia.test.manager/test_manager.fidl

This is the entry point of running test suites. A test "run" consists of multiple test "suites" which consists of running multiple "test cases".

AddSuite

Add a suite to this run. A suite is a component that implements fuchsia.test.Suite. Implementors of this API will talk to test suites using "Suite" protocol and return results using controller. The controller is also used to control the execution of the test suite.

Request

NameType
test_url fuchsia.url/Url
options RunOptions
controller request<SuiteController>

Build

Build and schedule the run.

This runs all suites added with their respective filters and closes the channel once it is done.

Request

NameType
controller request<RunController>

RunController

Defined in fuchsia.test.manager/test_manager.fidl

The server end will disconnect after all the suite runs have finished and the events are drained. If the client disconnects, the tests will be terminated immediately and all results discarded.

GetEvents

Request

NameType

Response

NameType
events vector<RunEvent>

Kill

Immediately terminate the run. RunController will disconnect after all resources are released. This method will terminate tests even if they are in progress.

Request

NameType

Stop

Stop the run gracefully. RunController will disconnect after all resources are released and all the events in this controller are drained. This method is used to allow the run to complete tests that are in progress, but will prevent starting new tests.

Request

NameType

SuiteController

Defined in fuchsia.test.manager/test_manager.fidl

The server end will disconnect after all the suite run has finished and all events are drained. If the client disconnects, the suite will be terminated immediately and all results discarded.

GetEvents

Iterator over events for the run. This method is a hanging get; it returns an empty vector only when there will be no further events (the run completed).

Request

NameType

Response

NameType
result SuiteController_GetEvents_Result

Kill

Immediately terminate the run. SuiteController will disconnect after all resources are released. This method will terminate tests even if they are in progress.

Request

NameType

Stop

Stop the suite run gracefully. SuiteController will disconnect after all resources are released and all the events in this controller are drained.

Request

NameType

STRUCTS

CaseArtifact

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
identifier TestCaseId No default
artifact Artifact No default

CaseFinished

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
identifier TestCaseId No default

CaseFound

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
test_case_name CaseName

Name of this test case.

No default
identifier TestCaseId

Used to identify this test case in subsequent payloads

No default

CaseStarted

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
identifier TestCaseId No default

CaseStopped

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
identifier TestCaseId No default
status CaseStatus No default

Harness_LaunchSuite_Response

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault

Stderr

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
socket handle<socket> No default

Stdout

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
socket handle<socket> No default

SuiteArtifact

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
artifact Artifact No default

SuiteController_GetEvents_Response

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
events vector<SuiteEvent> No default

SuiteFinished

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescriptionDefault
status SuiteStatus No default

ENUMS

CaseStatus

Type: uint32

Defined in fuchsia.test.manager/test_manager.fidl

Represent status of a test case run execution.

NameValueDescription
PASSED 0

The test case passed.

FAILED 1

Test case failed.

TIMED_OUT 2

Test case timed out.

SKIPPED 3

Test case was skipped.

ERROR 4

Suite implementation did not return status.

LaunchError

Type: uint32

Defined in fuchsia.test.manager/test_manager.fidl

Error for LaunchSuite call.

NameValueDescription
RESOURCE_UNAVAILABLE 1

There were insufficient resources to perform the operation.

INSTANCE_CANNOT_RESOLVE 2

Cannot resolve test_url.

INVALID_ARGS 3

Invalid argument(s) passed.

FAILED_TO_CONNECT_TO_TEST_SUITE 4

Failed to connect to the fuchsia.test.TestSuite that the test should expose.

CASE_ENUMERATION 5

Failed to enumerate tests.

INTERNAL_ERROR 6

Some internal error occured. Something wrong with test manager setup. Check logs and report bug.

LogsIteratorOption

Type: uint32

Defined in fuchsia.test.manager/test_manager.fidl

Option which specifies which kind of iterator the client supports

NameValueDescription
BATCH_ITERATOR 0
ARCHIVE_ITERATOR 1

SuiteStatus

Type: uint32

Defined in fuchsia.test.manager/test_manager.fidl

Represents status of a suite run. This ordering is the explicit ordering of preference, from lowest priority to highest priority. for example, if all Cases PASSED except one that FAILED, the status for the whole suite will be FAILED.

NameValueDescription
PASSED 0

All tests cases passed/skipped.

FAILED 1

At least one test case in the suite failed.

DID_NOT_FINISH 3

Suite implementation crashed or did not send Finish event.

TIMED_OUT 4

At least one test case in the suite timed out.

STOPPED 5

The test suite was stopped.

INTERNAL_ERROR 6

TABLES

LaunchOptions

Defined in fuchsia.test.manager/test_manager.fidl

Options to run particular test suite.

OrdinalNameTypeDescription
1 logs_iterator LogsIterator

Isolated logs from the test component will be streamed through this iterator.

RunEvent

Defined in fuchsia.test.manager/test_manager.fidl

OrdinalNameTypeDescription

RunOptions

Defined in fuchsia.test.manager/test_manager.fidl

Optional additional instructions for executing a test suite.

OrdinalNameTypeDescription
1 run_disabled_tests bool

If set to true, test cases that have been disabled by the test author will nonetheless be executed. Defaults to false.

2 parallel uint16

Defines maximum number of test cases to run simultaneously. If unspecified, the default behavior is chosen by the Suite implementation.

3 arguments vector<string>

Optional arguments to pass to the test. Test runners will decide how to pass these arguments to tests.

4 timeout zx/duration

Timeout in seconds for the entire suite.

5 case_filters_to_run vector<string>

glob case filter. This filter will match based on glob pattern [https://en.wikipedia.org/wiki/Glob_(programming)]. All the filters are ORed. If passed in, only tests matching these filters would be executed. If not specified then all test cases will be admitted which is equivalent to specifying [ "*" ]

6 log_iterator LogsIteratorOption

Defines what kind of log iterator the client supports. Default value is Batch iterator.

SuiteEvent

Defined in fuchsia.test.manager/test_manager.fidl

OrdinalNameTypeDescription
1 timestamp zx/time
2 payload SuiteEventPayload

UNIONS

Artifact

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescription
stdout handle<socket>
stderr handle<socket>
log Syslog

Harness_LaunchSuite_Result

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescription
response Harness_LaunchSuite_Response
err LaunchError

LogsIterator

Defined in fuchsia.test.manager/test_manager.fidl

Holds the server end of an iterator over the isolated logs of a test.

NameTypeDescription
archive request<fuchsia.developer.remotecontrol/ArchiveIterator>

Server end of the iterator, when this protocol is used by host-side clients.

batch request<fuchsia.diagnostics/BatchIterator>

Server end of the iterator, when this protocol is used by Fuchsia clients.

SuiteController_GetEvents_Result

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescription
response SuiteController_GetEvents_Response
err LaunchError

SuiteEventPayload

Defined in fuchsia.test.manager/test_manager.fidl

Various events for test execution.

First event for a test case will always be case_found and last will be case_finished. Events case_started and case_artifact can come in any order. There can be some case_artifact between case_stopped and case_finished. suite_finished event will always fire when the whole suite has finished executing and suite_artifact may be fired anytime before suite_finished.

NameTypeDescription
case_found CaseFound

A case was found.

case_started CaseStarted

A case started execution

case_stopped CaseStopped

A case stopped executing, includes the pass/fail/skipped result of the case. The client might still get artifacts pertaining to this test after this event.

case_finished CaseFinished

A case has finished and all artifact events have been dispatched to the client.

case_artifact CaseArtifact

Artifact from a case

suite_artifact SuiteArtifact

Artifact from a suite.

suite_finished SuiteFinished

Suite run finished executing

Syslog

Defined in fuchsia.test.manager/test_manager.fidl

NameTypeDescription
archive fuchsia.developer.remotecontrol/ArchiveIterator

Client end of the iterator, when this protocol is used by host-side clients.

batch fuchsia.diagnostics/BatchIterator

Client end of the iterator, when this protocol is used by Fuchsia clients.

TYPE ALIASES

NameValueDescription
CaseName string[512]

Human-readable name for a test case.

TestCaseId uint32

Test case identifier. Unique in a suite run.