testit-adapter-mocha 1.1.5

package/README.md

@@ -0,0 +1,219 @@
+# Test IT TMS adapters for Mocha
+![Test IT](https://raw.githubusercontent.com/testit-tms/adapters-js/master/images/banner.png)
+
+## Getting Started
+
+### Installation
+```
+npm install testit-adapter-mocha
+```
+
+### Adapter connection
+
+```js
+// .mocharc.js
+
+module.exports = {
+  reporter: "testit-adapter-mocha",
+  // ... other mocha options
+}
+```
+
+## Configuration
+
+| Description                                                                                                                                                | Property                   | Environment variable              |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|-----------------------------------|
+| Location of the TMS instance                                                                                                                               | url                        | TMS_URL                           |
+| API secret key <br/>[How to getting API secret key?](https://github.com/testit-tms/.github/tree/main/configuration#privatetoken)                           | privateToken               | TMS_PRIVATE_TOKEN                 |
+| ID of project in TMS instance <br/>[How to getting project ID?](https://github.com/testit-tms/.github/tree/main/configuration#projectid)                   | projectId                  | TMS_PROJECT_ID                    |
+| ID of configuration in TMS instance <br/>[How to getting configuration ID?](https://github.com/testit-tms/.github/tree/main/configuration#configurationid) | configurationId            | TMS_CONFIGURATION_ID              |
+| ID of the created test run in TMS instance.<br/>It's necessary for **adapterMode** 0 or 1                                                                  | testRunId                  | TMS_TEST_RUN_ID                   |
+| Parameter for specifying the name of test run in TMS instance (**It's optional**). <br/>If it is not provided, it is created automatically                 | testRunName                | TMS_TEST_RUN_NAME                 |
+| Adapter mode *                                                                                                                                             | adapterMode                | TMS_ADAPTER_MODE                  |
+| Mode of automatic creation test cases ** (**It's optional**).                                                                                              | automaticCreationTestCases | TMS_AUTOMATIC_CREATION_TEST_CASES |
+
+*The adapter supports following modes:
+* 0 - in this mode, the adapter filters tests by external id and sends the results to the test run. **Default value**.
+* 1 - in this mode, the adapter sends all results to the test run without filtering
+* 2 - in this mode, the adapter creates a new test run and sends results to the new test run
+
+**The adapter supports following modes:
+* true - in this mode, the adapter will create a test case linked to the created autotest (not to the updated autotest)
+* false - in this mode, the adapter will not create a test case. **Default value**.
+
+### File
+
+1. Adapter configuration file: `tms.config.json`
+
+```json
+{
+  "url": "URL",
+  "privateToken": "USER_PRIVATE_TOKEN",
+  "projectId": "PROJECT_ID",
+  "configurationId": "CONFIGURATION_ID",
+  "testRunId": "TEST_RUN_ID",
+  "adapterMode": 0,
+  "automaticCreationTestCases": false
+}
+```
+
+2. You can set adapter config in mocha config file: `.mocharc.js`.
+
+```js
+module.exports = {
+  reporter: "testit-adapter-mocha",
+  tmsOptions: {
+    url: 'URL',
+    privateToken: 'USER_PRIVATE_TOKEN',
+    projectId: 'PROJECT_ID',
+    configurationId: 'CONFIGURATION_ID',
+    testRunId: 'TEST_RUN_ID',
+    adapterMode: ADAPTER_MODE,
+    automaticCreationTestCases: AUTOMATIC_CREATION_TEST_CASES
+  },
+  // ... other mocha options
+};
+```
+
+3. You can set adapter config to environment variables: `.env`.
+
+```dotenv
+TMS_PRIVATE_TOKEN=YourPrivateToken
+TMS_URL=URL
+TMS_PROJECT_ID=YourProjectId;
+TMS_CONFIGURATION_ID=YourConfigurationId;
+TMS_TEST_RUN_ID=TestRunId;
+TMS_TEST_RUN_NAME=TestRunName; # optional
+TMS_ADAPTER_MODE=0; # or 1, or 2
+TMS_CONFIG_FILE=pathToAnotherConfigFile; #optional
+TMS_AUTOMATIC_CREATION_TEST_CASES=false; # or true, optional
+```
+
+## Usage
+
+Methods and properties can be used to specify information about autotest.
+
+### Properties
+
+Description of metadata properties:
+- `this.workItemsIds` - linking an autotest to a test case
+- `this.displayName` - name of the autotest in the Test IT system
+- `this.externalId` - External ID of the autotest within the project in the Test IT system
+- `this.title` - title in the autotest card
+- `this.description` - description in the autotest card
+- `this.labels` - labels in the autotest card
+- `this.links` - links in the autotest card
+- `this.nameSpace` - directory in the TMS system (default - directory's name of test)
+- `this.className` - subdirectory in the TMS system (default - file's name of test)
+
+### Methods
+
+Description of methods:
+- `this.addLinks` - links in the autotest result
+- `this.addAttachments` - uploading files in the autotest result or step result
+- `this.addMessage` - information about autotest in the autotest result
+- `this.addSteps` - information about step in the autotest result
+
+## Examples
+
+### Simple test
+
+```ts
+// annotations.spec.ts
+
+import assert from "assert";
+import {Context, Link} from "testit-adapter-mocha";
+
+const links: Link[] = [
+  { url: "https://test01.example", title: "Example01", description: "Example01 description", type: "Issue" },
+  { url: "https://test02.example", title: "Example02", description: "Example02 description", type: "BlockedBy" },
+  { url: "https://test03.example", title: "Example03", description: "Example03 description", type: "Requirement" },
+  { url: "https://test04.example", title: "Example04", description: "Example04 description", type: "Defect" },
+  { url: "https://test05.example", title: "Example05", description: "Example05 description", type: "Repository" },
+];
+
+const paths = [
+  join(__dirname, "../attachments/file.txt"),
+  join(__dirname, "../attachments/image.jpg")
+];
+
+it('All annotations and methods', function (this: Context) {
+  this.externalId = 'external_id';
+  this.displayName = 'display_name';
+  this.title = 'title';
+  this.description = 'description';
+  this.labels = ['label1', 'label2'];
+  this.links = links;
+
+  this.addMessage('This is a message');
+  this.addLinks(links);
+
+  this.addAttachments(paths);
+  this.addAttachments('This is a custom attachment', 'custom.txt');
+  this.addAttachments('Text-like attachmnet');
+  
+  this.addSteps("Step_name", (step) => {
+    // ... step logic
+    step.description = "Step Description";
+    step.parameters = {
+      login: "login",
+      password: "password",
+    };
+    this.addAttachments("Attachment_from_step", "step.txt");
+  })
+
+  assert.equal(true, true);
+});
+```
+
+### Parameterized test
+
+```ts
+// parameters.spec.ts
+
+import assert from "assert";
+import {Context} from "testit-adapter-mocha";
+
+const tests = [2, 3, "string", false];
+
+tests.forEach((value) => {
+  it(`3 is ${value}`, function (this: Context) {
+    this.parameters = {
+      value: value.toString(),
+    };
+    
+    assert.strictEqual(3, value);
+  });
+});
+
+const tests2 = [
+  { args: [1, 2], expected: 3 },
+  { args: [1, 2, 3], expected: 7 },
+  { args: [1, 2, 3, 4], expected: "10" },
+];
+
+tests2.forEach(({ args, expected }) => {
+  it(`correctly sum ${args} to ${expected}`, function (this: Context) {
+    this.parameters = {
+      args: args.toString(),
+      expected: expected.toString(),
+    };
+    
+    assert.strictEqual(sum(args), expected);
+  });
+});
+```
+
+# Contributing
+
+You can help to develop the project. Any contributions are **greatly appreciated**.
+
+* If you have suggestions for adding or removing projects, feel free to [open an issue](https://github.com/testit-tms/adapters-js/issues/new) to discuss it, or directly create a pull request after you edit the *README.md* file with necessary changes.
+* Please make sure you check your spelling and grammar.
+* Create individual PR for each suggestion.
+* Please also read through the [Code Of Conduct](https://github.com/testit-tms/adapters-js/blob/master/CODE_OF_CONDUCT.md) before posting your first idea as well.
+
+# License
+
+Distributed under the Apache-2.0 License. See [LICENSE](https://github.com/testit-tms/adapters-js/blob/master/LICENSE.md) for more information.
+

package/lib/reporter.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/reporter.js

@@ -0,0 +1,182 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mocha_1 = require("mocha");
+const testit_js_commons_1 = require("testit-js-commons");
+const step_1 = require("./step");
+const utils_1 = require("./utils");
+const Reporter = mocha_1.reporters.List;
+const Events = mocha_1.Runner.constants;
+const emptyTest = () => ({
+    autoTestExternalId: "",
+    outcome: "Passed",
+    stepResults: [],
+    setupResults: [],
+    teardownResults: [],
+    attachments: [],
+});
+const emptyStep = () => ({
+    title: "",
+    steps: [],
+    attachments: [],
+});
+module.exports = class extends Reporter {
+    constructor(runner, options) {
+        super(runner, options);
+        this.attachmentsQueue = [];
+        this.autotestsQueue = [];
+        this.autotestsForTestRun = [];
+        this.currentTest = emptyTest();
+        this.currentStep = emptyStep();
+        this.onStartRun = () => __awaiter(this, void 0, void 0, function* () {
+            this.strategy.setup();
+        });
+        this.onEndRun = () => __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all(this.attachmentsQueue).catch((err) => {
+                console.log("Error loading attachments. \n", err.body);
+            });
+            yield Promise.all(this.autotestsQueue);
+            yield this.strategy.loadTestRun(this.autotestsForTestRun).catch((err) => {
+                console.log("Error load test run. \n", err.body);
+            });
+            yield this.strategy.teardown();
+        });
+        this.addAttachments = (pathsOrContent, fileName) => {
+            const target = this.currentType === "test" ? this.currentTest : this.currentStep;
+            const promise = typeof pathsOrContent === "string"
+                ? this.additions.addAttachments(pathsOrContent, fileName)
+                : this.additions.addAttachments(pathsOrContent);
+            promise.then((attachments) => {
+                var _a;
+                (_a = target.attachments) === null || _a === void 0 ? void 0 : _a.push(...attachments);
+            });
+            this.attachmentsQueue.push(promise);
+            return promise;
+        };
+        this.addLinks = (links) => {
+            Array.isArray(links) ? this.additions.addLinks(links) : this.additions.addLinks(links);
+        };
+        this.addMessage = (message) => {
+            this.additions.addMessage(message);
+        };
+        this.addSteps = (title, stepConstructor) => {
+            var _a;
+            const start = new Date();
+            const prevType = this.currentType;
+            this.currentType = "step";
+            const step = new step_1.TestStep(title);
+            try {
+                stepConstructor === null || stepConstructor === void 0 ? void 0 : stepConstructor(step);
+            }
+            catch (err) {
+                this.currentStep.outcome = "Failed";
+                console.log("Step failed. \n", err);
+            }
+            this.currentStep.title = step.title;
+            this.currentStep.description = step.description;
+            this.currentStep.parameters = step.parameters;
+            this.currentStep.outcome = "Passed";
+            this.currentStep.startedOn = start;
+            this.currentStep.completedOn = new Date();
+            this.currentStep.duration = Date.now() - start.getTime();
+            (_a = this.currentTest.stepResults) === null || _a === void 0 ? void 0 : _a.push(this.currentStep);
+            this.currentType = prevType;
+            this.currentStep = emptyStep();
+        };
+        const config = new testit_js_commons_1.ConfigComposer().compose(options === null || options === void 0 ? void 0 : options.tmsOptions);
+        const client = new testit_js_commons_1.Client(config);
+        this.strategy = testit_js_commons_1.StrategyFactory.create(client, config);
+        this.additions = new testit_js_commons_1.Additions(client);
+        this.runner.on(Events.EVENT_RUN_BEGIN, () => this.onStartRun());
+        this.runner.on(Events.EVENT_RUN_END, () => this.onEndRun());
+        this.runner.once(Events.EVENT_TEST_BEGIN, (test) => this.addMethods(test.ctx));
+        this.runner.once(Events.EVENT_HOOK_BEGIN, (hook) => this.addMethods(hook.ctx));
+        this.runner.on(Events.EVENT_TEST_BEGIN, () => this.onStartTest());
+        this.runner.on(Events.EVENT_TEST_END, (test) => this.onEndTest(test));
+    }
+    clearContext(ctx) {
+        ctx.externalId = undefined;
+        ctx.displayName = undefined;
+        ctx.title = undefined;
+        ctx.description = undefined;
+        ctx.links = [];
+        ctx.labels = [];
+        ctx.classname = undefined;
+        ctx.workItemsIds = [];
+        ctx.parameters = {};
+        ctx.properties = {};
+    }
+    addMethods(context) {
+        if (!context)
+            return;
+        context.addAttachments = this.addAttachments;
+        context.addLinks = this.addLinks;
+        context.addMessage = this.addMessage;
+        context.addSteps = this.addSteps;
+    }
+    onStartTest() {
+        this.currentType = "test";
+        this.currentTest.startedOn = new Date();
+    }
+    onEndTest(test) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
+        const hooks = (0, utils_1.extractHooks)(test.parent);
+        const setup = [...hooks.beforeAll, ...hooks.beforeEach];
+        const teardown = [...hooks.afterEach, ...hooks.afterAll];
+        const autotestPost = {
+            externalId: (_b = (_a = test.ctx) === null || _a === void 0 ? void 0 : _a.externalId) !== null && _b !== void 0 ? _b : testit_js_commons_1.Utils.getHash(test.title),
+            name: (_d = (_c = test.ctx) === null || _c === void 0 ? void 0 : _c.displayName) !== null && _d !== void 0 ? _d : test.title,
+            description: (_e = test.ctx) === null || _e === void 0 ? void 0 : _e.description,
+            title: (_f = test.ctx) === null || _f === void 0 ? void 0 : _f.title,
+            links: (_g = test.ctx) === null || _g === void 0 ? void 0 : _g.links,
+            labels: (_j = (_h = test.ctx) === null || _h === void 0 ? void 0 : _h.labels) === null || _j === void 0 ? void 0 : _j.map((label) => ({ name: label })),
+            namespace: (_l = (_k = test.ctx) === null || _k === void 0 ? void 0 : _k.namespace) !== null && _l !== void 0 ? _l : this._getNameSpace(test.file),
+            classname: (_o = (_m = test.ctx) === null || _m === void 0 ? void 0 : _m.classname) !== null && _o !== void 0 ? _o : this._getClassName(test.file),
+            steps: this.currentTest.stepResults,
+            setup,
+            teardown,
+            workItemIds: (_p = test.ctx) === null || _p === void 0 ? void 0 : _p.workItemsIds,
+        };
+        const promise = this.strategy.loadAutotest(autotestPost, test.isPassed());
+        this.autotestsQueue.push(promise);
+        this.autotestsForTestRun.push({
+            autoTestExternalId: autotestPost.externalId,
+            outcome: test.isFailed() ? "Failed" : "Passed",
+            startedOn: this.currentTest.startedOn,
+            completedOn: new Date(),
+            duration: (_q = test.duration) !== null && _q !== void 0 ? _q : Date.now() - this.currentTest.startedOn.getTime(),
+            stepResults: this.currentTest.stepResults,
+            setupResults: setup,
+            teardownResults: teardown,
+            attachments: this.currentTest.attachments,
+            links: this.additions.links,
+            message: ((_r = test.err) === null || _r === void 0 ? void 0 : _r.message)
+                ? this.additions.messages.concat(test.err.message).join("\n")
+                : this.additions.messages.join("\n"),
+            traces: (_s = test.err) === null || _s === void 0 ? void 0 : _s.stack,
+            parameters: (_t = test.ctx) === null || _t === void 0 ? void 0 : _t.parameters,
+            properties: (_u = test.ctx) === null || _u === void 0 ? void 0 : _u.properties,
+        });
+        this.resetTest(test);
+    }
+    resetTest(test) {
+        this.currentTest = emptyTest();
+        this.additions.clear();
+        if (test.ctx)
+            this.clearContext(test.ctx);
+    }
+    _getNameSpace(path) {
+        return path && testit_js_commons_1.Utils.getDir(path.replace(__dirname, ""));
+    }
+    _getClassName(path) {
+        return path && testit_js_commons_1.Utils.getFileName(path);
+    }
+};

package/lib/step.d.ts

@@ -0,0 +1,15 @@
+export interface ITestStep {
+    title: string;
+    description?: string;
+    parameters?: {
+        [key: string]: string;
+    };
+}
+export declare class TestStep implements ITestStep {
+    title: string;
+    description?: string;
+    parameters?: {
+        [p: string]: string;
+    };
+    constructor(title: string);
+}

package/lib/step.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestStep = void 0;
+class TestStep {
+    constructor(title) {
+        this.title = title;
+    }
+}
+exports.TestStep = TestStep;

package/lib/types.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="mocha" />
+import { AdapterConfig, Metadata, DynamicMethods } from "testit-js-commons";
+import { ITestStep } from "./step";
+declare module "mocha" {
+    interface Context extends Metadata, Methods {
+    }
+}
+export interface ReporterOptions extends Mocha.MochaOptions {
+    tmsOptions: AdapterConfig;
+}
+export interface Methods extends DynamicMethods {
+    addSteps: (title: string, stepConstructor?: (step: ITestStep) => void) => void;
+}
+export type Context = Mocha.Context & Metadata & Methods;
+export interface Test extends Mocha.Test {
+    ctx?: Context;
+}
+export interface Hook extends Mocha.Hook {
+    ctx?: Context;
+}
+export type LinkType = "Related" | "BlockedBy" | "Defect" | "Issue" | "Requirement" | "Repository";
+export interface Link {
+    title: string;
+    url: string;
+    description?: string;
+    type?: LinkType;
+    hasInfo?: boolean;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils.d.ts

@@ -0,0 +1,10 @@
+import { Step } from "testit-js-commons";
+import { Suite } from "mocha";
+import { Hook } from "./types";
+export declare function hookToStep(hook: Hook): Step;
+export declare function extractHooks(suite?: Suite): {
+    afterAll: Step[];
+    beforeAll: Step[];
+    afterEach: Step[];
+    beforeEach: Step[];
+};

package/lib/utils.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractHooks = exports.hookToStep = void 0;
+function hookToStep(hook) {
+    var _a;
+    return {
+        title: hook.title,
+        duration: (_a = hook.duration) !== null && _a !== void 0 ? _a : 0,
+    };
+}
+exports.hookToStep = hookToStep;
+function extractHooks(suite) {
+    if (!suite)
+        return { afterAll: [], beforeAll: [], afterEach: [], beforeEach: [] };
+    const hooks = extractHooks(suite.parent);
+    // @ts-ignore
+    const { _afterAll = [], _beforeAll = [], _afterEach = [], _beforeEach = [] } = suite;
+    return {
+        beforeAll: [...hooks.beforeAll, ..._beforeAll.map(hookToStep)],
+        afterAll: [...hooks.afterAll, ..._afterAll.map(hookToStep)],
+        afterEach: [...hooks.afterEach, ..._afterEach.map(hookToStep)],
+        beforeEach: [...hooks.beforeEach, ..._beforeEach.map(hookToStep)],
+    };
+}
+exports.extractHooks = extractHooks;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "testit-adapter-mocha",
+  "version": "1.1.5",
+  "description": "Mocha adapter for Test IT",
+  "main": "lib/reporter.js",
+  "types": "lib/types.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w"
+  },
+  "author": {
+    "name": "Integration team",
+    "email": "integrations@testit.software"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^20.2.4",
+    "@types/request": "^2.48.8",
+    "@typescript-eslint/eslint-plugin": "^5.59.7",
+    "@typescript-eslint/parser": "^5.59.7",
+    "eslint": "^8.41.0",
+    "prettier": "^2.8.8"
+  },
+  "dependencies": {
+    "mocha": "^10.2.0",
+    "testit-js-commons": "^1.1.5"
+  },
+  "files": [
+    "lib"
+  ]
+}