// 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.plan.v1;

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

import "test/fleet/v1/dut.proto";

// From chromiumos/config repo.
import "chromiumos/config/api/topology.proto";

// A set of known test plans.
//
// In practice, a complete specification of all known plans may consist of
// multiple Specification instances. In that case the plan names MUST be unique
// across different Specification instances.
message Specification {
  repeated Plan plans = 1;
}

// A Plan fully specifies a Test Platform end-user's coverage needs.
//
// Plans SHOULD associate platform software and Device Under Test condition
// coverage rules with tests that exercise those components. Plans MUST be used
// in the Test Platform request API. Other Test Lab Environments may use plans
// to ease interoperation with the Test Platform.
message Plan {
  // A globally unique test plan name.
  //
  // MUST be valid resource name per https://aip.dev/122.
  //
  // Pattern: plans/{plan}
  string name = 1;

  // Each test plan unit specifies a particular set of tests to be run to meet
  // specific conditions.
  repeated Unit units = 2;
}

// Specifies a particular set of tests to be run to meet specific conditions.
message Unit {
  // A globally unique test plan unit name.
  //
  // MUST be valid resource name per https://aip.dev/122.
  //
  // Pattern: plans/{plan}/units/{unit}
  //   where {plan} is the parent Plan of this Unit.
  string name = 1;

  // Selects tests to include in this test plan unit.
  //
  // See also: exclusions.
  TestConstraint test_constraint = 2;

  // Selects the set of Devices Under Test that satisfy the coverage
  // requirements of this test plan unit.
  //
  // See also: exclusions.
  DUTCoverageConstraint dut_coverage_constraint = 3;

  // Chrome OS platform software covered by this test plan.
  //
  // Test Platform requests may optionally include a reference to platform
  // software to be tested via the test plan. For such requests, Test Platform
  // MUST only execute test plan units that have non-trivial coverage of the
  // referenced platform software. Unrelated test plan units MUST be skipped.
  //
  // A typical example is presubmit testing: When testing a change to the
  // network manager, it may be desirable to only run test plan units that
  // are known to exercise the network manager.
  //
  // For a test plan unit with no `code_coverage` specified, Test Platform MUST
  // assume coverage of all platform software (i.e., this test plan unit MUST
  // never be skipped for code coverage considerations).
  CodeCoverage code_coverage = 4;

  // A list of criteria for (test, Device Under Test) pairs that MUST be
  // excluded from this test plan.
  //
  // Exclusions are used to record exceptions to the test plan specification for
  // devices that are known to cause test failures for some temporary or
  // permanent reasons. The test_constraint and dut_coverage_constraint fields
  // together specify the _intent_ of the test plan unit. The exclusions further
  // restrict what Devices Under Test can be used to satisfy the test plan unit
  // due to practical considerations.
  //
  // Each exclusion SHOULD correspond to a different business reason.
  // Conceptually, fixing a known issue should result in an exclusion being
  // removed.
  repeated Exclusion exclusions = 5;
}

// Selects the test.metadata.Test to include in a test plan unit.
message TestConstraint {
  // A Common Expression Language (CEL) expression to specify set of tests that
  // are included in a test plan unit.
  //
  // Test Platform MUST effectively evaluate `expression` with the following
  // declarations in scope for every test and include the test for which
  // `expression` evaluates to true in the test plan unit.
  //
  // - Constant: `test` of type TestConstraint.Test defined below,
  //   populated with metadata for a particular test.
  //
  // The full CEL spec can be found at https://github.com/google/cel-spec.
  //
  // TODO(crbug.com/1051689) Add reference to the metadata validator package.
  //
  // ## Examples
  //
  // Typical instructive examples of expressions are:
  //
  // - Tauto dummy tests
  //     "suite:dummy" in test.attributes
  // - Tast's crosbolt tests
  //     !("disabled" in test.attributes)
  //     && "group:crosbolt" in test.attributes
  //     && "crosbolt_perbuild" in test.attributes
  // - network Tauto tests, selected by name
  //     test.name.startsWith("network_")
  //
  // ## CEL support
  //
  // All standard CEL syntax, macros and functions MUST be supported.
  string expression = 1;

  message Test {
    // Name of the test as specified in test.metadata.Test.name
    string name = 1;

    // The test attribute name as specified in the test.metadata.Attribute.name
    //
    // attributes are populated from test.metadata.Test.attributes.
    repeated string attributes = 2;
  }
}

