From a6d983b101062a4e3806eb4e6794f02a4368cfe0 Mon Sep 17 00:00:00 2001
From: Mike Han <mike.han@saucelabs.com>
Date: Mon, 22 Apr 2024 15:13:27 -0600
Subject: [PATCH] docs: Document the retain feature

---
 .../automated-testing/cypress/yaml/v1.md      | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/web-apps/automated-testing/cypress/yaml/v1.md b/docs/web-apps/automated-testing/cypress/yaml/v1.md
index 179a81829c..8aa05b6ff6 100644
--- a/docs/web-apps/automated-testing/cypress/yaml/v1.md
+++ b/docs/web-apps/automated-testing/cypress/yaml/v1.md
@@ -613,10 +613,13 @@ Specifies how to manage test artifacts, such as logs, videos, and screenshots.
 ```yaml
 artifacts:
   cleanup: true
+  retain:
+    generated-report-dir: report.zip
   download:
     when: always
     match:
       - junit.xml
+      - report.zip
     directory: ./artifacts/
 ```
 
@@ -635,6 +638,35 @@ artifacts:
 
 ---
 
+### `retain`
+
+<p><small>| OPTIONAL | OBJECT |</small></p>
+
+Define directories to archive and retain as a test asset at the end of a test run. Archived test assets can
+be downloaded automatically using the `download` configuration or via the 
+[REST API](https://docs.saucelabs.com/dev/api/jobs/#get-a-job-asset-file) or through the test details page.
+
+```yaml
+artifacts:
+  retain:
+    source-directory: destination-archive.zip
+  download:
+    when: always
+    match:
+      - destination-archive.zip
+    directory: ./artifacts/
+```
+
+:::note
+The source and destination will be relative to the `rootDir` defined in your configuration.
+:::
+
+:::note
+The destination archive must have a .zip file extension.
+:::
+
+---
+
 ### `download`
 
 <p><small>| OPTIONAL | OBJECT |</small></p>