testcafe-reporter-qase 2.0.2 → 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,45 @@
+# 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
+
+Support `ignore` metadata for test cases. If the test case has the `ignore` tag, the reporter will not send the result to the Qase
+TMS.
+
+```ts
+const q = qase.ignore().create();
+test.meta({ ...q })(
+  'test',
+  async (t) => {
+    await t;
+  },
+);
+```
+
 # qase-testcafe@2.0.2
 
 ## What's new
@@ -8,7 +50,8 @@ Improved error collection. The error stack trace contains more useful debugging
 
 ## What's new
 
-Support group parameters for test cases. You can specify the group parameters in the test case using the following format:
+Support group parameters for test cases. You can specify the group parameters in the test case using the following
+format:
 
 ```ts
 const q = qase.groupParameters({ 'param01': 'value01', 'param02': 'value02' }).create();

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,9 +1,11 @@
+import { StepFunction } from 'qase-javascript-commons';
 export declare class qase {
     private static _qaseID;
     private static _qaseTitle;
     private static _qaseFields;
     private static _qaseParameters;
     private static _qaseGroupParameters;
+    private static _qaseIgnore;
     /**
      * Set a Qase ID for the test case
      * Don't forget to call `create` method after setting all the necessary parameters
@@ -53,12 +55,51 @@ export declare class qase {
      * Don't forget to call `create` method after setting all the necessary parameters
      * @param {Record<string, string>} values
      * @example
-     * const q = qase.group_parameters({ 'severity': 'high', 'priority': 'medium' }).create();
+     * const q = qase.groupParameters({ 'severity': 'high', 'priority': 'medium' }).create();
      * test.meta(q)('Test case title', async t => { ... });
      * or
      * test.meta({userField: 123, ...q})('Test case title', async t => { ... });
      */
-    static group_parameters: (values: Record<string, string>) => typeof qase;
+    static groupParameters: (values: Record<string, string>) => typeof qase;
+    /**
+     * Set a ignore flag for the test case
+     * Don't forget to call `create` method after setting all the necessary parameters
+     * @example
+     * const q = qase.ignore().create();
+     * test.meta(q)('Test case title', async t => { ... });
+     * or
+     * 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
@@ -74,6 +115,7 @@ export declare class qase {
         QaseFields: string;
         QaseParameters: string;
         QaseGroupParameters: string;
+        QaseIgnore: string;
     };
     private static toNormalizeRecord;
 }

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;
@@ -12,6 +18,7 @@ qase._qaseTitle = '';
 qase._qaseFields = '';
 qase._qaseParameters = '';
 qase._qaseGroupParameters = '';
+qase._qaseIgnore = '';
 /**
  * Set a Qase ID for the test case
  * Don't forget to call `create` method after setting all the necessary parameters
@@ -73,15 +80,82 @@ qase.parameters = (values) => {
  * Don't forget to call `create` method after setting all the necessary parameters
  * @param {Record<string, string>} values
  * @example
- * const q = qase.group_parameters({ 'severity': 'high', 'priority': 'medium' }).create();
+ * const q = qase.groupParameters({ 'severity': 'high', 'priority': 'medium' }).create();
  * test.meta(q)('Test case title', async t => { ... });
  * or
  * test.meta({userField: 123, ...q})('Test case title', async t => { ... });
  */
-qase.group_parameters = (values) => {
+qase.groupParameters = (values) => {
     _a._qaseGroupParameters = _a.toNormalizeRecord(values);
     return _a;
 };
+/**
+ * Set a ignore flag for the test case
+ * Don't forget to call `create` method after setting all the necessary parameters
+ * @example
+ * const q = qase.ignore().create();
+ * test.meta(q)('Test case title', async t => { ... });
+ * or
+ * test.meta({userField: 123, ...q})('Test case title', async t => { ... });
+ */
+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
@@ -98,12 +172,14 @@ qase.create = () => {
         QaseFields: _a._qaseFields,
         QaseParameters: _a._qaseParameters,
         QaseGroupParameters: _a._qaseGroupParameters,
+        QaseIgnore: _a._qaseIgnore,
     };
     _a._qaseID = '';
     _a._qaseTitle = '';
     _a._qaseFields = '';
     _a._qaseParameters = '';
     _a._qaseGroupParameters = '';
+    _a._qaseIgnore = '';
     return meta;
 };
 qase.toNormalizeRecord = (record) => {

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";
@@ -11,6 +12,7 @@ var metadataEnum;
     metadataEnum["parameters"] = "QaseParameters";
     metadataEnum["groupParameters"] = "QaseGroupParameters";
     metadataEnum["oldID"] = "CID";
+    metadataEnum["ignore"] = "QaseIgnore";
 })(metadataEnum || (metadataEnum = {}));
 /**
  * @class TestcafeQaseReporter
@@ -54,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
@@ -67,12 +75,17 @@ class TestcafeQaseReporter {
          * @param formatError
          */
         this.reportTestDone = async (title, testRunInfo, meta, formatError) => {
+            const metadata = this.getMeta(meta);
+            if (metadata[metadataEnum.ignore]) {
+                return;
+            }
             const errorLog = testRunInfo.errs
                 .map((error, index) => formatError(error, `${index + 1} `).replace(
             // 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 metadata = this.getMeta(meta);
+            const attachments = TestcafeQaseReporter.transformAttachments(testRunInfo.screenshots);
+            attachments.push(...this.attachments);
             await this.reporter.addTestResult({
                 author: null,
                 execution: {
@@ -100,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,
             });
         };
         /**
@@ -120,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 = {
@@ -128,6 +148,7 @@ class TestcafeQaseReporter {
             QaseFields: {},
             QaseParameters: {},
             QaseGroupParameters: {},
+            QaseIgnore: false,
         };
         if (meta[metadataEnum.oldID] !== undefined && meta[metadataEnum.oldID] !== '') {
             const v = meta[metadataEnum.oldID].split(',');
@@ -146,6 +167,12 @@ class TestcafeQaseReporter {
         if (meta[metadataEnum.parameters] !== undefined && meta[metadataEnum.parameters] !== '') {
             metadata.QaseParameters = JSON.parse(meta[metadataEnum.parameters]);
         }
+        if (meta[metadataEnum.groupParameters] !== undefined && meta[metadataEnum.groupParameters] !== '') {
+            metadata.QaseGroupParameters = JSON.parse(meta[metadataEnum.groupParameters]);
+        }
+        if (meta[metadataEnum.ignore] !== undefined && meta[metadataEnum.ignore] !== '') {
+            metadata.QaseIgnore = meta[metadataEnum.ignore] === 'true';
+        }
         return 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.2",
+  "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": {