From f4e7335923f849d1471309b848c4db0f4933e75b Mon Sep 17 00:00:00 2001
From: Aditya Sirish <aditya@saky.in>
Date: Mon, 13 Mar 2023 16:00:06 -0400
Subject: [PATCH] Add predicate capturing results of test runs

Signed-off-by: Aditya Sirish <aditya@saky.in>
---
 spec/predicates/test-results.md | 146 ++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 spec/predicates/test-results.md

diff --git a/spec/predicates/test-results.md b/spec/predicates/test-results.md
new file mode 100644
index 00000000..696e9474
--- /dev/null
+++ b/spec/predicates/test-results.md
@@ -0,0 +1,146 @@
+# Predicate type: Test Results
+
+Type URI: https://in-toto.io/attestation/test-result/v0.1
+
+Version: 0.1.0
+
+Authors:
+
+## Purpose
+
+This predicate type defines a generic schema to express the result of running
+tests in software supply chains. The schema may be extended to support different
+types of testing or specific test harnesses.
+
+## Use Cases
+
+Software development processes include several types of tests. This attestation
+can be used to express the results of running those tests. It can be used to
+verify:
+
+1.  that all tests were in fact run, and
+2.  that all required tests passed
+
+Therefore, each attestation corresponds to one invocation of a test suite, and
+may include the results of several individual tests.
+
+## Prerequisites
+
+Understanding of the
+[in-toto attestation specification](https://github.com/in-toto/attestation).
+
+## Model
+
+This predicate type includes one compulsory field, `result`, that describes the
+result of the test run. The `testRun` object can be used to communicate a link
+to the test run and list tests that passed, failed, and passed with warnings. It
+also may optionally contain a reference to the configuration for the test run.
+
+## Schema
+
+```json
+{
+    "_type": "https://in-toto.io/Statement/v1",
+    "subject": [{...}],
+    "predicateType": "https://in-toto.io/attestation/test-result/v0.1",
+    "predicate": {
+        "result": "pass/fail",
+        "testRun": {
+            "link": "<URL>",
+            "configuration": "<ResourceDescriptor>",
+            "passedTests": ["<TEST_NAME>", ...],
+            "warnedTests": ["<TEST_NAME>", ...],
+            "failedTests": ["<TEST_NAME>", ...]
+        }
+    }
+}
+```
+
+### Parsing Rules
+
+This predicate follows the in-toto attestation parsing rules. Summary:
+
+-   Consumers MUST ignore unrecognized fields.
+-   The `predicateType` URI includes the major version number and will always
+    change whenever there is a backwards incompatible change.
+-   Minor version changes are always backwards compatible and “monotonic.” Such
+    changes do not update the `predicateType`.
+-   Producers MAY add extension fields using field names that are URIs.
+-   Fields marked _optional_ MAY be unset or null, and should be treated
+    equivalently. Both are equivalent to empty for object or array values.
+
+### Fields
+
+`result` _boolean_ , _required_
+
+Indicates the result of the test run. If true, it indicates _all_ tests passed
+in the corresponding run.
+
+`testRun` _object_, _optional_
+
+`testRun.link` _URI_, _optional_
+
+Contains a link to the test run. Useful to point to information that cannot be
+captured in the attestation.
+
+`testRun.configuration` _ResourceDescriptor_, _optional_
+
+Reference to the configuration used for the test run.
+
+`testRun.passedTests` _list_, _optional_
+
+Each entry corresponds to a single test that passed.
+
+`testRun.warnedTests` _list_, _optional_
+
+Each entry corresponds to a single test that expressed a warning.
+
+`testRun.failedTests` _list_, _optional_
+
+Each entry corresponds to a single test that failed.
+
+## Example
+
+```json
+{
+    "_type": "https://in-toto.io/Statement/v1",
+    "subject": [
+        {
+            "digest": {
+                "gitCommit": "d20ace7968ba43c0219f62d71334c1095bab1602"
+            }
+        }
+    ],
+    "predicateType": "https://in-toto.io/attestation/test-result/v0.1",
+    "predicate": {
+        "result": "pass",
+        "testRun": {
+            "link": "https://github.com/in-toto/in-toto/actions/runs/4425592351",
+            "configuration": {
+                "name": ".github/workflows/ci.yml",
+                "downloadLocation": "https://github.com/in-toto/in-toto/blob/d20ace7968ba43c0219f62d71334c1095bab1602/.github/workflows/ci.yml",
+                "digest": {
+                    "gitBlob": "ebe4add40f63c3c98bc9b32ff1e736f04120b023"
+                }
+            },
+            "passedTests": [
+                "build (3.7, ubuntu-latest, py)",
+                "build (3.7, macos-latest, py)",
+                "build (3.7, windows-latest, py)",
+                "build (3.8, ubuntu-latest, py)",
+                "build (3.8, macos-latest, py)",
+                "build (3.8, windows-latest, py)",
+                "build (3.9, ubuntu-latest, py)",
+                "build (3.9, macos-latest, py)",
+                "build (3.9, windows-latest, py)",
+                "build (3.10, ubuntu-latest, py)",
+                "build (3.10, macos-latest, py)",
+                "build (3.10, windows-latest, py)",
+                "build (3.x, ubuntu-latest, lint)"
+            ],
+            "warnedTests": [],
+            "failedTests": []
+        }
+    }
+}
+```