// Selects sets of Devices Under Test to run the tests on in a test plan unit.
message DUTCoverageConstraint {
  // A Common Expression Language (CEL) expression to specify set of DUTs that
  // provide the necessary coverage. `expression` MUST evaluate to a boolean
  // value in the evaluation context described below.
  //
  // Test Platform MUST support scheduling test requests on a set of Devices
  // Under Test that satisfy some constraints on their Chrome OS configuration.
  //
  // Test Platform MUST effectively evaluate `expression` with the following
  // declarations in scope for each possible subset of Devices Under Test and
  // ensure that the test is scheduled on a set of Devices Under Test for which
  // `expression` evaluates to true.
  //
  // - Constant: `duts` of type repeated DUTConfigConstraint.DUT defined below,
  //   each entry in `duts` set to the Chrome OS configuration payload of a
  //   particular Device Under Test.
  // - Types: Protobuf messages from `chromiumos.config.api.*`
  //   - Additionally available with the short-hand `api.*`
  // - Types: Protobuf messages from `test.fleet.v1.*`
  //   - Additionally available with the short-hand `fleet.*`
  //
  // The full CEL spec can be found at https://github.com/google/cel-spec.
  // This API only supports a sub-set of the CEL features as described here.
  // Test Platform MUST validate the expression and reject use of unsupported
  // features.
  //
  // TODO(crbug.com/1051689) Add reference to the metadata validator package.
  //
  // ## Examples
  //
  // Typical instructive examples of expressions are:
  //
  // - Constraints: All pre-F20 plans only specify constraints on what devices
  //   may be used, e.g.:
  //    - Run each test on one DUT with model 'nautilus'.
  //        TODO(pprabhu, shapiroc): Need a way to specify model for migration.
  //        duts.all(dut, dut.id.model_id.value = 'nautilus') && size(duts) == 1
  //    - Run each test on one DUT with a stylus.
  //        (duts.all(dut, dut.hardware_features.stylus
  //                       == api.HardwareFeatures.Present.PRESENT))
  //         && size(duts) == 1)
  //  - Fanout (not yet supported): In addition to constraints, the
  //    plan may want to ensure coverage across some device features.
  //    TODO(pprabhu) This is an instructive example. We can't say what arch
  //    yet.
  //    - Run each test on one x86 and ARM DUT with a specific camera.
  //        (duts.all(dut, dut.hardware_toplogy.camera.id != "gomoe")
  //         && duts.exist(dut,
  //                       dut.cpu = api.Component.Soc.Architecture.X86)
  //         && duts.exist(dut,
  //                       dut.cpu = api.Component.Soc.Architecture.ARM))
  //      Note that this expression does not have a clause for size(duts). Thus
  //      Test Platform may satisfy this expression by running the test on more
  //      than two DUTs. This behaviour can be unexpected, especially if the
  //      plan fails due to an error on test execution on one of the selected
  //      devices, even though it passed on other devices in the set such that
  //      the expression was satsifed by the passing subset. Selection of a
  //      minimal set of devices to run the plan is best effort.
  //
  // Currently, only single-DUT constraints are supported by the Test Platform.
  // i.e., `expression` MUST be of the form:
  //   duts.all(DUT_SELECTOR) && size(duts) == 1
  // where DUT_SELECTOR is an expression that does not refer to `duts`.
  // This restriction will be lifted as this API matures.
  //
  // ## CEL support
  //
  // The full CEL spec can be found at https://github.com/google/cel-spec.
  //
  // Current support for `expression` evaluation is very restricted due to
  // limitations in the scheduling infrastructure used by Test Platform.
  //
  // As this API matures, features will be added to the scheduling
  // infrastructure of Test Platform and restrictions here will be lifted based
  // on requirements collected from test authors. See milestones in
  // go/cros-f20-plan for expected feature iterations. Test Lab Environments
  // SHOULD validate the expression and reject use of unsupported features.
  //
  // TODO(crbug.com/1051689) Add reference to the metadata validator package.
  //
  // ### Syntax
  //
  // See full syntax definition at
  // https://github.com/google/cel-spec/blob/master/doc/langdef.md#syntax
  //
  // CEL standard syntax allows expressions that evaluate to errors (e.g.,
  // syntax allows negation of lists, which has no semantics in CEL).
  // Thus, this spec does not attempt to restrict the syntax, but specifies what
  // operations are unsupported to aid metadata producers. Ultimately, the
  // reference metadata validator is the authority on what expressions are
  // allowed.
  //
  // Unsupported standard CEL semantics:
  //   - Binary arithmetic operations
  //     e.g.: +, *, /, % ...
  //   - Relational Operators beyond (in)equality are not supported.
  //     e.g.: (>, <, >=, <= ...)
  //   - Logical OR in expressions is not supported.
  //     e.g.: (a || b), !(a && b) ...
  //
  // ### Macros
  //
  // See full macro definition at
  // https://github.com/google/cel-spec/blob/master/doc/langdef.md#macros
  //
  // Supported macros: has(), e.all()
  // Unsupported macros: e.exists(), e.exists_one(), e.map(), e.filter()
  //
  // ### Standard functions
  //
  // See full list of standard definitions at
  // https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions
  //
  // Most standard functions are not supported.
  //
  // - Supported operators: !_, -_, _!=_, _&&_, _=_, _[_]
  //   - All other operators are not supported.
  // - All other standard functions are not supported. In particular:
  //   - size() is not supported.
  //   - string functions like endsWith() and contains() are not supported.
  //   - type conversions like int() and string() are not supported.
  //   - reflection with type(), null_type() and dyn() is not supported.
  string expression = 1;

  // The evaluation context for `expression` MUST include the Chrome OS
  // configuration payload for a set of Devices Under Test as a typed
  // constant of the following type.
  //
  //   repeated DUT duts = 1;
  //
  message DUT {
    // Configuration information about the lab deployment of the device.
    test.fleet.v1.DeviceUnderTest fleet_dut = 1;
    chromiumos.config.api.HardwareFeatures hardware_features = 2;
  }
}

