Add attach(), similar to that from cucumber-js

Author: badeball

docs/json-report.md

@@ -10,8 +10,66 @@ JSON reports can be enabled using the `json.enabled` property. The preprocessor
 }
 ```
 
-This **requires** you to have downloaded and installed the [cucumber-json-formatter](https://github.com/cucumber/common/tree/main/json-formatter) **yourself**. Arch Linux users can install it from [AUR](https://aur.archlinux.org/packages/cucumber-json-formatter).
+This **requires** you to have registered this module in your [plugin file](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Plugins-file), as shown below.
+
+```ts
+import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
+
+export default (
+  on: Cypress.PluginEvents,
+  config: Cypress.PluginConfigOptions
+): Cypress.PluginConfigOptions => {
+  await addCucumberPreprocessorPlugin(on, config);
+
+  // Make sure to return the config object as it might have been modified by the plugin.
+  return config;
+}
+```
+
+This also **requires** you to have downloaded and installed the [cucumber-json-formatter](https://github.com/cucumber/common/tree/main/json-formatter) **yourself**. Arch Linux users can install it from [AUR](https://aur.archlinux.org/packages/cucumber-json-formatter).
 
 The location of the executable is configurable through the `json.formatter` property, but it will by default search for `cucumber-json-formatter` in your `PATH`.
 
 The report is outputted to `cucumber-report.json` in the project directory, but can be configured through the `json.output` property.
+
+## Attachments
+
+Text, images and other data can be added to the output of the messages and JSON reports with attachments.
+
+```ts
+import { Given, attach } from "@badeball/cypress-cucumber-preprocessor";
+
+Given("a step", function() {
+  attach("foobar");
+});
+```
+
+By default, text is saved with a MIME type of text/plain. You can also specify a different MIME type.
+
+```ts
+import { Given, attach } from "@badeball/cypress-cucumber-preprocessor";
+
+Given("a step", function() {
+  attach('{ "name": "foobar" }', "application/json");
+});
+```
+
+Images and other binary data can be attached using a ArrayBuffer. The data will be base64 encoded in the output.
+
+```ts
+import { Given, attach } from "@badeball/cypress-cucumber-preprocessor";
+
+Given("a step", function() {
+  attach(new TextEncoder().encode("foobar").buffer, "text/plain");
+});
+```
+
+If you've already got a base64-encoded string, you can prefix your mime type with `base64:` to indicate this.
+
+```ts
+import { Given, attach } from "@badeball/cypress-cucumber-preprocessor";
+
+Given("a step", function() {
+  attach("Zm9vYmFy", "base64:text/plain");
+});
+```

features/attachments.feature

@@ -0,0 +1,67 @@
+Feature: attachments
+
+  Background:
+    Given additional preprocessor configuration
+      """
+      {
+        "json": {
+          "enabled": true
+        }
+      }
+      """
+    And I've ensured cucumber-json-formatter is installed
+
+  Scenario: string identity
+    Given a file named "cypress/integration/a.feature" with:
+      """
+      Feature: a feature
+        Scenario: a scenario
+          Given a step
+      """
+    And a file named "cypress/support/step_definitions/steps.js" with:
+      """
+      const { Given, attach } = require("@badeball/cypress-cucumber-preprocessor");
+      Given("a step", function() {
+        attach("foobar")
+      })
+      """
+    When I run cypress
+    Then it passes
+    And there should be a JSON output similar to "fixtures/attachments/string.json"
+
+  Scenario: array buffer
+    Given a file named "cypress/integration/a.feature" with:
+      """
+      Feature: a feature
+        Scenario: a scenario
+          Given a step
+      """
+    And a file named "cypress/support/step_definitions/steps.js" with:
+      """
+      const { Given, attach } = require("@badeball/cypress-cucumber-preprocessor");
+      Given("a step", function() {
+        attach(new TextEncoder().encode("foobar").buffer, "text/plain")
+      })
+      """
+    When I run cypress
+    Then it passes
+    And there should be a JSON output similar to "fixtures/attachments/string.json"
+
+  Scenario: string encoded
+    Given a file named "cypress/integration/a.feature" with:
+      """
+      Feature: a feature
+        Scenario: a scenario
+          Given a step
+      """
+    And a file named "cypress/support/step_definitions/steps.js" with:
+      """
+      const { fromByteArray } = require("base64-js");
+      const { Given, attach } = require("@badeball/cypress-cucumber-preprocessor");
+      Given("a step", function() {
+        attach(fromByteArray(new TextEncoder().encode("foobar")), "base64:text/plain")
+      })
+      """
+    When I run cypress
+    Then it passes
+    And there should be a JSON output similar to "fixtures/attachments/string.json"

features/fixtures/screenshot.json renamed to features/fixtures/attachments/screenshot.json

@@ -0,0 +1,39 @@
+[
+  {
+    "description": "",
+    "elements": [
+      {
+        "description": "",
+        "id": "a-feature;a-scenario",
+        "keyword": "Scenario",
+        "line": 2,
+        "name": "a scenario",
+        "steps": [
+          {
+            "keyword": "Given ",
+            "line": 3,
+            "name": "a step",
+            "result": {
+              "status": "passed"
+            },
+            "match": {
+              "location": "not available:0"
+            },
+            "embeddings": [
+              {
+                "data": "Zm9vYmFy",
+                "mime_type": "text/plain"
+              }
+            ]
+          }
+        ],
+        "type": "scenario"
+      }
+    ],
+    "id": "a-feature",
+    "keyword": "Feature",
+    "line": 1,
+    "name": "a feature",
+    "uri": "cypress/integration/a.feature"
+  }
+]

features/fixtures/attachments/string.json

@@ -177,4 +177,4 @@ Feature: JSON formatter
       """
     When I run cypress
     Then it passes
-    And there should be a JSON output similar to "fixtures/screenshot.json"
+    And there should be a JSON output similar to "fixtures/attachments/screenshot.json"

features/json_report.feature

@@ -87,7 +87,7 @@ Then(
     if (process.env.WRITE_FIXTURES) {
       await fs.writeFile(
         absoluteExpectedJsonpath,
-        JSON.stringify(actualJsonOutput, null, 2)
+        JSON.stringify(actualJsonOutput, null, 2) + "\n"
       );
     } else {
       const expectedJsonOutput = JSON.parse(

features/step_definitions/json_steps.ts

@@ -17,7 +17,11 @@ import {
   ICypressConfiguration,
 } from "@badeball/cypress-configuration";
 
-import { TASK_APPEND_MESSAGES, TASK_TEST_STEP_STARTED } from "./constants";
+import {
+  TASK_APPEND_MESSAGES,
+  TASK_CREATE_STRING_ATTACHMENT,
+  TASK_TEST_STEP_STARTED,
+} from "./constants";
 
 import { resolve } from "./preprocessor-configuration";
 
@@ -125,6 +129,23 @@ export default async function addCucumberPreprocessorPlugin(
       currentTestStepStartedId = testStepStartedId;
       return true;
     },
+
+    [TASK_CREATE_STRING_ATTACHMENT]: async ({ data, mediaType, encoding }) => {
+      const message: messages.IEnvelope = {
+        attachment: {
+          testStepId: currentTestStepStartedId,
+          body: data,
+          mediaType: mediaType,
+          contentEncoding: encoding,
+        },
+      };
+
+      await fs.writeFile(messagesPath, JSON.stringify(message) + "\n", {
+        flag: "a",
+      });
+
+      return true;
+    },
   });
 
   const tags = getTags(config.env);

lib/add-cucumber-preprocessor-plugin.ts

@@ -3,3 +3,6 @@ export const TASK_APPEND_MESSAGES =
 
 export const TASK_TEST_STEP_STARTED =
   "cypress-cucumber-preprocessor:test-step-started";
+
+export const TASK_CREATE_STRING_ATTACHMENT =
+  "cypress-cucumber-preprocessor:create-string-attachment";

lib/constants.ts

@@ -46,6 +46,7 @@ export const defineParameterType = createUnimplementation(
   Methods.defineParameterType
 );
 export const Step = createUnimplementation(Methods.Step);
+export const attach = createUnimplementation(Methods.attach);
 
 export function defineBefore(options: { tags?: string }, fn: IHookBody): void;
 export function defineBefore(fn: IHookBody): void;

lib/index.ts

@@ -1,4 +1,9 @@
+import { fromByteArray } from "base64-js";
+
+import { TASK_CREATE_STRING_ATTACHMENT } from "./constants";
+
 import DataTable from "./data_table";
+
 import { getRegistry } from "./registry";
 
 import {
@@ -56,6 +61,42 @@ function defineAfter(
   }
 }
 
+function createStringAttachment(
+  data: string,
+  mediaType: string,
+  encoding: "BASE64" | "IDENTITY"
+) {
+  cy.task(TASK_CREATE_STRING_ATTACHMENT, {
+    data,
+    mediaType,
+    encoding,
+  });
+}
+
+export function attach(data: string | ArrayBuffer, mediaType?: string) {
+  if (typeof data === "string") {
+    mediaType = mediaType ?? "text/plain";
+
+    if (mediaType.startsWith("base64:")) {
+      createStringAttachment(data, mediaType.replace("base64:", ""), "BASE64");
+    } else {
+      createStringAttachment(data, mediaType ?? "text/plain", "IDENTITY");
+    }
+  } else if (data instanceof ArrayBuffer) {
+    if (typeof mediaType !== "string") {
+      throw Error("ArrayBuffer attachments must specify a media type");
+    }
+
+    createStringAttachment(
+      fromByteArray(new Uint8Array(data)),
+      mediaType,
+      "BASE64"
+    );
+  } else {
+    throw Error("Invalid attachment data: must be a ArrayBuffer or string");
+  }
+}
+
 export {
   defineStep as Given,
   defineStep as When,