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

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "common.proto";

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

// A result of a functional test case.
// Often a single test case is executed multiple times and has multiple results,
// a single test suite has multiple test cases,
// and the same test suite can be executed in different variants
// (OS, GPU, compile flags, etc).
//
// This message does not specify the test id.
// It should be available in the message that embeds this message.
message TestResult {
  // Test id, a unique identifier of the test in a LUCI project.
  // Regex: ^[[::print::]]{1,256}$
  //
  // If two tests have a common test id prefix that ends with a
  // non-alphanumeric character, they considered a part of a group. Examples:
  // - "a/b/c"
  // - "a/b/d"
  // - "a/b/e:x"
  // - "a/b/e:y"
  // - "a/f"
  // This defines the following groups:
  // - All items belong to one group because of the common prefix "a/"
  // - Within that group, the first 4 form a sub-group because of the common
  //   prefix "a/b/"
  // - Within that group, "a/b/e:x" and "a/b/e:y" form a sub-group because of
  //   the common prefix "a/b/e:".
  // This can be used in UI.
  // LUCI does not interpret test ids in any other way.
  string test_id = 1;

  // Identifies a test result in a given invocation and test id.
  // Regex: ^[[:ascii:]]{1,32}$
  string result_id = 2;

  // Whether the result of test case execution is expected.
  // In a typical Chromium CL, 99%+ of test results are expected.
  // Users are typically interested only in the unexpected results.
  //
  // An unexpected result != test case failure. There are test cases that are
  // expected to fail/skip/crash. The test harness compares the actual status
  // with the expected one(s) and this field is the result of the comparison.
  bool expected = 3;

  // Machine-readable status of the test case.
  // MUST NOT be STATUS_UNSPECIFIED.
  TestStatus status = 4;

  // Human-readable explanation of the result, in HTML.
  // MUST be sanitized before rendering in the browser.
  //
  // The size of the summary must be equal to or smaller than 4096 bytes in
  // UTF-8.
  string summary_html = 5;

  // The point in time when the test case started to execute.
  google.protobuf.Timestamp start_time = 6;

  // Duration of the test case execution.
  // MUST be equal to or greater than 0.
  google.protobuf.Duration duration = 7;

  // Metadata for this test result.
  // It might describe this particular execution or the test case.
  repeated luci.resultdb.v1.StringPair tags = 8;

  // Artifacts to upload and associate with this test result.
  // The map key is an artifact id.
  map<string, Artifact> artifacts = 9;
}

// Machine-readable status of a test result.
enum TestStatus {
  // Status was not specified.
  // Not to be used in actual test results; serves as a default value for an
  // unset field.
  STATUS_UNSPECIFIED = 0;

  // The test case has passed.
  PASS = 1;

  // The test case has failed.
  // Suggests that the code under test is incorrect, but it is also possible
  // that the test is incorrect or it is a flake.
  FAIL = 2;

  // The test case has crashed during execution.
  // The outcome is inconclusive: the code under test might or might not be
  // correct, but the test+code is incorrect.
  CRASH = 3;

  // The test case has started, but was aborted before finishing.
  // A common reason: timeout.
  ABORT = 4;

  // The test case did not execute.
  // Examples:
  // - The execution of the collection of test cases, such as a test
  //   binary, was aborted prematurely and execution of some test cases was
  //   skipped.
  // - The test harness configuration specified that the test case MUST be
  //   skipped.
  SKIP = 5;
}

// A local equivalent of luci.resultdb.Artifact message
// in ../../rpc/v1/artifact.proto.
// See its comments for details.
// Does not have a name or artifact_id because they are represented by the
// TestResult.artifacts map key.
message Artifact {
  oneof body {
    // Absolute path to the artifact file on the same machine as the
    // ResultSink server.
    string file_path = 1;

    // Contents of the artifact. Useful when sending a file from a different
    // machine.
    // TODO(nodir, sajjadm): allow sending contents in chunks.
    bytes contents = 2;
  }

  // Equivalent of luci.resultdb.v1.Artifact.content_type.
  string content_type = 3;
}

// A file with test results.
message TestResultFile {
  // Absolute OS-native path to the results file on the same machine as the
  // ResultSink server.
  string path = 1;

  // A result file format.
  enum Format {
    // The file is a sequence of TestResult JSON objects (not a JSON Array).
    // The default format.
    LUCI = 0;

    // Chromium's JSON Test Results format
    // https://chromium.googlesource.com/chromium/src/+/master/docs/testing/json_test_results_format.md
    CHROMIUM_JSON_TEST_RESULTS = 1;

    // GTest format.
    // Not well documented.
    // Implementation:
    // https://cs.chromium.org/chromium/src/base/test/launcher/test_results_tracker.cc
    GOOGLE_TEST = 2;
  }

  // Format of the file.
  Format format = 2;
}