// Copyright 2020 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 test.rtd.v1;

option go_package = "go.chromium.org/chromiumos/infra/proto/go/test/invocation";

import "lab/peripherals.proto";
import "lab/services/client.proto";
import "test/common/device.proto";
import "test/rtd/v1/progress.proto";

// Input to a Remote Test Driver invocation.
//
// TODO(crbug.com/1051691): Link to a reference implementation of Remote Test
// Server & Remote Test Driver.
message Invocation {
  // Progress sink to be used to report progress of the Remote Test Driver
  // invocation to the surrounding Remote Test Server.
  ProgressSinkClientConfig progress_sink_client_config = 1;

  // Set of DUTs used for each of the requests in this invocation.
  repeated DUT duts = 2;

  // Smallest unit of an invocation request for which results must be reported.
  //
  // An invocation must execute all requests serially in-order. This assumption
  // is necessary for future support of test sequences in test plans.
  repeated Request requests = 3;

  // Configuration information for using Test Lab Services to interact
  // with DUTs and their peripherals.
  lab.services.ClientConfig test_lab_services_config = 4;
}


// Contains all configuration data required to interact with a single device
// under test during a test invocation.
message DUT {
  // Device Under Test sepcification.
  test.common.Device device =1;

  // Peripherals information about the lab deployment of the device.
  lab.Peripherals peripherals = 2;

  // Name for the DUT for using Test Lab Services to interact with the
  // device and its peripherals.
  // The RTD must pass this to certain Test Lab Service RPCs to specify
  // DUTs to act on.
  // See the tls.OpenDutPortRequest message for an example of where
  // this is used.
  string tls_dut_name = 3;
}

// Request for execution of a single test.metadata.Test
message Request {
  // name must be unique across all requests in this invocation.
  //
  // Remote Test Drivers are recommended to use name as the opaque tag
  // required by the Test Lab Services API. Thus, name should be unique across
  // all invocations to simplify analytics. UUIDs are recommended.
  //
  // See also:
  //   Test Lab Services API: tls/README.md
  string name = 1;

  // The test to execute, identified by the test.metadata.Test.name field.
  //
  // Note that the request does not contain a reference to the Remote Test
  // Driver to use, as the request is an input to the Remote Test Driver
  // invocation.
  string test = 2;

  // Per-request Remote Test Server environment configuration.
  message Environment {
    // Absolute path to a directory where prod-critical log-data may be written.
    //
    // This directory must be created by Remote Test Server prior to the Remote
    // Test Driver invocation and its contents must be successfully offloaded to
    // the requested long-term storage for the request to be considered
    // successful.
    //
    // Note: Remote Test Drivers should use
    // test.invocation.ProgressClient.ReportLogData() to report logs whenever
    // possible. This log-data reporting feature is grandfathered into the
    // current API to support test-specific critical log-data reporting.
    string critical_log_data_path = 1;

    // Absolute path to a directory where non prod-critical log-data may be
    // written.
    //
    // This directory must be created by Remote Test Server prior to the Remote
    // Test Driver invocation. It's contents may be offloaded to long-term
    // storage as a best effort asynchronous task.
    //
    // Note: Remote Test Drivers should use
    // test.invocation.ProgressClient.ReportLogData() to report logs whenever
    // possible. This log-data reporting feature is grandfathered into the
    // current API to support test-specific log files.
    string log_data_path = 2;
  }

  // Environment configuration set by the Remote Test Server for a specific
  // request of the Remote Test Driver.
  Environment environment = 3;
}