resultdb/proto/v1/common.proto

// Copyright 2019 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package luci.resultdb.v1;

option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";

// A key-value map describing one variant of a test case.
//
// The same test case can be executed in different ways, for example on
// different OS, GPUs, with different compile options, runtime flags or even
// with different values of the test parameter (for parameterized tests).
// A variant definition captures one variant.
// A test case with a specific variant definition is called test variant.
//
// Guidelines for variant definition design:
// - This rule guides what keys MUST be present in the definition.
//   A single expected result of a given test variant is enough to consider it
//   passing (potentially flakily). If it is important to differentiate across
//   a certain dimension (e.g. whether web tests are executed with or without
//   site per process isolation), then there MUST be a key that captures the
//   dimension (e.g. a name from test_suites.pyl).
//   Otherwise, a pass in one variant will hide a failure of another one.
//
// - This rule guides what keys MUST NOT be present in the definition.
//   A change in the key-value set essentially resets the test result history.
//   For example, if GN args are among variant key-value pairs, then adding a
//   new GN arg changes the identity of the test variant and resets its history.
//
// In Chromium, typical variant keys are:
// - bucket: the LUCI bucket, e.g. "ci"
// - builder: the LUCI builder, e.g. "linux-rel"
// - test_suite: a name from
//   https://cs.chromium.org/chromium/src/testing/buildbot/test_suites.pyl
message Variant {
  // The definition of the variant.
  // Key and values must be valid StringPair keys and values, see their
  // constraints.
  map<string, string> def = 1;
}

// A string key-value pair. Typically used for tagging, see Invocation.tags
message StringPair {
  // Regex: ^[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*$
  // Max length: 64.
  string key = 1;

  // Max length: 256.
  string value = 2;
}