// Exlclusion is used to record exceptions to the test plan
// specification for devices that are known to cause test failures for some
// temporary or permanent reasons.
message Exclusion {
  enum Type {
    // Do not use.
    TYPE_UNSPECIFIED = 0;
    // There are no active plans to remove these exclusions becuase it is
    // prohibitive to fix the issue or business needs do not justify the effort
    // to fix the issue.
    //
    // Each PERMANENT exclusion MUST include references that point to a business
    // justification for its addition.
    PERMANENT = 1;

    // Use for excluding new tests from running on devices where the test has
    // not yet been stabilized. The intention is to support incremental rollout
    // of new tests.
    //
    // These exclsusion are temporary. These exclusions SHOULD be routinely
    // audited and resolved or promoted to PERMANENT exclusions.
    TEMPORARY_NEW_TEST = 2;

    // Use for excluding broken / flakey tests while a fix is being worked on.
    //
    // These exclsusion are temporary. These exclusions SHOULD be routinely
    // audited and resolved or promoted to PERMANENT exclusions.
    TEMPORARY_PENDING_FIX = 3;
  }
  // Required.
  Type type = 1;

  enum Action {
    // Specify no action.
    //
    // The Test Lab Environment may choose any of the available actions based
    // on internal heuristics.
    //
    // The default Action is a good default if none of the considersations for
    // the specific actions below apply.
    ACTION_UNSPECIFIED = 0;

    // Do not schedule the selected Tests on specified Devices Under Test.
    //
    // It is especially useful to set this Action for permanent exceptions as it
    // is definitely not useful to run the Tests at all in those cases.
    DO_NOT_SCHEDULE = 1;

    // Schedule the Test on Devices Under Test as required by the test plan
    // unit, but mark the results for selected tests on the specified Devices
    // Under Test as non-critical. Results marked non-critical are intended to
    // be ignored by result consumers (e.g, presubmit system should consider the
    // result irrelevant for validatting a Chrome OS build).
    //
    // This action does not guarantee that results for the selected (Test,
    // Device Under Test) pairs are always available because that depends no how
    // the test plan Unit is interpreted overall. When this action is set, the
    // Test Lab Environment SHOULD NOT make any special effort to include /
    // exclude the selected (Test, Device Under Test) pairs.
    //
    // It is useful to set this Action for temporary exclusions where the
    // results generated from test execution can be uesd to root cause and fix
    // the underlying issues.
    MARK_NON_CRITICAL = 2;
  }
  Action action = 5;

  // The tests this exclusion applies to, within a test plan unit.
  //
  // Tests selected by this condition that are not in the test plan unit are
  // ignored. e.g., simply selecting all tests via the test_constraint will
  // apply this exclusion to all tests in the test plan unit.
  TestConstraint test_constraint = 2;

  // Constraints to exclude particular Device Under Test from being considered
  // to satisfy the test plan.
  //
  // Effectively, the negation of the constraint is added to the dut_constraints
  // for each selected test.
  DUTExclusionConstraint dut_constraint = 3;

  // External references useful for archeology for this exclusion.
  //
  // PERMANENT exclusions MUST add references for the decision to make the
  // exclusion PERMANENT.
  //
  // References should be links with more context behind the decision.
  // Suggested forms:
  // * Monorail bug: https://bugs.chromium.org/p/chromium/issues/detail?id=XXX
  // * Buganizer bug: https://b.corp.google.com/issues/XXX
  repeated string references = 4;
}

