From ed10d3fa15bf368f859bc2d28a1c5b4995116e81 Mon Sep 17 00:00:00 2001 From: Mike Han Date: Tue, 23 Apr 2024 09:54:23 -0600 Subject: [PATCH] Describe the V2 assets approach --- .../automated-testing/_partials/_advanced.md | 30 +++++++++++++++++-- .../automated-testing/cypress/yaml/v1.md | 2 +- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/web-apps/automated-testing/_partials/_advanced.md b/docs/web-apps/automated-testing/_partials/_advanced.md index e3ac28f694..39266ae05a 100644 --- a/docs/web-apps/automated-testing/_partials/_advanced.md +++ b/docs/web-apps/automated-testing/_partials/_advanced.md @@ -153,12 +153,36 @@ This feature is highly experimental. ## Attaching Test Assets -Any test assets created by your tests at runtime (such as logs, screenshots or reports) you wish to retain along with your test results must be placed in the `__assets__` directory of your project root folder. On Sauce Labs VMs, this path is relative to the current working directory. +By default, any test assets created by your tests at runtime (such as logs, screenshots or reports) you wish to retain along with your test results must be placed in the `__assets__` directory of your project root folder. On Sauce Labs VMs, this path is relative to the current working directory. + +### Attaching entire directories + +In situations where you want to preserve the file structure of your assets (e.g. a multi-page HTML report), +you can use the `retain` feature to define a directory to archive and store as a test asset. + +### Handling nested assets -:::note Nested Paths Nested assets are stored **flat** in Sauce Labs. A test asset like `__assets__/mylogs/log.txt` would therefore be stored and available for download as `log.txt`. Please keep that in mind when creating custom assets, as examples like `__assets__/mylogs/log.txt` and `__assets__/myotherlogs/log.txt` would eventually collide when persisted. -::: + +There are cases where you may want to override this default behaviour; e.g. your test framework generates +an HTML report and you want to preserve the entire report directory and don't want the individual files to +be flattened and automatically attached as described above. In that case, you can set an environment variable +in your saucectl config to opt out of the default behaviour. When set, the configured output directory +for the test run will be honoured; e.g. it won't be overridden to `__assets__/`. + +```yaml title= "example configuration" +artifacts: + retain: + report-directory: archived-report.zip + +env: + SAUCE_SYNC_WEB_ASSETS: "true" +``` + +When configured this way, the directory named `report-directory` will be archived as `archived-report.zip`. +To maintain backwards compatibility, some asset types (e.g. images, logs, etc.) in `report-directory` will be +automatically attached to the test results. ## Setting up a Proxy diff --git a/docs/web-apps/automated-testing/cypress/yaml/v1.md b/docs/web-apps/automated-testing/cypress/yaml/v1.md index 8bb7c7216e..7c3a99d91a 100644 --- a/docs/web-apps/automated-testing/cypress/yaml/v1.md +++ b/docs/web-apps/automated-testing/cypress/yaml/v1.md @@ -644,7 +644,7 @@ artifacts: 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, via the -[REST API](https://docs.saucelabs.com/dev/api/jobs/#get-a-job-asset-file), or through the test details page. +[REST API](/dev/api/jobs/#get-a-job-asset-file), or through the test details page. ```yaml artifacts: