blob: b1cc585e836b4737f043d4a6a3276223860e5e2b [file] [log] [blame]
// Copyright 2021 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
syntax = "proto3";
package tast.core;
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "chromiumos/tast/framework/protocol/dutfeatures.proto";
import "features.proto";
option go_package = "chromiumos/tast/internal/protocol";
service TestService {
// ListEntities requests all entities available on the server.
rpc ListEntities(ListEntitiesRequest) returns (ListEntitiesResponse) {}
// RunTests requests to run tests.
// A client must send an initial request message containing RunTestsInit to
// a server. Then a server starts running tests and report progress in
// streamed response messages.
rpc RunTests(stream RunTestsRequest) returns (stream RunTestsResponse) {}
// GetDUTInfo requests to collect DUT system information.
rpc GetDUTInfo(GetDUTInfoRequest) returns (GetDUTInfoResponse) {}
// GetSysInfoState requests to collect the initial sysinfo state of the DUT.
rpc GetSysInfoState(GetSysInfoStateRequest)
returns (GetSysInfoStateResponse) {}
// CollectSysInfo requests to collect the sysinfo, considering diff from the
// given initial sysinfo state.
rpc CollectSysInfo(CollectSysInfoRequest) returns (CollectSysInfoResponse) {}
// DownloadPrivateBundles requests to download private bundles and install
// them to the DUT.
rpc DownloadPrivateBundles(DownloadPrivateBundlesRequest)
returns (DownloadPrivateBundlesResponse) {}
}
message ListEntitiesRequest {
Features features = 1;
// Recursive specifies whether to list entities on target bundles recursively.
bool recursive = 2;
}
message ListEntitiesResponse {
// Entities is a list of entities available on the server. The order of
// entities is unspecified.
repeated ResolvedEntity entities = 1;
}
message RunTestsRequest {
oneof type {
RunTestsInit run_tests_init = 1;
StackOperationResponse stack_operation_response = 3;
}
reserved 2;
}
message RunTestsResponse {
oneof type {
RunLogEvent run_log = 1;
EntityStartEvent entity_start = 2;
EntityLogEvent entity_log = 3;
EntityErrorEvent entity_error = 4;
EntityEndEvent entity_end = 5;
EntityCopyEndEvent entity_copy_end = 8;
StackOperationRequest stack_operation = 6;
HeartbeatEvent heartbeat = 7;
}
}
message GetDUTInfoRequest {
// ExtraUseFlags lists USE flags that should be treated as being set in
// addition to the ones read from USEFlagsFile when computing the feature sets
// for GetDUTInfoResponse.
repeated string extra_use_flags = 1;
}
message GetDUTInfoResponse { DUTInfo dut_info = 1; }
message GetSysInfoStateRequest {}
message GetSysInfoStateResponse {
// State contains the collected sysinfo state.
SysInfoState state = 1;
}
message CollectSysInfoRequest {
// InitialState describes the pre-testing state of the DUT. It should be
// generated by the GetSysInfoState method executed before tests are run.
SysInfoState initial_state = 1;
}
message CollectSysInfoResponse {
// LogDir is the directory which log files were copied to. The caller should
// delete it.
string log_dir = 1;
// CrashDir is the directory which minidump crash files were copied to. The
// caller should delete it.
string crash_dir = 2;
}
message DownloadPrivateBundlesRequest {
// ServiceConfig contains information needed to connect to the service
// provided by infrastructure system.
ServiceConfig service_config = 1;
// BuildArtifactsUrl is the URL of Google Cloud Storage directory, ending with
// a slash, containing build artifacts for the current ChromeOS image.
// If it is empty, DefaultBuildArtifactsURL in runner.Config is used.
string build_artifact_url = 2;
}
message DownloadPrivateBundlesResponse {}
// EntityType represents a type of an entity.
enum EntityType {
TEST = 0;
FIXTURE = 1;
}
// Entity describes an entity.
message Entity {
EntityType type = 1;
string name = 2;
string package = 3;
repeated string attributes = 4;
string description = 5;
string fixture = 6;
EntityDependencies dependencies = 7;
EntityContacts contacts = 8;
EntityLegacyData legacy_data = 9;
repeated StringPair search_flags = 10;
}
// EntityContacts contains contact information of an entity.
message EntityContacts { repeated string emails = 1; }
// EntityDependencies describes dependencies of an entity that need to be
// evaluated before running it.
message EntityDependencies {
repeated string data_files = 1;
repeated string services = 2;
}
// EntityLegacyData contains extra information of an entity.
// Fields in this message are considered legacy because test bundles need to
// send these fields to Tast CLI just because they are made available in
// results.json for compatibility reasons.
message EntityLegacyData {
google.protobuf.Duration timeout = 1;
repeated string variables = 2;
repeated string variable_deps = 3;
repeated string software_deps = 4;
string bundle = 5;
}
message RunTestsInit {
RunConfig run_config = 1;
// Recursive specifies whether to run tests on target bundles recursively.
bool recursive = 2;
// DebugPort is the port which the debugger for the test bundle will listen
// on. Note that this field is only used for test runners, and not bundles.
uint32 debug_port = 10;
}
// RunConfig contains parameters needed to run tests in a test bundle.
message RunConfig {
// Tests is a list of test names to be run. Wildcards are not allowed.
repeated string tests = 1;
RunDirectories dirs = 2;
Features features = 3;
ServiceConfig service_config = 4;
DataFileConfig data_file_config = 5;
reserved 6;
StartFixtureState start_fixture_state = 7;
// HeartbeatInterval is the interval in seconds at which heartbeat messages
// are sent back periodically from runners (before running bundles) and
// bundles. If this value is not positive, heartbeat messages are not sent.
// TODO(crbug.com/1128259): Remove this field once we fully migrate to gRPC.
google.protobuf.Duration heartbeat_interval = 8;
// WaitUntilReady indicates that the test bundle's "ready" function (see
// ReadyFunc) should be executed before any tests are executed.
// TODO(crbug.com/1128259): Remove this field once we fully migrate to gRPC.
bool wait_until_ready = 9;
// DebugPort is the port that the bundle will attach the debugger to.
uint32 debug_port = 10;
// SystemServiceTimeout is timeout for waiting for system services to be ready
// in seconds. (Default: 120 seconds)
google.protobuf.Duration system_services_timeout = 11;
// Target specifies how the primary target bundle should run.
// This can be nil if no target bundle exists.
RunTargetConfig target = 12;
}
// RunTargetConfig contains parameters for the primary target bundle to run.
message RunTargetConfig {
// Devservers correspnods to config.Devservers.
repeated string devservers = 1;
// Dirs contains directories local tests use.
RunDirectories dirs = 2;
// DebugPort is the port that the bundle will attach the debugger to.
uint32 debug_port = 3;
// MaxTestFailures specifies maximum test failures allowed.
int32 max_test_failures = 4;
// Retries is the number of retries for failing tests.
int32 retries = 5;
// Proxy if true indicates that the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY
// environment variables (and their lowercase counterparts) should be
// forwarded to the DUT if set on the host.
bool proxy = 6;
// TODO(crbug.com/1128259): Remove this field once we fully migrate to gRPC.
bool wait_until_ready = 7;
}
// RunDirectories holds several directory paths important for running tests.
message RunDirectories {
// DataDir is the path to the directory containing test data files.
string data_dir = 1;
// OutDir is the path to the base directory under which tests should write
// output files.
string out_dir = 2;
// TempDir is the path to the directory under which temporary files for tests
// are written.
string temp_dir = 3;
}
// ServiceConfig contains configurations of external services available to
// Tast framework and Tast tests.
message ServiceConfig {
// Devservers is a list of devserver URLs (e.g. "https://1.2.3.4:5678").
// Devservers are used to download data files from Google Cloud Storage with
// cache. It is ignored if DUT Server is available.
repeated string devservers = 1;
// TlwServer is an address of a TLW server (e.g. "1.2.3.4:5678").
// When this is set, it takes precedence over Devservers.
// Note: Obsolete.
string tlw_server = 2;
// TlwSelfName is a "DUT name" that identifies the current machine.
// It is empty for remote tests.
// Note: Obsolete.
string tlw_self_name = 3;
// TlwPrimaryTargetName is a "DUT name" of the primary target.
// It is empty if a primary target doesn't exist.
// Note: Obsolete.
string tlw_primary_target_name = 4;
// DutServer is an address of a DUT server (e.g. "1.2.3.4:5678").
// When this is set, it takes precedence over Devservers.
string dut_server = 5;
// Following fields are only needed for remote tests.
// UseEphemeralDevserer instructs whether to use ephemeral devserver.
bool use_ephemeral_devservers = 6;
// TastDir used to specify cache directory.
string tast_dir = 7;
// ExtraAllowedBuckets specifies ephemeral devserver's allowed buckets.
repeated string extra_allowed_buckets = 8;
}
// DownloadMode specifies a strategy to download external data files.
enum DownloadMode {
// BATCH specifies that test bundles should download external data files
// in batch before running tests.
BATCH = 0;
// LAZY specifies that test bundles should download external data files
// as needed between tests.
LAZY = 1;
}
// DataFileConfig contains configurations about data files.
message DataFileConfig {
DownloadMode download_mode = 1;
// BuildArtifactsUrl is the URL of Google Cloud Storage directory, ending with
// a slash, containing build artifacts for the current ChromeOS image.
string build_artifacts_url = 2;
}
// StartFixtureState contains information of a start fixture.
message StartFixtureState {
// Name is the name of a start fixture.
string name = 1;
// Errors contains errors reported on dependent fixture setup. If it is not
// empty, all fixtures and tests should fail immediately.
repeated Error errors = 2;
}
// Error describes details of an error reported by an entity.
message Error {
string reason = 1;
ErrorLocation location = 2;
}
// ErrorLocation represents a code location where an error was reported.
message ErrorLocation {
string file = 1;
int64 line = 2;
string stack = 3;
}
// ResolvedEntity is similar to Entity, but contains additional fields computed
// from an original Entity and run time information.
message ResolvedEntity {
Entity entity = 1;
// Skips contains reasons why this test should be skipped. If it contains one
// or more reasons, the test should be skipped for unsatisfied dependencies.
// This field can be set only if the entity is a test.
Skip skip = 2;
// Hops contains the number of remote connection hops from the current machine
// and the machine serving the entity.
// On the host machine, hops=0 means remote entities (on the host machine) and
// hops=1 means local entities (on the DUT).
int32 hops = 3;
// StartFixtureName is the name of the fixture that needs to be set up
// externally in order to run this entity.
string start_fixture_name = 4;
}
// TimingLog is a protobuf presentation of a timing.Log.
message TimingLog { TimingStage root = 1; }
// TimingStage is a protobuf presentation of a completed timing.Stage.
message TimingStage {
string name = 1;
google.protobuf.Timestamp start_time = 2;
google.protobuf.Timestamp end_time = 3;
repeated TimingStage children = 4;
}
// RunLogEvent indicates that an informational log message not associated with
// an entity was produced.
message RunLogEvent {
google.protobuf.Timestamp time = 1;
string text = 2;
}
// EntityStartEvent marks the start of an entity run. EntityStartEvent is sent
// even if an entity is to be skipped.
message EntityStartEvent {
google.protobuf.Timestamp time = 1;
Entity entity = 2;
string out_dir = 3;
}
// EntityLogEvent indicates that an informational log message was produced by
// an entity.
message EntityLogEvent {
google.protobuf.Timestamp time = 1;
string entity_name = 2;
string text = 3;
}
// EntityErrorEvent indicates that an error was produced by an entity.
// A consumer should treat an entity as failed when it sees one or more errors
// reported for it.
message EntityErrorEvent {
google.protobuf.Timestamp time = 1;
string entity_name = 2;
Error error = 3;
}
// EntityEndEvent marks the end of an entity run.
message EntityEndEvent {
google.protobuf.Timestamp time = 1;
string entity_name = 2;
Skip skip = 3;
TimingLog timing_log = 4;
}
// EntityCopyEndEvent marks the end of an file copies after entity ends.
message EntityCopyEndEvent { string entity_name = 1; }
// Skip describes the reasons why an entity is skipped.
message Skip { repeated string reasons = 1; }
// DUTInfo holds DUT system information.
message DUTInfo {
reserved 1;
// Features contains features available on the DUT.
DUTFeatures features = 4;
// OsVersion contains the DUT's OS Version.
string os_version = 2;
// DefaultBuildArtifactsUrl specifies the default URL of the build artifacts.
string default_build_artifacts_url = 3;
}
// SysInfoState contains the state of the DUT's system information.
message SysInfoState {
// LogInodeSizes maps from each log file's inode to its size in bytes.
map<uint64, int64> log_inode_sizes = 1;
// UnifiedLogCursor contains an opaque cursor pointing at the current tip of
// unified system logs.
string unified_log_cursor = 2;
// CrashFilePaths contains absolute paths to crash files.
repeated string crash_file_paths = 3;
}
message StackOperationRequest {
oneof type {
StackReset reset = 1;
StackPreTest pre_test = 2;
StackPostTest post_test = 3;
StackGetStatus status = 4;
StackSetDirty set_dirty = 5;
StackGetErrors errors = 6;
}
}
message StackReset {}
message StackPreTest {
Entity entity = 1;
bool has_error = 2;
}
message StackPostTest {
Entity entity = 1;
bool has_error = 2;
}
message StackGetStatus {}
message StackSetDirty { bool dirty = 1; }
message StackGetErrors {}
message StackOperationResponse {
// FatalError is an framework internal error happened during operation.
string fatal_error = 1;
// Status is a response for StackGetStatus request.
// It's also populated in Reset's response.
StackStatus status = 2;
// Errors is a response for StackGetErrors request.
repeated Error errors = 3;
// TestHasError is a response for StackPreTest and StackPostTest request.
bool test_has_error = 4;
}
enum StackStatus {
GREEN = 0;
RED = 1;
YELLOW = 2;
}
message HeartbeatEvent { google.protobuf.Timestamp time = 1; }
// A string key-value pair.
message StringPair {
// Regex: ^[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*$
// Max length: 64.
string key = 1;
// Max length: 256.
string value = 2;
}