feat: add task to upload asset to Sauce for spec test job (#86)

* feat: add task to upload assets to Sauce for spec test jobs

* docs: add example

* add more validation

* rename function

* add comments to explain why using spec basename as the key

* rename specAssets to specAssetsMap

* add comment for specAssetsMap

* upload multiple assets

* fix README

* use Variadic function

* update README

* fix format

* update integration test

* put the reading stream in a task

* use txt extension

* revert debug step

* kill all warnings

* reword

* refine comment

* remove data param

* make filename optional

* revert integration setup for fs operation

* update test

* eslint for Buffer is not required

* make the doc more natural to read

* refine examples

.github/workflows/tests.yml

@@ -52,8 +52,8 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version-file: '.nvmrc'
-          cache: 'npm'
+          node-version-file: ".nvmrc"
+          cache: "npm"
 
       - name: Install Dependencies
         run: npm ci

README.md

@@ -32,15 +32,15 @@ Sauce Labs. Your Sauce Labs Username and Access Key are available from your
 Example `cypress.config.cjs`:
 
 ```javascript
-const { defineConfig } = require('cypress');
+const { defineConfig } = require("cypress");
 
 module.exports = defineConfig({
   e2e: {
     setupNodeEvents(on, config) {
-      require('@saucelabs/cypress-plugin').default(on, config, {
-        region: 'us-west-1',
-        build: 'myBuild',
-        tags: ['example1'],
+      require("@saucelabs/cypress-plugin").default(on, config, {
+        region: "us-west-1",
+        build: "myBuild",
+        tags: ["example1"],
       });
       return config;
     },
@@ -51,16 +51,16 @@ module.exports = defineConfig({
 Example `cypress.config.mjs`:
 
 ```javascript
-import { defineConfig } from 'cypress';
-import reporter from '@saucelabs/cypress-plugin';
+import { defineConfig } from "cypress";
+import reporter from "@saucelabs/cypress-plugin";
 
 export default defineConfig({
   e2e: {
     setupNodeEvents(on, config) {
       reporter.default(on, config, {
-        region: 'us-west-1',
-        build: 'myBuild',
-        tags: ['example1'],
+        region: "us-west-1",
+        build: "myBuild",
+        tags: ["example1"],
       });
       return config;
     },
@@ -71,16 +71,16 @@ export default defineConfig({
 Example `cypress.config.ts`:
 
 ```typescript
-import { defineConfig } from 'cypress';
-import Reporter, { Region } from '@saucelabs/cypress-plugin';
+import { defineConfig } from "cypress";
+import Reporter, { Region } from "@saucelabs/cypress-plugin";
 
 export default defineConfig({
   e2e: {
     setupNodeEvents(on, config) {
       Reporter(on, config, {
         region: Region.USWest1, // us-west-1 is the default
-        build: 'myBuild',
-        tags: ['example1'],
+        build: "myBuild",
+        tags: ["example1"],
       });
       return config;
     },
@@ -96,10 +96,10 @@ Register the plugin in your project's `cypress/plugins/index.js`:
 module.exports = (on, config) => {
   // Other plugins you may already have.
   // ...
-  require('@saucelabs/cypress-plugin').default(on, config, {
-    region: 'us-west-1',
-    build: 'myBuild',
-    tags: ['example1'],
+  require("@saucelabs/cypress-plugin").default(on, config, {
+    region: "us-west-1",
+    build: "myBuild",
+    tags: ["example1"],
   });
   return config;
 };
@@ -134,6 +134,38 @@ Jobs reported to Sauce Labs:
   └────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
+## Upload Assets Task
+
+This task allows you to upload assets (such as images or logs) to a specific Sauce Labs job associated with the test spec.
+
+| Parameter           | Type                 | Description                                                                                                                                                               |
+| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec`              | `string`             | Path to the spec file being executed, typically provided by `__filename`.                                                                                                 |
+| `assets`            | `Asset` \| `Asset[]` | Can be a single `Asset` object or an array of `Asset` objects to be uploaded to Sauce Labs. Each `Asset` should contain a `filename` and either a `path` or `data`.       |
+| `assets[].path`     | `string`             | **Required**. Path to the file on the local filesystem (e.g., `"pics/this-is-fine.png"`).                                                                                 |
+| `assets[].filename` | `string`             | **Optional**. The name of the file to upload, as it should appear in Sauce Labs (e.g., `"this-is-fine.png"`). If not provided, the file path basename is used by default. |
+
+### Example Usage
+
+```javascript
+it("upload assets", () => {
+  // Single file upload.
+  cy.task("sauce:uploadAssets", {
+    spec: __filename,
+    assets: { path: "pics/this-is-fine.png" },
+  });
+
+  // Multiple files upload.
+  cy.task("sauce:uploadAssets", {
+    spec: __filename,
+    assets: [
+      { path: "pics/this-is-fine.png" },
+      { path: "test.txt", filename: "test.log" },
+    ],
+  });
+});
+```
+
 ## Real-life Example
 
 [tests/integration/](https://github.com/saucelabs/sauce-cypress-plugin/tree/main/tests/integration/) folder will present an integration example with [Cypress' Kitchensink](https://github.com/cypress-io/cypress-example-kitchensink/tree/master/cypress/e2e/2-advanced-examples) tests set.

eslint.config.mjs

@@ -34,6 +34,7 @@ export default ts.config(
     languageOptions: {
       globals: {
         __dirname: true,
+        __filename: true,
         console: true,
         exports: true,
         module: true,

src/index.ts

@@ -1,6 +1,9 @@
 import Reporter from "./reporter";
 import Table from "cli-table3";
 import chalk from "chalk";
+import path from "node:path";
+import fs from "node:fs";
+import { Asset } from "@saucelabs/testcomposer";
 import BeforeRunDetails = Cypress.BeforeRunDetails;
 import PluginConfigOptions = Cypress.PluginConfigOptions;
 import PluginEvents = Cypress.PluginEvents;
@@ -20,6 +23,9 @@ export interface Options {
 let reporterInstance: Reporter;
 const reportedSpecs: { name: string; jobURL: string }[] = [];
 
+// Maps spec names to their associated assets, cached for later upload.
+let specToAssets: Map<string, Asset[]>;
+
 const isAccountSet = function () {
   return process.env.SAUCE_USERNAME && process.env.SAUCE_ACCESS_KEY;
 };
@@ -40,7 +46,7 @@ const onAfterSpec = async function (
   }
 
   try {
-    const job = await reporterInstance.reportSpec(results);
+    const job = await reporterInstance.reportSpec(results, specToAssets);
     if (!job?.id || !job?.url) {
       return;
     }
@@ -136,13 +142,59 @@ export async function afterRunTestReport(
   return reportJSON;
 }
 
+/**
+ * Temporarily caches assets for the current spec test job.
+ * Assets collected by this function are stored and later uploaded in `onAfterSpec`.
+ **/
+const cacheAssets = ({
+  spec,
+  ...assets
+}: {
+  spec: string;
+  assets: Asset[];
+}): null => {
+  if (!spec) {
+    throw new Error("'spec' is required.");
+  }
+  const assetsArray = Object.values(assets).flat();
+  if (assetsArray.length === 0) {
+    throw new Error("'assets' is required.");
+  }
+  assetsArray.forEach((asset: Asset) => {
+    if (!asset.path) {
+      throw new Error("'path' is required.");
+    }
+    const resolvedPath = path.resolve(asset.path);
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`File not found at path '${resolvedPath}'.`);
+    }
+    asset.data = fs.createReadStream(resolvedPath);
+    if (!asset.filename) {
+      asset.filename = path.basename(asset.path);
+    }
+  });
+
+  // The spec name in the Cypress report uses the basename of the spec file.
+  // To ensure matching during upload, convert it to the basename here as well.
+  const specName = path.basename(spec);
+  const currAssets = specToAssets.get(specName) || [];
+  currAssets.push(...assetsArray);
+  specToAssets.set(specName, currAssets);
+
+  return null; // Cypress task requirement.
+};
+
 export default function (
   on: PluginEvents,
   config: PluginConfigOptions,
   opts?: Options,
 ) {
   reporterInstance = new Reporter(undefined, opts);
+  specToAssets = new Map();
 
+  on("task", {
+    "sauce:uploadAssets": cacheAssets,
+  });
   on("before:run", onBeforeRun);
   on("after:run", onAfterRun);
   on("after:spec", onAfterSpec);

src/reporter.ts

@@ -120,7 +120,7 @@ export default class Reporter {
   }
 
   // Reports a spec as a Job on Sauce.
-  async reportSpec(result: RunResult) {
+  async reportSpec(result: RunResult, specToAssets: Map<string, Asset[]>) {
     if (!this.testComposer) {
       return;
     }
@@ -147,6 +147,7 @@ export default class Reporter {
 
     const report = await this.createSauceTestReport([result]);
     const assets = await this.collectAssets([result], report);
+    assets.push(...(specToAssets.get(result.spec.name) || []));
     await this.uploadAssets(job.id, assets);
 
     return job;

tests/integration/cypress/e2e/1-getting-started/todo.cy.js

@@ -34,4 +34,21 @@ describe("example to-do app", () => {
     cy.get(".todo-list li").first().should("have.text", "Pay electric bill");
     cy.get(".todo-list li").last().should("have.text", "Walk the dog");
   });
+
+  it("uploads assets", () => {
+    // Single file upload.
+    cy.task("sauce:uploadAssets", {
+      spec: __filename,
+      assets: { filename: "test1.log", path: "test.txt" },
+    });
+
+    // Multiple files upload.
+    cy.task("sauce:uploadAssets", {
+      spec: __filename,
+      assets: [
+        { filename: "test2.log", path: "test.txt" },
+        { path: "test.txt" },
+      ],
+    });
+  });
 });

tests/integration/test.txt

@@ -0,0 +1 @@
+This is the log file, which will be uploaded during the Cypress task test.