test.proto

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under both the MIT license found in the
 * LICENSE-MIT file in the root directory of this source tree and the Apache
 * License, Version 2.0 found in the LICENSE-APACHE file in the root directory
 * of this source tree.
 */

syntax = "proto3";

package buck.test;

import "google/protobuf/duration.proto";
import "data.proto";

// Message sent when a TestSuite is discovered.
message Testing {
  // A name for the current suite.
  string suite = 1;
  repeated string testcases = 2;
}

message TestStage {
  message Listing {
    string suite = 1;
  }

  oneof item {
    Listing listing = 1;
    Testing testing = 2;
  }
}

message WeightClass {
  oneof value {
    uint64 permits = 1;
    uint32 percentage = 2; // Between 0 and 100.
  }
}

message HostSharingRequirements {
  reserved 1, 3;

  message Shared {
    WeightClass weight_class = 1;
  }

  message ExclusiveAccess {}

  message OnePerToken {
    string identifier = 1;
    WeightClass weight_class = 2;
  }

  oneof requirements {
    ExclusiveAccess exclusive_access = 2;
    Shared shared = 4;
    OnePerToken one_per_token = 5;
  }
}

message ExecutionStream {
  oneof item {
    bytes inline = 1;
  }
}

message ExecutionStatus {
  oneof status {
    int32 finished = 1;
    google.protobuf.Duration timed_out = 2;
  }
}

message ConfiguredTargetHandle {
  int64 id = 1;
}

message ConfiguredTarget {
  reserved 2;
  ConfiguredTargetHandle handle = 1;
  // Structured data describing the target
  string cell = 3;
  string package = 4;
  string target = 5;
  string configuration = 6;
  string package_project_relative_path = 7;
}

enum TestStatus {
  NOT_SET = 0;
  PASS = 1;
  FAIL = 2;
  SKIP = 3;
  OMITTED = 4;
  FATAL = 5;
  TIMEOUT = 6;
  UNKNOWN = 7;
  RERUN = 8;
  LISTING_SUCCESS = 9;
  LISTING_FAILED = 10;
}

message TestResult {
  message OptionalMsg {
    string msg = 1; // Required
  }

  string name = 1; // Required
  TestStatus status = 2; // Required
  OptionalMsg msg = 5; // Optional
  ConfiguredTargetHandle target = 6; // Required
  google.protobuf.Duration duration = 7; // Optional
  string details = 8; // Required
}

message ReportTestResultRequest {
  TestResult result = 1;
}

message ReportTestsDiscoveredRequest {
  ConfiguredTargetHandle target = 1;
  Testing testing = 3;
}

message ReportTestSessionRequest {
  reserved 2;
  string session_info = 3;
}

message EndOfTestResultsRequest {
  int32 exit_code = 1;
}

message Empty {};

message ExternalRunnerSpecRequest {
  ExternalRunnerSpec test_spec = 1;
}

// A spec representing test targets aiming for maximum compatibility with the
// external runner spec as defined in buck1.
message ExternalRunnerSpec {
  // Target the spec belongs to
  ConfiguredTarget target = 1;

  // Type of test spec
  string test_type = 2;

  // Base command used for further processing. A mix of verbatim arguments and
  // opaque handles for more complex arguments.
  repeated ExternalRunnerSpecValue command = 3;

  // Environment variables a specified by the rule. A mapping from keys to
  // verbatim values or opaque handles for more complex values.
  map<string, ExternalRunnerSpecValue> env = 4;

  // Labels defined on the rule.
  repeated string labels = 5;

  // Contacts defined on the rule.
  repeated string contacts = 6;

  // Oncall
  optional string oncall = 7;

  // Current working directory cell.
  string working_dir_cell = 8;
}

message ExternalRunnerSpecValue {
  oneof value {
    string verbatim = 1;
    int64 arg_handle = 2;
    string env_handle = 3;
  }
}

message TestExecutable {
  reserved 4;
  TestStage stage = 1;
  ConfiguredTargetHandle target = 2;
  repeated ArgValue cmd = 3;
  repeated DeclaredOutput pre_create_dirs = 5;
  repeated EnvironmentVariable env = 6;
}

message ExecutorConfigOverride {
  string name = 1;
}

message LocalResourceType {
  string name = 1;
}

message ExecuteRequest2 {
  reserved 1 to 4, 7;
  google.protobuf.Duration timeout = 5;
  HostSharingRequirements host_sharing_requirements = 6;
  TestExecutable test_executable = 8;
  ExecutorConfigOverride executor_override = 9;
  repeated LocalResourceType required_local_resources = 10;
}

message PrepareForLocalExecutionRequest {
  TestExecutable test_executable = 1;
  repeated LocalResourceType required_local_resources = 2;
}

