testcafe-reporter-qase 2.0.3 → 2.0.4

package/README.md

@@ -20,15 +20,28 @@ To update a test project using testcafe-reporter-qaser@v1 to version 2:
 The TestCafe reporter has the ability to auto-generate test cases
 and suites from your test data.
 
-But if necessary, you can independently register the ID of already
-existing test cases from TMS before the executing tests. Meta key should be `CID`.
-You should assign list of case IDs to it, e.g.:
+You can also annotate the tests with the IDs of existing test cases
+from Qase.io before executing tests. It's a more reliable way to bind
+autotests to test cases, that persists when you rename, move, or
+parameterize your tests.
 
-```js
-test.meta('CID', [1])('Text typing basics', async (t) => {
-  await t;
-});
+### Metadata
+
+- `qase.title` - set the title of the test case
+- `qase.fields` - set the fields of the test case
+- `qase.suite` - set the suite of the test case
+- `qase.comment` - set the comment of the test case
+- `qase.parameters` - set the parameters of the test case
+- `qase.groupParameters` - set the group parameters of the test case
+- `qase.ignore` - ignore the test case in Qase. The test will be executed, but the results will not be sent to Qase.
+- `qase.step` - create a step in the test case
+- `qase.attach` - attach a file or content to the test case
+
+For detailed instructions on using annotations and methods, refer to [Usage](docs/usage.md).
 
+For example:
+
+```js
 const q = qase.id(1)
   .title('Text typing basics')
   .field({ 'severity': 'high' })
@@ -98,16 +111,8 @@ Example `qase.config.json` file:
 }
 ```
 
-Supported ENV variables:
-
-- `QASE_MODE` - Same as `mode`
-- `QASE_DEBUG` - Same as `debug`
-- `QASE_ENVIRONMENT` - Same as `environment`
-- `QASE_TESTOPS_API_TOKEN` - Same as `testops.api.token`
-- `QASE_TESTOPS_PROJECT` - Same as `testops.project`
-- `QASE_TESTOPS_RUN_ID` - Pass Run ID from ENV and override reporter option `testops.run.id`
-- `QASE_TESTOPS_RUN_TITLE` - Same as `testops.run.title`
-- `QASE_TESTOPS_RUN_DESCRIPTION` - Same as `testops.run.description`
+Check out the example of configuration for multiple reporters in the
+[demo project](../examples/testcafe/qase.config.json).
 
 ## Requirements
 

package/changelog.md

@@ -1,3 +1,28 @@
+# qase-testcafe@2.0.4
+
+## What's new
+
+Support `step` and `attach` methods for test cases. 
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+test('test', async (t) => {
+  qase.attach({ name: 'attachment.txt', content: 'Hello, world!', contentType: 'text/plain' });
+  
+  await qase.step('Step 1', async (s1) => {
+    await s1.step('Step 1.1', async (s11) => {
+      await s11.step('Step 1.1.1', async (s111) => {
+        s11.attach({ name: 'attachment.txt', content: 'Hello, world!', contentType: 'text/plain' });
+        await s111.expect(true).ok();
+      });
+    });
+    await t.expect(true).ok();
+  });
+  await t.expect(true).ok();
+});
+```
+
 # qase-testcafe@2.0.3
 
 ## What's new

package/dist/factory.d.ts

@@ -7,6 +7,7 @@ export declare const factory: (options: TestcafeQaseOptionsType) => {
     noColors: boolean;
     reportTaskStart: () => void;
     reportFixtureStart: () => void;
+    reportTestStart: () => void;
     reportTestDone(name: string, testRunInfo: TestRunInfoType, meta: Record<string, string>): Promise<void>;
     reportTaskDone: () => Promise<void>;
 };

package/dist/factory.js

