From b71a755c8cf963f89dbf58349c2e9c99b7cf2f1e Mon Sep 17 00:00:00 2001
From: Ryan Cole <rcyoalne@gmail.com>
Date: Wed, 31 Jan 2024 13:34:43 -0500
Subject: [PATCH] doc(stoneintg-756): write how to manually re-trigger
 integration test

Add a document that describes the procedure for manually re-triggering
an integration test.

Signed-off-by: Ryan Cole <rcyoalne@gmail.com>
Co-authored-by: Ralph Bean <rbean@redhat.com>
Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com>
---
 docs/modules/ROOT/nav-how-to-guides.adoc      |  1 +
 .../proc_retriggering_integration_tests.adoc  | 38 +++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc

diff --git a/docs/modules/ROOT/nav-how-to-guides.adoc b/docs/modules/ROOT/nav-how-to-guides.adoc
index 4fc169bc..b121f08d 100644
--- a/docs/modules/ROOT/nav-how-to-guides.adoc
+++ b/docs/modules/ROOT/nav-how-to-guides.adoc
@@ -13,6 +13,7 @@
 *** xref:how-to-guides/testing_applications/surface-level_tests.adoc[Surface-level tests]
 *** xref:how-to-guides/testing_applications/proc_adding_an_integration_test.adoc[Adding an integration test]
 *** xref:how-to-guides/testing_applications/proc_creating_custom_test.adoc[Creating a custom integration test]
+*** xref:how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc[Retriggering integration tests]
 ** Managing environments
 *** xref:how-to-guides/managing-environments/con_overview_of_environments.adoc[Overview of {ProductName} environments]
 *** xref:how-to-guides/managing-environments/proc_creating_your_own_environment.adoc[Creating your own environment]
diff --git a/docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc b/docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc
new file mode 100644
index 00000000..2c6e0777
--- /dev/null
+++ b/docs/modules/ROOT/pages/how-to-guides/testing_applications/proc_retriggering_integration_tests.adoc
@@ -0,0 +1,38 @@
+= Retriggering Integration Tests
+
+Integration test scenarios for a given snapshot can be re-triggered by adding a label to the snapshot.
+
+== Prerequisites
+- You have a snapshot that has completed all its initial tests. All initial tests must be finished before you trigger subsequent tests.
+- The snapshot for which tests will be retriggered has completed its initial tests
+- You have CLI access to the specific OpenShift cluster. For information on obtaining CLI access, refer to  xref:../../getting-started/getting_started_in_cli.adoc[Getting started in CLI]
+- You have an up-to-date kubectl binary.  Alternatively, the `oc` binary is also compatible.
+
+== Procedure
+. Identify the IntegrationTestScenario that needs to be rerun.  For a given snapshot, you can only rerun one IntegrationTestScenario.
+. Label the snapshot with `test.appstudio.openshift.io/run`, assigning the scenario name you wish to rerun as its value.
+[source]
+$ kubectl label [snapshot name] test.appstudio.openshift.io/run=[scenario name]
+
+. The tests are re-triggered automatically.  Once they are re-triggered, the system removes the label, allowing you to apply a new label for a different scenario if you wish to test multiple scenarios.
+[source]
+$ tkn pipelinerun list
+
+[Example Output]
+NAME                            STARTED         DURATION   STATUS
+integration-pipelinerun-jfrdb   4 seconds ago   ---        Running
+
+. To verify the tests, run `tkn pipelinerun describe [pipelinerun]` and ensure that the labels `appstudio.openshift.io/snapshot` and `test.appstudio.openshift.io/scenario` reference the correct snapshot and scenario.
+[source]
+$ tkn pipelinerun describe integration-pipelinerun-jfrdb
+
+[Expected labels in the output]
+Name:              integration-pipelinerun-jfrdb
+Namespace:         default
+Service Account:   appstudio-pipeline
+Labels:
+...
+ appstudio.openshift.io/snapshot=snapshot-sample
+...
+ test.appstudio.openshift.io/test=component
+...