// Conditions to be met for the Chrome OS configuration of a Device Under
// Test for it to be excluded from consideration to satisfy a test plan unit.
message DUTExclusionConstraint {
  // A Common Expression Language (CEL) expression to specify constraints on a
  // Device Under Test's Chrome OS configuration payload. `expression` MUST
  // evaluate to a boolean value in the evaluation context described below.
  //
  // Test Lab Environments may optionally support excluding specific Devices
  // Under Test from being considered for a test plan unit.
  // When supported, the Test Lab Environment MUST effectively evaluate
  // `expression` with the following declarations in scope for each available
  // Device Under Test and ensure that the test is *not* scheduled on a Device
  // Under Test for which `expression` evaluates to true.
  //
  // - Constant: `dut` of type DUTConfigConstraint.DUT defined below, set to the
  //   Chrome OS configuration payload of a particular Device Under Test.
  // - Types: Protobuf messages from `chromiumos.config.api.*`
  //   - Additionally available with the short-hand `api.*`
  //
  // ## Examples
  //
  // Typical examples of expressions are:
  //
  // - Must not run on a device with a given screen size:
  //     dut.hardware_features.screen.milliinch.value == 14000
  // - TODO: Add model / build target example.
  //
  // ## CEL support
  //
  // The full CEL spec can be found at https://github.com/google/cel-spec.
  //
  // Current support for `expression` evaluation is very restricted due to
  // limitations in the scheduling infrastructure used by Test Platform.
  //
  // As this API matures, features will be added to the scheduling
  // infrastructure of Test Platform and restrictions here will be lifted based
  // on requirements collected from test authors. See milestones in
  // go/cros-f20-plan for expected feature iterations. Test Lab Environments
  // SHOULD validate the expression and reject use of unsupported features.
  //
  // TODO(crbug.com/1051689) Add reference to the metadata validator package.
  //
  // ### Syntax
  //
  // See full syntax definition at
  // https://github.com/google/cel-spec/blob/master/doc/langdef.md#syntax
  //
  // CEL standard syntax allows expressions that evaluate to errors (e.g.,
  // syntax allows negation of lists, which has no semantics in CEL).
  // Thus, this spec does not attempt to restrict the syntax, but specifies what
  // operations are unsupported to aid metadata producers. Ultimately, the
  // reference metadata validator is the authority on what expressions are
  // allowed.
  //
  // Unsupported standard CEL semantics:
  //   - Binary arithmetic operations
  //     e.g.: +, *, /, % ...
  //   - Relational Operators beyond (in)equality are not supported.
  //     e.g.: (>, <, >=, <= ...)
  //   - Logical OR in expressions is not supported.
  //     e.g.: (a || b), !(a && b) ...
  //
  // ### Macros
  //
  // See full macro definition at
  // https://github.com/google/cel-spec/blob/master/doc/langdef.md#macros
  //
  // Supported macros: has(), e.all()
  // Unsupported macros: e.exists(), e.exists_one(), e.map(), e.filter()
  //
  // ### Standard functions
  //
  // See full list of standard definitions at
  // https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions
  //
  // Most standard functions are not supported.
  //
  // - Supported operators: !_, -_, _!=_, _&&_, _=_, _[_]
  //   - All other operators are not supported.
  // - All other standard functions are not supported. In particular:
  //   - size() is not supported.
  //   - string functions like endsWith() and contains() are not supported.
  //   - type conversions like int() and string() are not supported.
  //   - reflection with type(), null_type() and dyn() is not supported.
  string expression = 1;

  // The evaluation context for `expression` MUST include the Chrome OS
  // configuration payload for a particular Device Under Test as a typed
  // constant of the following type.
  message DUT {
    chromiumos.config.api.HardwareFeatures hardware_features = 1;
    // TODO(pprabhu, shapiroc) Add a way to target model and build_target here.
  }
}

