github.com/nya3jp/tast@v0.0.0-20230601000426-85c8e4d83a9b/src/go.chromium.org/tast/core/internal/protocol/testing.proto

// Copyright 2021 The ChromiumOS Authors
// 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 "go.chromium.org/tast/core/framework/protocol/dutfeatures.proto";
import "features.proto";

option go_package = "go.chromium.org/tast/core/internal/protocol";

service TestService {
  // ListEntities requests all entities available on the server.
  rpc ListEntities(ListEntitiesRequest) returns (ListEntitiesResponse) {}

  // GlobalRuntimeVars requests all global runtime variables declared on the
  // server.
  rpc GlobalRuntimeVars(GlobalRuntimeVarsRequest)
      returns (GlobalRuntimeVarsResponse) {}

  // 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) {}

  // StreamFile requests to stream a specify file.
  rpc StreamFile(StreamFileRequest) returns (stream StreamFileResponse) {}
}

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 GlobalRuntimeVarsRequest {}

message GlobalRuntimeVar { string name = 1; }

message GlobalRuntimeVarsResponse { repeated GlobalRuntimeVar vars = 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;
  // Features specifies whether to get software/hardware features of the DUT.
  bool features = 2;
}

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 {}

message StreamFileRequest {
  // Name is the name of the file which the content will be streamed.
  string name = 1;
  // Offset is where in the file that streaming should start.
  // If the offset is negative, streaming will start at the end of file.
  int64 offset = 2;
}

message StreamFileResponse {
  // Content is the latest content from the log file.
  bytes data = 1;
  // Offset is where the current file point to after reading the current data.
  int64 offset = 2;
}

// 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;
  repeated string test_bed_deps = 11;
  repeated string requirements = 12;
  string bug_component = 13;
  string lacros_status = 14;
}

// 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;

  // MsgTimeout is the duration that the client waits for.
  // If no activity is seen even after that the connection is closed.
  // (Default: 60 seconds)
  google.protobuf.Duration msg_timeout = 13;

  // MaxSysMsgLogSize is a maximum size of /var/log/messages that Tast will
  // copy.
  int64 max_sys_msg_log_size = 14;

  // WaitUntilReadyTimeout set a timeout for the entire ready.Wait function.
  google.protobuf.Duration wait_until_ready_timeout = 15;
}

// 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;
  // MsgTimeout is the duration that the client waits for.
  // If no activity is seen even after that the connection is closed.
  // (Default: 60 seconds)
  google.protobuf.Duration msg_timeout = 8;
  // SystemServiceTimeout is timeout for waiting for system services to be ready
  // in seconds. (Default: 120 seconds)
  google.protobuf.Duration system_services_timeout = 9;
  // WaitUntilReadyTimeout set a timeout for the entire ready.Wait function.
  //(Default: 120 seconds)
  google.protobuf.Duration wait_until_ready_timeout = 10;
  // SwarmingTaskID specifies the swarming task ID of the scheduled
  // job that run Tast tests.
  string SwarmingTaskID = 11;
  // BuildBucketID specifies the build bucket ID of the scheduled
  // job that run Tast tests.
  string BuildBucketID = 12;
}

// 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;

  // SwarmingTaskID specifies the swarming task ID of the scheduled
  // job that run Tast tests.
  string SwarmingTaskID = 9;
  // BuildBucketID specifies the build bucket ID of the scheduled
  // job that run Tast tests.
  string BuildBucketID = 10;
}

// 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;
    StackValue value = 7;
  }
}

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 StackValue {}

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;
  // FixtValue is the serialized fixture value of the fixture in current stack.
  bytes fixt_value = 5;
}

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;
}