| // 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"; |
| |
| // This package contains the definitions for the test metadata generated as |
| // build artifacts for all supported tests. |
| // |
| // This metadata is used for test execution requests, scheduling decisions and |
| // results analytics in various Test Lab Environments. |
| // |
| // Metadata MUST be generated for all tests in supported Remote Test Drivers and |
| // MUST be respected in all Test Lab Environments. |
| package test.metadata.v1; |
| |
| option go_package = "go.chromium.org/chromiumos/infra/proto/go/test/metadata/v1;metadata"; |
| option java_outer_classname = "MetadataProto"; |
| |
| import "google/protobuf/struct.proto"; |
| import "lab/peripherals.proto"; |
| |
| // From chromiumos/config repo. |
| import "api/hardware_topology.proto"; |
| import "api/topology.proto"; |
| |
| // The test metadata specification. |
| // |
| // Test metadata MUST be generated for each Remote Test Driver as one of the |
| // test artifacts generated from Chrome OS build system. |
| message Specification { |
| // A set of Remote Test Driver packages. |
| // |
| // In practice, a complete specification of all known Remote Test Drivers may |
| // consist of multiple Specification instances. In that case the test names |
| // MUST be unique across different Specification instances. |
| // |
| // Unlike tests, a RemoteTestDriver (identified by its name) may be specified |
| // multiple times, in a single Specification or across different Specification |
| // instances. In that case, all fields except the list of tests MUST be |
| // identical across these RemoteTestDriver instances. The list of tests across |
| // these instances will be concatenated together. |
| repeated RemoteTestDriver remote_test_drivers = 1; |
| } |
| |
| // go/cros-rtd-spec describes the Remote Test Driver bootstrapping flow inside |
| // the Remote Test Server. Remote Test Driver configures the bootstrapping flow |
| // for a test invocation. |
| message RemoteTestDriver { |
| // Globally unique name for a Remote Test Driver package. |
| // |
| // |
| // MUST be a valid resource per https://aip.dev/122. |
| // |
| // Pattern: remoteTestDrivers/{remoteTestDriver} |
| // |
| // The two most commonly used Remote Test Drivers are named |
| // - remoteTestDrivers/tauto |
| // - remoteTestDrivers/tast |
| // and contain the common public tests written in the Tauto and Tast framework |
| // respectively. |
| string name = 1; |
| |
| // A container image containing all the required dependencies and other build |
| // artifacts required for test invocations. |
| // |
| // Test Lab Environments SHOULD fail with an error indicating that the request |
| // was invalid if the image fails to be found for a test invocation. |
| BuildArtifact image = 2; |
| |
| // Command to invoke the Remote Test Driver inside `image`. |
| // |
| // Remote Test Servers MUST run `command` as |
| // $ ${command} -input_json ${input_json} |
| // where ${command} and ${input_json} are absolute paths inside the container. |
| // |
| // Remote Test Servers MUST populate `input_json` with a JSON encoded |
| // test.invocation.Request message. |
| string command = 3; |
| |
| // Metadata for the smallest schedulable test units. |
| repeated Test tests = 4; |
| } |
| |
| // A Chrome OS build artifact required for test execution. |
| message BuildArtifact { |
| // All build artifacts are assumed to be archived in some common directory |
| // root. `relative_path` is the relative path inside the root archive |
| // directory. |
| // |
| // Infrastructure Test Lab Environment: Chrome OS Continuous Integration |
| // builders archive build artifacts to a path on Google Storage. The Test |
| // Platform requests include a reference to the root archival path. |
| // e.g., |
| // * The builder archives all build artifacts to |
| // gs://chromeos-image-archive/link-release/R64-0.0.0.0/ |
| // * Test Platform request includes this archival path. |
| // * `relative_path` is set to tast/mighty.bin |
| // * Then, the full path to the artifact is |
| // gs://chromeos-image-archive/link-release/R64-0.0.0.0/tast/mighty.bin |
| // |
| // Developer Test Lab Environment: For developer flow outside of the |
| // infrastructure, it is assumed that the build artifacts are available at a |
| // local path with the same directory layout as the Google Storage archival. |
| // e.g., |
| // * Local build copies all artifacts to /tmp/cbuildbot/archive/ |
| // * Local tooling includes a reference to this path. |
| // * `relative_path` is set to tauto/ssp.bin |
| // * Then, the full path to the artifact is |
| // /tmp/cbuildbot/archive/tauto/ssp.bin |
| string relative_path = 1; |
| } |
| |
| // The smallest schedulable test unit. |
| // |
| // A Test is an atomic schdulable unit. In particular, it is not possible to |
| // modify the behaviour of a Remote Test Driver execution for a given Test by |
| // supplying test arguments. See the documentation of |
| // test.metadata.v1.Informational on how paramaterized tests may be in light of |
| // this restriction. |
| // |
| // A single test platform request or Remote Test Driver invocation may contain |
| // multiple instances of multiple Tests, but each instance of a Test MUST |
| // correspond to exactly one reported result. |
| // |
| // See Also: |
| // Test Platform request: TODO(pprabhu) |
| // Remote Test Driver invocation request: test/rtd/invocation.proto |
| // Remote Test Driver progress API: test/rtd/progress.proto |
| message Test { |
| // Globally unique name for this test. |
| // |
| // MUST be a valid resource per https://aip.dev/122. |
| // |
| // Pattern: remoteTestDrivers/{remoteTestDriver}/tests/{test} |
| // where {remoteTestDriver} is the Remote Test Driver package that contains |
| // this test. |
| string name = 1; |
| |
| // Attributes are used to include tests in test plans. |
| // |
| // See Also: |
| // Test plans: test/plan/plan.proto |
| repeated Attribute attributes = 2; |
| |
| // Required condition to be met for each Device Under Test targeted by this |
| // test. |
| // |
| // Condition enforcement is an optional feature for test scheduling, i.e., |
| // some Test Lab Environments may ignore conditions entirely. |
| // |
| // May be specified multiple times for tests that target more than one Device |
| // Under Test, once per required device. |
| repeated DUTCondition conditions = 3; |
| |
| // Metadata about the test that doesn't affect scheduling or execution. |
| Informational informational = 4; |
| } |
| |
| // Attributes used to include tests in test plans. |
| message Attribute { |
| // Opaque name for this attribute. |
| // |
| // Value MUST be valid resource names per https://aip.dev/122. |
| // |
| // MUST NOT be interpreted by Test Lab Environments. |
| string name = 1; |
| } |
| |
| // Condition to be met for each Device Under Test targeted by a test. |
| message DUTCondition { |
| // A Common Expression Language (CEL) expression to specify DUT conditions. |
| // |
| // Test Lab Environments may optionally support targeting test requests to |
| // Device Under Test based on DUTConditions. If this feature is supported, the |
| // Test Lab Environment MUST interpret `expression` in the scope of the |
| // protobuf message DUTCondition.Scope as defined below. |
| // |
| // The full CEL spec can be found at https://github.com/google/cel-spec. |
| // This API only currently only supports a small sub-set of the CEL features, |
| // as described here. Test Lab Environments SHOULD 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: |
| // |
| // - A specific characteristic for a hardware feature, e.g.: |
| // scope.hardware_topology.screen.milliinch.value == 14000 |
| // - A specific topology for a hardware feature, e.g.: |
| // scope.hardware_topology.form_factor.id == "fancy_clamshell" |
| // - Existence of a hardware feature, e.g.: |
| // scope.hardware_features.lte == scope.hardware_features.PRESENT |
| // - Exclude certain hardware topologies, e.g.: |
| // scope.hardware_topology.stylus.id != "pencil" |
| // |
| // ## CEL support |
| // |
| // Current support for `expression` evaluation is very restricted due to |
| // limitations in the scheduling platform used by Test Platform. Specifying |
| // the conditions in CEL will allow gradual lifting of support restrictions. |
| // |
| // 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. |
| // |
| // ### Evaluation context |
| // |
| // In general, a CEL expression must be evaluated in some context that |
| // provides the basic bindings for name resolution. |
| // |
| // In this case, `expression` MUST be evaluated in a context that contains |
| // |
| // - A variable 'scope' of type DUTCondition.Scope. This variable contains the |
| // information about a particular Device Under Test being tested for |
| // acceptance via `expression`. |
| // - Protobuf definitions in this git project (i.e., rooted at infra/proto/). |
| // |
| // ### 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 take note: |
| // - 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; |
| |
| // Protocol buffer scope for interpretation of `expression`. |
| // |
| // Scope includes the Device Under Test features that can be targeted for test |
| // targeting. |
| message Scope { |
| // Peripherals information about the lab deployment of the device. |
| lab.Peripherals peripherals = 1; |
| // The relationship between topology and features is described at |
| // https://chromium.googlesource.com/chromiumos/config/+/master/proto/api/hardware_topology.md |
| chromiumos.config.api.HardwareTopology hardware_topology = 2; |
| chromiumos.config.api.HardwareFeatures hardware_features = 3; |
| } |
| } |
| |
| // Contains metadata about the test that doesn't affect scheduling or execution. |
| message Informational { |
| // Contacts for ownership / flakiness notification etc. |
| repeated Contact authors = 1; |
| |
| // Machine readable test-specific information. |
| // |
| // Remote Test Drivers SHOULD include detailed information to aid analytics. |
| // For example, test authors may minimize code duplication by writing |
| // paramterized tests. Thus, multiple test metadata may refer to the |
| // same test implementation with different arguments. It is useful to include |
| // this information as details. An example for Tauto: |
| // { |
| // "test_project": "chromiumos/third_party/autotest", |
| // "control_file": "site_tests/dummy_Pass/control.stress", |
| // "args": { |
| // "run_count": 35 |
| // } |
| // } |
| // |
| // This field MUST NOT be interpreted by the Test Lab Environments, but Remote |
| // Test Drivers can enrich analytics by using uniform stable schema for |
| // details across all their tests. |
| google.protobuf.Struct details = 2; |
| } |
| |
| // Contact information of individuals or teams. |
| message Contact { |
| oneof type { |
| // e.g.: user@google.com |
| string email = 1; |
| // e.g.: team-name (not mdb/team-name) |
| string mdb_group = 2; |
| } |
| } |