@@ -16,6 +16,9 @@ const factory = (options) => {
         reportFixtureStart: () => {
             /* empty */
         },
+        reportTestStart: () => {
+            reporter.reportTestStart();
+        },
         async reportTestDone(name, testRunInfo, meta) {
             return reporter.reportTestDone(name, testRunInfo, meta, 
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment

package/dist/global.d.ts

@@ -0,0 +1,16 @@
+import { TestcafeQaseReporter } from './reporter';
+import { Attachment, TestStepType } from 'qase-javascript-commons';
+declare global {
+    namespace NodeJS {
+        interface Global {
+            Qase: Qase;
+        }
+    }
+}
+export declare class Qase {
+    private reporter;
+    constructor(reporter: TestcafeQaseReporter);
+    step(step: TestStepType): void;
+    attachment(attachment: Attachment): void;
+}
+export {};

package/dist/global.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Qase = void 0;
+class Qase {
+    constructor(reporter) {
+        this.reporter = reporter;
+    }
+    step(step) {
+        this.reporter.addStep(step);
+    }
+    attachment(attachment) {
+        this.reporter.addAttachment(attachment);
+    }
+}
+exports.Qase = Qase;

package/dist/qase.d.ts

@@ -1,3 +1,4 @@
+import { StepFunction } from 'qase-javascript-commons';
 export declare class qase {
     private static _qaseID;
     private static _qaseTitle;
@@ -70,6 +71,35 @@ export declare class qase {
      * test.meta({userField: 123, ...q})('Test case title', async t => { ... });
      */
     static ignore: () => typeof qase;
+    /**
+     * Add a step to the test case
+     * @param name
+     * @param body
+     * @example
+     * test.meta({userField: 123, ...q})('Test case title', async t => {
+     *    await qase.step("Step", () => {
+     *      expect(true).toBe(true);
+     *    });
+     *     expect(true).toBe(true);
+     * });
+     */
+    static step: (name: string, body: StepFunction) => Promise<void>;
+    /**
+     * Add an attachment to the test case
+     * @param attach
+     * @example
+     * test.meta({userField: 123, ...q})('Test case title', async t => {
+     *   qase.attach({ name: 'attachment.txt', content: 'Hello, world!', type: 'text/plain' });
+     *   qase.attach({ paths: ['/path/to/file', '/path/to/another/file']});
+     *     expect(true).toBe(true);
+     * });
+     */
+    static attach: (attach: {
+        name?: string;
+        type?: string;
+        content?: string;
+        paths?: string[];
+    }) => void;
     /**
      * Create a Qase metadata
      * Call this method after setting all the necessary parameters

package/dist/qase.js

@@ -1,8 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.qase = void 0;
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+const path_1 = __importDefault(require("path"));
+const qase_javascript_commons_1 = require("qase-javascript-commons");
+const uuid_1 = require("uuid");
 class qase {
 }
 exports.qase = qase;
@@ -96,6 +102,60 @@ qase.ignore = () => {
     _a._qaseIgnore = 'true';
     return _a;
 };
+/**
+ * Add a step to the test case
+ * @param name
+ * @param body
+ * @example
+ * test.meta({userField: 123, ...q})('Test case title', async t => {
+ *    await qase.step("Step", () => {
+ *      expect(true).toBe(true);
+ *    });
+ *     expect(true).toBe(true);
+ * });
+ */
+qase.step = async (name, body) => {
+    const runningStep = new qase_javascript_commons_1.QaseStep(name);
+    // eslint-disable-next-line @typescript-eslint/require-await
+    await runningStep.run(body, async (step) => global.Qase.step(step));
+};
+/**
+ * Add an attachment to the test case
+ * @param attach
+ * @example
+ * test.meta({userField: 123, ...q})('Test case title', async t => {
+ *   qase.attach({ name: 'attachment.txt', content: 'Hello, world!', type: 'text/plain' });
+ *   qase.attach({ paths: ['/path/to/file', '/path/to/another/file']});
+ *     expect(true).toBe(true);
+ * });
+ */
+qase.attach = (attach) => {
+    if (attach.paths) {
+        for (const file of attach.paths) {
+            const attachmentName = path_1.default.basename(file);
+            const contentType = (0, qase_javascript_commons_1.getMimeTypes)(file);
+            global.Qase.attachment({
+                file_path: file,
+                size: 0,
+                id: (0, uuid_1.v4)(),
+                file_name: attachmentName,
+                mime_type: contentType,
+                content: '',
+            });
+        }
+        return;
+    }
+    if (attach.content) {
+        global.Qase.attachment({
+            file_path: null,
+            size: attach.content.length,
+            id: (0, uuid_1.v4)(),
+            file_name: attach.name ?? 'attachment',
+            mime_type: attach.type ?? 'application/octet-stream',
+            content: attach.content,
+        });
+    }
+};
 /**
  * Create a Qase metadata
  * Call this method after setting all the necessary parameters

package/dist/reporter.d.ts

@@ -1,4 +1,4 @@
-import { ConfigLoader, ConfigType } from 'qase-javascript-commons';
+import { ConfigLoader, ConfigType, Attachment, TestStepType } from 'qase-javascript-commons';
 interface CallsiteRecordType {
     filename?: string;
     lineNum?: number;
@@ -65,15 +65,20 @@ export declare class TestcafeQaseReporter {
      * @private
      */
     private reporter;
+    private steps;
+    private attachments;
     /**
      * @param {TestcafeQaseOptionsType} options
      * @param {ConfigLoaderInterface} configLoader
      */
     constructor(options: TestcafeQaseOptionsType, configLoader?: ConfigLoader<Partial<ConfigType> & Record<string, unknown>>);
+    addStep(step: TestStepType): void;
+    addAttachment(attachment: Attachment): void;
     /**
      * @returns {Promise<void>}
      */
     startTestRun: () => void;
+    reportTestStart: () => void;
     /**
      * @param {string} title
      * @param {TestRunInfoType} testRunInfo

package/dist/reporter.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TestcafeQaseReporter = void 0;
 const uuid_1 = require("uuid");
 const qase_javascript_commons_1 = require("qase-javascript-commons");
+const global_1 = require("./global");
 var metadataEnum;
 (function (metadataEnum) {
     metadataEnum["id"] = "QaseID";
@@ -55,12 +56,18 @@ class TestcafeQaseReporter {
      * @param {ConfigLoaderInterface} configLoader
      */
     constructor(options, configLoader = new qase_javascript_commons_1.ConfigLoader()) {
+        this.steps = [];
+        this.attachments = [];
         /**
          * @returns {Promise<void>}
          */
         this.startTestRun = () => {
             this.reporter.startTestRun();
         };
+        this.reportTestStart = () => {
+            this.steps = [];
+            this.attachments = [];
+        };
         /**
          * @param {string} title
          * @param {TestRunInfoType} testRunInfo
@@ -77,6 +84,8 @@ class TestcafeQaseReporter {
             // eslint-disable-next-line no-control-regex
             /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, ''))
                 .join('\n');
+            const attachments = TestcafeQaseReporter.transformAttachments(testRunInfo.screenshots);
+            attachments.push(...this.attachments);
             await this.reporter.addTestResult({
                 author: null,
                 execution: {
@@ -104,11 +113,11 @@ class TestcafeQaseReporter {
                 },
                 run_id: null,
                 signature: this.getSignature(testRunInfo.fixture, title, metadata[metadataEnum.id], metadata[metadataEnum.parameters]),
-                steps: [],
+                steps: this.steps,
                 id: (0, uuid_1.v4)(),
                 testops_id: metadata[metadataEnum.id].length > 0 ? metadata[metadataEnum.id] : null,
                 title: metadata[metadataEnum.title] != undefined ? metadata[metadataEnum.title] : title,
-                attachments: TestcafeQaseReporter.transformAttachments(testRunInfo.screenshots),
+                attachments: attachments,
             });
         };
         /**
@@ -124,6 +133,13 @@ class TestcafeQaseReporter {
             frameworkName: 'testcafe',
             reporterName: 'testcafe-reporter-qase',
         });
+        global.Qase = new global_1.Qase(this);
+    }
+    addStep(step) {
+        this.steps.push(step);
+    }
+    addAttachment(attachment) {
+        this.attachments.push(attachment);
     }
     getMeta(meta) {
         const metadata = {

package/docs/usage.md

@@ -0,0 +1,163 @@
+# Qase Integration in TestCafe
+
+This guide demonstrates how to integrate Qase with TestCafe, providing instructions on how to add Qase IDs, titles,
+fields, suites, comments, and file attachments to your test cases.
+
+---
+
+## Adding QaseID to a Test
+
+To associate a QaseID with a test in TestCafe, use the `qase` function. This function accepts a single integer
+representing the test's ID in Qase.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+const q = qase.id(1).create();
+test.meta(q)('simple test', async (t) => {
+  await t.expect(true).ok();
+});
+```
+
+---
+
+## Adding a Title to a Test
+
+You can provide a title for your test using the `qase.title` function. The function accepts a string, which will be
+used as the test's title in Qase. If no title is provided, the test method name will be used by default.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+const q = qase.title('Some title').create();
+test.meta(q)('simple test', async (t) => {
+  await t.expect(true).ok();
+});
+```
+
+---
+
+## Adding Fields to a Test
+
+The `qase.fields` function allows you to add additional metadata to a test case. You can specify multiple fields to
+enhance test case information in Qase.
+
+### System Fields:
+
+- `description` — Description of the test case.
+- `preconditions` — Preconditions for the test case.
+- `postconditions` — Postconditions for the test case.
+- `severity` — Severity of the test case (e.g., `critical`, `major`).
+- `priority` — Priority of the test case (e.g., `high`, `low`).
+- `layer` — Test layer (e.g., `UI`, `API`).
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+const q = qase.fields({ 'severity': 'high', 'priority': 'medium' }).create();
+test.meta(q)('simple test', async (t) => {
+  await t.expect(true).ok();
+});
+```
+
+---
+
+## Ignoring a Test in Qase
+
+To exclude a test from being reported to Qase (while still executing the test in TestCafe), use the `qase.ignore`
+function. The test will run, but its result will not be sent to Qase.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+const q = qase.ignore().create();
+test.meta(q)('simple test', async (t) => {
+  await t.expect(true).ok();
+});
+```
+
+---
+
+## Attaching Files to a Test
+
+To attach files to a test result, use the `qase.attach` function. This method supports attaching one or multiple files,
+along with optional file names, comments, and file types.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+test('test', async (t) => {
+  qase.attach({ name: 'attachment.txt', content: 'Hello, world!', contentType: 'text/plain' });
+  qase.attach({ paths: '/path/to/file' });
+  qase.attach({ paths: ['/path/to/file', '/path/to/another/file'] });
+  await t.expect(true).ok();
+});
+```
+
+---
+
+## Adding Parameters to a Test
+
+You can add parameters to a test case using the `qase.parameters` function. This function accepts an object with
+parameter names and values.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+const q = qase.parameters({ param1: 'value1', param2: 'value2' }).create();
+test.meta(q)('simple test', async (t) => {
+  await t.expect(true).ok();
+});
+```
+
+## Adding Group Parameters to a Test
+
+To add group parameters to a test case, use the `qase.groupParameters` function. This function accepts an list with
+group parameter names.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+const q = qase.parameters({ param1: 'value1', param2: 'value2' }).groupParameters(['param1']).create();
+test.meta(q)('simple test', async (t) => {
+  await t.expect(true).ok();
+});
+```
+
+## Adding Steps to a Test
+
+You can add steps to a test case using the `qase.step` function. This function accepts a string, which will be used as
+the step description in Qase.
+
+### Example:
+
+```javascript
+import { qase } from 'testcafe-qase-reporter/qase';
+
+test('test', async (t) => {
+  await qase.step('Step 1', async (s1) => {
+    await s1.step('Step 1.1', async (s11) => {
+      await s11.step('Step 1.1.1', async (s111) => {
+        s11.attach({ name: 'attachment.txt', content: 'Hello, world!', contentType: 'text/plain' });
+        await s111.expect(true).ok();
+      });
+    });
+    await t.expect(true).ok();
+  });
+  await t.expect(true).ok();
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testcafe-reporter-qase",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Qase TMS TestCafe Reporter",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -40,7 +40,7 @@
   "author": "Qase Team <support@qase.io>",
   "license": "Apache-2.0",
   "dependencies": {
-    "qase-javascript-commons": "~2.2.0",
+    "qase-javascript-commons": "~2.2.4",
     "uuid": "^9.0.0"
   },
   "peerDependencies": {