Reinstate system and staging tests as first-class citizens

2 files changed, 40 insertions, 8 deletions

diff --git a/tenant-cd/src/main/java/ai/vespa/hosted/cd/StagingTest.java b/tenant-cd/src/main/java/ai/vespa/hosted/cd/StagingTest.java
index ee2ee0add4c..40377da30ef 100644
--- a/tenant-cd/src/main/java/ai/vespa/hosted/cd/StagingTest.java
+++ b/tenant-cd/src/main/java/ai/vespa/hosted/cd/StagingTest.java
@@ -2,9 +2,21 @@
 package ai.vespa.hosted.cd;
 
 /**
- * @deprecated Use {@link UpgradeTest}.
+ * Tests that assert continuity of behaviour for Vespa application deployments, through upgrades.
+ *
+ * These tests are run whenever a change is pushed to a Vespa application, and whenever the Vespa platform
+ * is upgraded, and before any deployments to production zones. When these tests fails, the tested change to
+ * the Vespa application is not rolled out.
+ *
+ * A typical upgrade test is to do some operations against a test deployment prior to upgrade, like feed and
+ * search for some documents, perhaps recording some metrics from the deployment, and then to upgrade it,
+ * repeat the exercise, and compare the results from pre and post upgrade.
+ *
+ * TODO Split in platform upgrades and application upgrades?
+ *
+ * @author jonmv
  */
-@Deprecated
-public class StagingTest {
-
+public interface StagingTest {
+    // Want to verify documents are not damaged by upgrade.
+    // May want to verify metrics during upgrade.
 }
diff --git a/tenant-cd/src/main/java/ai/vespa/hosted/cd/SystemTest.java b/tenant-cd/src/main/java/ai/vespa/hosted/cd/SystemTest.java
index 6a8d1b4cbe4..c67d86fc8de 100644
--- a/tenant-cd/src/main/java/ai/vespa/hosted/cd/SystemTest.java
+++ b/tenant-cd/src/main/java/ai/vespa/hosted/cd/SystemTest.java
@@ -2,9 +2,29 @@
 package ai.vespa.hosted.cd;
 
 /**
- * @deprecated use {@link FunctionalTest}.
+ * Tests that compare the behaviour of a Vespa application deployment against a fixed specification.
+ *
+ * These tests are run whenever a change is pushed to a Vespa application, and whenever the Vespa platform
+ * is upgraded, and before any deployments to production zones. When these tests fails, the tested change to
+ * the Vespa application is not rolled out.
+ *
+ * A typical system test is to feed some documents, optionally verifying that the documents have been processed
+ * as expected, and then to see that queries give the expected results. Another common use is to verify integration
+ * with external services.
+ *
+ * @author jonmv
  */
-@Deprecated
-public class SystemTest {
-
+public interface SystemTest {
+    // Want to feed some documents.
+    // Want to verify document processing and routing is as expected.
+    // Want to check recall on those documents.
+    // Want to verify queries give expected documents.
+    // Want to verify searchers.
+    // Want to verify updates.
+    // Want to verify deletion.
+    // May want to verify reprocessing.
+    // Must likely delete documents between tests.
+    // Must be able to feed documents, setting route.
+    // Must be able to search.
+    // Must be able to visit.
 }