message ArgValue {
  ArgValueContent content = 1;
  // Optional format string for the value
  ArgFormat format = 2;
}

message EnvironmentVariable {
  string key = 1;
  ArgValue value = 2;
}

message ArgFormat {
  string format = 1;
}

message ArgValueContent {
  oneof value {
    ExternalRunnerSpecValue spec_value = 1;
    OutputName declared_output = 2;
  }
}

// This message should be compatible with the prefix of DeclaredOutput for
// backwards compatibility
message OutputName {
  string name = 1;
  reserved 2;
}

message TtlConfig {
  // Specifies a custom TTL in seconds for blobs in the output.
  int64 ttl_seconds = 1;
  // Specifies a custom use-case to use for managing the blobs in CAS.
  string use_case = 2;
}

message DeclaredOutput {
  string name = 1;
  // Flags that a consumer supports *remote* output, in which case it's not
  // necessary to materialize this output.
  bool supports_remote = 2;
  optional TtlConfig ttl_config = 3;
}

// Copy of Digest from Remote Execution API:
// https://github.com/facebook/buck2/blob/main/remote_execution/oss/re_grpc_proto/proto/build/bazel/remote/execution/v2/remote_execution.proto#L936-L943
message CasDigest {
  // The hash. In the case of SHA-256, it will always be a lowercase hex string
  // exactly 64 characters long.
  string hash = 1;

  // The size of the blob, in bytes.
  int64 size_bytes = 2;
}

// TODO(arr): consider using remote_execution.proto later on. The API surface
// there is larger but consolidation may be worth it.
message RemoteFileNode {
  string name = 1;
}

message RemoteDirNode {
  string name = 1;
  repeated RemoteObject children = 2;
}

message RemoteObject {
  CasDigest digest = 1;
  oneof node {
    RemoteFileNode file = 2;
    RemoteDirNode dir = 3;
  }
}

message Output {
  // TODO(arr): replace this oneof with just it's fields when we start uploading
  // results of local executions to CAS
  oneof value {
    string local_path = 1;
    RemoteObject remote_object = 2;
  }
}

message OutputEntry {
  OutputName declared_output = 1;
  Output output = 2;
}

message ExecutionResult2 {
  ExecutionStatus status = 1;
  ExecutionStream stdout = 2;
  ExecutionStream stderr = 3;
  repeated OutputEntry outputs = 4;
  google.protobuf.Duration start_time = 5; // Duration since the epoch
  google.protobuf.Duration execution_time = 6;
  ExecutionDetails execution_details = 7;
}

message ExecutionDetails {
  optional buck.data.CommandExecutionKind execution_kind = 1;
}

message Cancelled {}

message ExecuteResponse2 {
  oneof response {
    ExecutionResult2 result = 1;
    Cancelled cancelled = 2;
  }
}

message PrepareForLocalExecutionResult {
  reserved 2;
  repeated string cmd = 1;
  string cwd = 3;
  repeated VerbatimEnvironmentVariable env = 4;
}

message SetupLocalResourceLocalExecutionCommand {
  repeated string cmd = 1;
  string cwd = 2;
  repeated VerbatimEnvironmentVariable env = 3;
}

message VerbatimEnvironmentVariable {
  string key = 1;
  string value = 2;
}

message PrepareForLocalExecutionResponse {
  PrepareForLocalExecutionResult result = 1;
  repeated SetupLocalResourceLocalExecutionCommand
      setup_local_resource_commands = 2;
}

message AttachInfoMessageRequest {
  string message = 1;
}

message UnstableHeapDumpRequest {
  // The path to write the heap dump to. If this path is relative, it is made
  // absolute relative to the working directory of the daemon.
  string destination_path = 1;
}
message UnstableHeapDumpResponse {}

service TestOrchestrator {
  rpc EndOfTestResults(EndOfTestResultsRequest) returns (Empty);
  rpc ReportTestResult(ReportTestResultRequest) returns (Empty);
  rpc ReportTestsDiscovered(ReportTestsDiscoveredRequest) returns (Empty);
  rpc ReportTestSession(ReportTestSessionRequest) returns (Empty);
  rpc Execute2(ExecuteRequest2) returns (ExecuteResponse2);
  rpc PrepareForLocalExecution(PrepareForLocalExecutionRequest)
      returns (PrepareForLocalExecutionResponse);
  rpc AttachInfoMessage(AttachInfoMessageRequest) returns (Empty);
}

service TestExecutor {
  rpc ExternalRunnerSpec(ExternalRunnerSpecRequest) returns (Empty);
  rpc EndOfTestRequests(Empty) returns (Empty);
  // Requests the test server to perform a heap dump and save the dump to a
  // file.
  rpc Unstable_HeapDump(UnstableHeapDumpRequest)
      returns (UnstableHeapDumpResponse);
}