// Specifies platforms software covered by a test plan unit.
message CodeCoverage {
  // A Common Expression Language (CEL) expression to specify Chrome OS platform
  // sources covered by a test plan unit.
  //
  // Test Platform may optionally support skipping test plan units that are not
  // applicable for incoming changes to Chrome OS. If this feature is supported,
  // and if a non-empty blamelist is available, Test Platform MUST effectively
  // evaluate `expression` with the following declarations in scope for the
  // blamelist only include the test plan unit if the `expression` evaluates to
  // true.
  //
  // - Constant: `blamelist` of type CodeCoverage.Blamelist defined below,
  //   populated with blamelist attached to the request, if blamelist is
  //   non-empty.
  //
  // The full CEL spec can be found at https://github.com/google/cel-spec.
  //
  // TODO(crbug.com/1051689) Add reference to the metadata validator package.
  //
  // ## Examples
  //
  // Typical instructive examples of expressions are:
  //
  // - Only include test plan unit if there are changes to chromite
  //     blamelist.repo_paths.exists(p, p.startsWith("chromite"))
  // - Only include test plan unit if there are changes to chromite or autotest
  //     blamelist.repo_paths.exists(p, [
  //         "src/third_party/autotest/files",
  //         "chromite"
  //       ].exists(s, p.startsWith(s)))
  // - Do not include test plan unit if there are changes to private overlays
  //     blamelist.repo_paths.all(p, !p.contains("private-overlays"))
  //
  // ## CEL support
  //
  // All standard CEL syntax, macros and functions MUST be supported.
  string expression = 1;

  message Blamelist {
    // Changed paths (usually directories) in a typical checkout of the Chrome
    // OS source tree.
    //
    // Paths are relative to `repo` root. e.g., `src/platform2/shill`.
    repeated string repo_paths = 1;
  }
}