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;

import "google/protobuf/timestamp.proto";

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 or runtime flags.
// 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, 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;
}

// CommitPosition specifies the numerical position of the commit an invocation
// runs against, in a repository's commit log. More specifically, a ref's commit
// log.
// It also specifies the repo/ref combination that the commit position exists
// in, to provide context.
message CommitPosition {
  // The following fields identify a git repository and a ref within which the
  // numerical position below identifies a single commit.
  string host = 1;
  string project = 2;
  string ref = 3;

  // The numerical position of the commit in the log for the host/project/ref
  // above.
  int64 position = 4;
}

// A range of commit positions.
// Commit positions are assumed to increase from earliest to latest.
// Note that if both earliest and latest are set, their host/project/ref must
// be identical.
// Used for specifying ranges to query in ResultDB.GetTestResultHistory.
message CommitPositionRange {
  // The lowest commit position to include in the range.
  CommitPosition earliest = 1;

  // Include only commit positions that that are strictly lower than this.
  CommitPosition latest = 2;
}

// A range of timestamps.
// Used for specifying ranges to query in ResultDB.GetTestResultHistory.
message TimeRange {
  // The oldest timestamp to include in the range.
  google.protobuf.Timestamp earliest = 1;

  // Include only timestamps that are strictly older than this.
  google.protobuf.Timestamp latest = 2;
}