// Copyright 2019 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_platform;

import "chromite/api/test_metadata.proto";
import "chromiumos/common.proto";
import "google/protobuf/duration.proto";

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

// Request represents a request to the ChromeOS Test Platform to run a test,
// set of tests, suite of tests, or test plan on a set of devices (eventually
// also: virtual devices) in the ChromeOS Test Lab.
message Request {
  // Params defines parameters that apply to an entire Request.
  //
  // NEXT_TAG: 11
  message Params {
    // HardwareAttributes defines the hardware-bound characteristics
    // of the devices to run tests on.
    message HardwareAttributes {
      // Model is the model to run tests against.
      //
      // TODO(akeshet): Re-use device protos instead of defining this
      // independently.
      string model = 1;

      // TODO(akeshet): Add other schedulable characteristics, based on shared
      // hardware config protos.
    }

    HardwareAttributes hardware_attributes = 1;

    // SoftwareAttributes defines software characteristics that are strongly
    // associated with a device, though not immutable or hardware-bound.
    message SoftwareAttributes {
      chromiumos.BuildTarget build_target = 2;

      // TODO(akeshet): add other attributes such as CTS version,
      // kernel version(?), etc.
    }

    SoftwareAttributes software_attributes = 2;

    // FreeformAttributes defines user-specified device attributes that are
    // opaque to the test platform. It is preferrable not to use these, but
    // they are provided to cover cases in which the test platform does not
    // present a parameter corresponding to the attributes of interest.
    message FreeformAttributes {
      // SwarmingDimensions are raw swarming bot dimensions, expressed as
      // "key:value" strings.
      repeated string swarming_dimensions = 1;
    }

    FreeformAttributes freeform_attributes = 9;

    // SoftwareDependency defines mutable software characteristics of the
    // devices to run tests on (for instance, the desired version of ChromeOS).
    message SoftwareDependency {
      oneof dep {
        // ChromeOS build name, e.g. "reef-release/R77-12345.0.0"
        string chromeos_build = 3;

        // Readonly firmware build name, e.g. "firmware-reef-9042.B-firmwarebranch/R72-11311.0.0"
        string ro_firmware_build = 4;

        // Read-write firmware build name, e.g. "firmware-reef-9042.B-firmwarebranch/R72-11311.0.0"
        string rw_firmware_build = 5;
      }
    }

    repeated SoftwareDependency software_dependencies = 3;

    // Scheduling defines parameters that affect how the tests in this
    // request are prioritized relative to other requests, and how capacity for
    // them is allocated.
    message Scheduling {
      // ManagedPool enumerates the different lab platform-managed pools.
      // Devices in these pools are automatically managed by lab platform
      // systems and can not be arbitrarily assigned to pools by users.
      //
      // Managed pool implementations are specific to test platform's scheduling
      // backends.
      // For Skylab, see
      // https://chromium.googlesource.com/infra/infra/+/5566668428c6b286702bf440d9dfd0be7bca1d84/go/src/infra/libs/skylab/inventory/device.proto#173
      // For autotest, see
      // https://chromium.googlesource.com/chromiumos/third_party/autotest/+/7436c2b6e6bd32ed1f1bd08cf8e0feb40cfe7b89/server/constants.py#18
      enum ManagedPool {
        MANAGED_POOL_UNSPECIFIED = 0;
        MANAGED_POOL_CQ = 1;
        MANAGED_POOL_BVT = 2;
        MANAGED_POOL_SUITES = 3;
        MANAGED_POOL_CTS = 4;
        MANAGED_POOL_CTS_PERBUILD = 5;
        MANAGED_POOL_CONTINUOUS = 6;
        MANAGED_POOL_ARC_PRESUBMIT = 7;
        MANAGED_POOL_QUOTA = 8;
      }

      oneof pool {
        // Managed pool of devices to run tests in.
        ManagedPool managed_pool = 1;

        // Unmanaged pool of devices to run tests in.
        // Must not be a managed pool.
        string unmanaged_pool = 2;

        // TODO(crbug/1059076): Remove this field after the migration is done. Use
        // qs_account to specify quota account for both managed and unmanaged pools.
        string quota_account = 3 [deprecated = true];
      }

      // Priority corresponds to a swarming task priority; if specified, it
      // should be in the range [50,255]. This priority will be used for
      // any swaming tasks created by this run.
      //
      // Note that the scheduler behavior with a given priority depends on
      // other factors, such as pool. In particular, if requests are run in
      // a quotascheduler-controlled pool, then this priority will be ignored,
      // as priority will be determined by quota account balances.
      int64 priority = 4;

     // It is an error to set both qs_account and priority at the same time.
     // qs_account should be used if the request is scheduled on a pool
     // managed by QuotaScheduler. See go/qs-enabled-pools for details.
     // If qs_account is set for requests on no QuotaScheduler pools,
     // it will be ignored and the request will default to running at
     // the lowest priority.
      string qs_account = 5;
    }

    Scheduling scheduling = 4;

    // Retry defines parameters that affect how failed tests within
    // a request are retried.
    message Retry {
      // Whether to allow test retries.
      bool allow = 1;

      // Maximum number of retries of tests within this invocation to allow.
      // 0 = unlimited.
      int32 max = 2;
    }

    Retry retry = 5;

    // Metadata defines parameters that determine where test definitions
    // and metadata are stored and discovered from.
    message Metadata {
      // A Google Storage path to the location of test metadata to be used.
      // For example:
      // "gs://chromeos-image-archive/arkham-release/R57-9202.10.11".
      string test_metadata_url = 1;

      // A Google Storage path to the location of image archive in which to find
      // debug symbols to be used in post-process symbolication of crashes. This
      // is generally the same as test_metadata_url.
      string debug_symbols_archive_url = 2;
    }

    Metadata metadata = 6;

    // Time defines parameters related to timeouts.
    message Time {
      // Maximum duration for the entire request to be handled.
      google.protobuf.Duration maximum_duration = 1;
    }

    Time time = 7;

    // Decorations defines parameters that add additional decorations to
    // test runs.
    message Decorations {
      // AutotestKeyvals are (key, value) pairs that will be added to all
      // autotest tasks run.
      map <string, string> autotest_keyvals = 1;

      // Tags are swarming tags that will be applied to all swarming tasks
      // launched.
      repeated string tags = 2;
    }

    Decorations decorations = 8;

    // Legacy encodes arguments that relate to migration from legacy backend
    // (autotest); support for these arguments will be phased out.
    message Legacy {
      // If autotest_suite is defined, then if the autotest backend is selected
      // for running this request, the entire enumeration will be ignored, and
      // replaced by a single invocation of this named autotest suite.
      string autotest_suite = 1;
    }

    Legacy legacy = 10;

    // Notification defines parameters for the request to use to notify callers
    // of its test's status updates.
    message Notification {
      // Pubsub topic to broadcast status updates to
      string pubsub_topic = 1;
    }

    Notification notification = 11;

    // Migrations defines parameters that facilitate gradual migrations between
    // different implementations of downstream components.
    message Migrations {
      // If true, schedule individual tests via buildbucket and run them via
      // test_runner recipe.
      // Otherwise, schedule individual tests via raw swarming calls and run
      // them via skylab_swarming_worker.
      // TODO(crbug/1033287): remove when migration is complete.
      bool use_test_runner = 1;

      // If true, test tasks will perform synchronous offload of the contents
      // of $SYNCHRONOUS_OFFLOAD_DIR to a GS bucket. This requires
      // use_test_runner to also be set to true: if use_test_runner is set to
      // false and enable_synchronous_offload is set to true, the build will
      // fail validation.
      // If false, such offload will be skipped.
      bool enable_synchronous_offload = 2;
    }

    Migrations migrations = 12;
  }

  Params params = 1;

  // SuiteRequest defines an individual named suite.
  message Suite {
    string name = 1;
  }

  message Test {
    message Autotest {
      string name = 1;
      string test_args = 2;

      // Name to be used to display this test's output artifacts, e.g. logs,
      // results etc. By default display_name is the same as name.
      //
      // display_name is especially useful when using test_args to distinguish
      // between multiple instances of the same test in a request.
      string display_name = 3;
    }

    oneof harness {
      Autotest autotest = 1;
    }
  }

  // Enumeration is a previously enumerated test plan.
  //
  // This is a copy of test_platform.steps.EnumerationResponse
  // Keep in sync.
  message Enumeration {
    message AutotestInvocation {
      chromite.api.AutotestTest test = 1;
      string test_args = 2;
      string display_name = 3;
      map <string, string> result_keyvals = 4;
    }
    repeated AutotestInvocation autotest_invocations = 2;
  }

  message TestPlan {
    repeated Suite suite = 1;
    repeated Test test = 2;
    Enumeration enumeration = 3;
  }

  TestPlan test_plan = 5;
}