qase-javascript-commons 2.0.0-beta.0 → 2.0.0-beta.10

package/README.md

@@ -1,102 +1,79 @@
-## Install
+# Qase JavaScript Commons
 
-```
-$ npm install --save qase-core-reporter
-```
-
-## Usage
-
-> Create a new Qase JS reporter in minutes by leveraging this core reporter.
-> Use Qase core reporter with test framework custom reporter hooks
-
-```js
-import {
-  QaseCoreReporter,
-  QaseOptions,
-  QaseCoreReporterOptions,
-  TestResult
-} from "qase-core-reporter";
+This package contains common classes and functions for working with Qase TMS API.
 
-const reporterOptions: QaseOptions = {
-  // expected options, provided by reporter user
-  apiToken: 'lknkldnfknobek'
-  projectCode: 'DH'
-};
+## Installation
 
-const qaseCoreReporterOptions: QaseCoreReporterOptions = {
-  // expected core options, provider by reporter developer
-  frameworkName: 'vitest',
-  reporterName: 'vitest-qase-reporter'
-};
-
-// Initialize Core reporter with expected params
-const reporter = new QaseCoreReporter(reporterOptions, qaseCoreReporterOptions);
-
-// On start hook
-reporter.start();
-
-// On test results
-reporter.addTestResult(test: TestResult, status, attachments);
-
-// On end/complete hook
-reporter.end({ spawn: false }); // spawn true will finish reporting in a child process
+```bash
+npm install qase-javascript-commons@beta
 ```
 
-## Reporter Options
-
-<a name="qase-core-reporter"></a>
-
-## reporter(qaseOptions, qaseCoreReporterOptions) ⇒ <code>QaseCoreReporter</code>
-
-| Param                                       | Type      | Required | Description                                                                       |
-| ------------------------------------------- | --------- | -------- | --------------------------------------------------------------------------------- |
-| qaseOptions                                 | `object`  | yes      |                                                                                   |
-| qaseOptions.`report`                        | `boolean` | no       | Whether or not to enable reporter                                                 |
-| qaseOptions.`apiToken`                      | `string`  | yes      | Qase api key                                                                      |
-| qaseOptions.`projectCode`                   | `string`  | yes      | Qase project ID                                                                   |
-| qaseOptions.`basePath`                      | `string`  | no       | Qase API base url                                                                 |
-| qaseOptions.`rootSuiteTitle`                | `string`  | no       | The root suite that unknown test cases will be added to                           |
-| qaseOptions.`runId`                         | `string`  | no       | Qase run ID, if you want results to be posted to a specific run                   |
-| qaseOptions.`logging`                       | `boolean` | no       | Whether or not to output Qase logs while testing and reporting                    |
-| qaseOptions.`runComplete`                   | `boolean` | no       | Whether or not to complete a test run when results are posted                     |
-| qaseOptions.`environmentId`                 | `string`  | no       | Qase environment ID                                                               |
-| qaseOptions.`runDescription`                | `string`  | no       | Qase run custom description                                                       |
-| qaseOptions.`runName`                       | `string`  | no       | Qase run custom name                                                              |
-| qaseCoreReporterOptions                     | `object`  | yes      |                                                                                   |
-| qaseCoreReporterOptions.`frameworkName`     | `string`  | yes      | Test automation framework/package name                                            |
-| qaseCoreReporterOptions.`reporterName`      | `string`  | yes      | Current qase reporter package name                                                |
-| qaseCoreReporterOptions.`uploadAttachments` | `boolean` | no       | Wether or not to upload attachments                                               |
-| qaseCoreReporterOptions.`screenshotFolder`  | `string`  | no       | Folder to find screenshots with Qase ID in file name                              |
-| qaseCoreReporterOptions.`videoFolder`       | `string`  | no       | Folder to find videos with Qase ID in file name                                   |
-| qaseCoreReporterOptions.`loadConfig`        | `boolean` | no       | Whether or not to also load reporter options from `qase.config.json` or `.qaserc` |
-
-## API (public methods)
-
-<a name="qase-core-reporter-public-methods"></a>
-
-| Method                                   | Description                                                                                                     |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| start()                                  | Check if reporting is enabled, check project and create run if needed                                           |
-| addTestResult(test, status, attachments) | Parse and save test results for publishing                                                                      |
-| end({spawn: true/false})                 | Upload attachments if needed and map to existing results, send results as BulkCreate, complete run if specified |
-| uploadAttachments(attachments)           | Upload attachments based on file path and return attachment hashes for test results                             |
-
-## Qase Reporter Environmental Variables
-
-> Qase environmental variables are first class options, which means the user can change all default/static reporter options by using these variables.
-
-<a name="qase-core-reporter-envs"></a>
-| Variable | Type | Description |
-| ------------------------- | --------- | -------------------------------------------------------------- |
-| `QASE_REPORT` | boolean | Whether or not to enable reporter |
-| `QASE_API_TOKEN` | string | Qase api key |
-| `QASE_API_BASE_URL` | string | Qase API base url |
-| `QASE_PROJECT_CODE` | string | Qase project ID |
-| `QASE_RUN_ID` | string | Qase run ID, if you want results to be posted to a specific run |
-| `QASE_RUN_NAME` | string | Qase run custom name |
-| `QASE_RUN_DESCRIPTION` | string | Qase run custom description |
-| `QASE_RUN_COMPLETE` | string | Whether or not to complete a test run when results are posted |
-| `QASE_ENVIRONMENT_ID` | string | Qase environment ID |
-| `QASE_ROOT_SUITE_TITLE` | string | The root suite that unknown test cases will be added to |
-| `QASE_UPLOAD_ATTACHMENTS` | string | Whether or not to upload attachments
-| `QASE_LOGGING` | boolean | Whether or not to output Qase logs while testing and reporting |
+## Configuration
+
+Qase JS Reporters can be configured in multiple ways:
+
+- using a config file `qase.config.json`
+- using environment variables
+
+All configuration options are listed in the table below:
+
+| Description                                                                                                                | Config file                | Environment variable            | Default value                           | Required | Possible values            |
+|----------------------------------------------------------------------------------------------------------------------------|----------------------------|---------------------------------|-----------------------------------------|----------|----------------------------|
+| **Common**                                                                                                                 |                            |                                 |                                         |          |                            |
+| Mode of reporter                                                                                                           | `mode`                     | `QASE_MODE`                     | `testops`                               | No       | `testops`, `report`, `off` |
+| Fallback mode of reporter                                                                                                  | `fallback`                 | `QASE_FALLBACK`                 | `off`                                   | No       | `testops`, `report`, `off` |
+| Environment                                                                                                                | `environment`              | `QASE_ENVIRONMENT`              | `local`                                 | No       | Any string                 |
+| Enable debug logs                                                                                                          | `debug`                    | `QASE_DEBUG`                    | `False`                                 | No       | `True`, `False`            |
+| Enable capture logs from `stdout` and `stderr`                                                                             | `testops.defect`           | `QASE_CAPTURE_LOGS`             | `False`                                 | No       | `True`, `False`            |
+| **Qase Report configuration**                                                                                              |                            |                                 |                                         |          |                            |
+| Driver used for report mode                                                                                                | `report.driver`            | `QASE_REPORT_DRIVER`            | `local`                                 | No       | `local`                    |
+| Path to save the report                                                                                                    | `report.connection.path`   | `QASE_REPORT_CONNECTION_PATH`   | `./build/qase-report`                   |          |                            |
+| Local report format                                                                                                        | `report.connection.format` | `QASE_REPORT_CONNECTION_FORMAT` | `json`                                  |          | `json`, `jsonp`            |
+| **Qase TestOps configuration**                                                                                             |                            |                                 |                                         |          |                            |
+| Token for [API access](https://developers.qase.io/#authentication)                                                         | `testops.api.token`        | `QASE_TESTOPS_API_TOKEN`        |                                         | Yes      | Any string                 |
+| Qase API host                                                                                                              | `testops.api.host`         | `QASE_TESTOPS_API_HOST`         | `qase.io`                               | No       | Any string                 |
+| Code of your project, which you can take from the URL: `https://app.qase.io/project/DEMOTR` - `DEMOTR` is the project code | `testops.project`          | `QASE_TESTOPS_PROJECT`          |                                         | Yes      | Any string                 |
+| Qase test run ID                                                                                                           | `testops.run.id`           | `QASE_TESTOPS_RUN_ID`           |                                         | No       | Any integer                |
+| Qase test run title                                                                                                        | `testops.run.title`        | `QASE_TESTOPS_RUN_TITLE`        | `Automated run <Current date and time>` | No       | Any string                 |
+| Qase test run description                                                                                                  | `testops.run.description`  | `QASE_TESTOPS_RUN_DESCRIPTION`  | `<Framework name> automated run`        | No       | Any string                 |
+| Qase test run complete                                                                                                     | `testops.run.complete`     | `QASE_TESTOPS_RUN_COMPLETE`     | `True`                                  |          | `True`, `False`            |
+| Qase test plan ID                                                                                                          | `testops.plan.id`          | `QASE_TESTOPS_PLAN_ID`          |                                         | No       | Any integer                |
+| Size of batch for sending test results                                                                                     | `testops.batch.size`       | `QASE_TESTOPS_BATCH_SIZE`       | `200`                                   | No       | Any integer                |
+| Enable defects for failed test cases                                                                                       | `testops.defect`           | `QASE_TESTOPS_DEFECT`           | `False`                                 | No       | `True`, `False`            |
+
+### Example `qase.config.json` config:
+
+```json
+{
+  "mode": "testops",
+  "fallback": "report",
+  "debug": false,
+  "environment": "local",
+  "captureLogs": false,
+  "report": {
+    "driver": "local",
+    "connection": {
+      "local": {
+        "path": "./build/qase-report",
+        "format": "json"
+      }
+    }
+  },
+  "testops": {
+    "api": {
+      "token": "<token>",
+      "host": "qase.io"
+    },
+    "run": {
+      "title": "Regress run",
+      "description": "Regress run description",
+      "complete": true
+    },
+    "defect": false,
+    "project": "<project_code>",
+    "batch": {
+      "size": 100
+    }
+  }
+}
+```

package/changelog.md

@@ -0,0 +1,159 @@
+# qase-javascript-commons@2.0.0-beta.10
+
+## What's new
+
+Fixed an issue when the results published before the test run creation.
+
+# qase-javascript-commons@2.0.0-beta.9
+
+## What's new
+
+Improved debug logging for better testing and reporting errors.
+
+-   Separate `logger` class for use in reporters, supporting logging to console and files.
+-   Extra debug logs in both reporter modes: TestOps and Local.
+
+Fixed an issue with duplicate test runs created when the testing framework
+(such as Cypress) uses more than one instance of the Qase reporter.
+Now reporter handles Qase test runs in the following way:
+
+1.  The first instance of the reporter creates a Qase test run and stores the run ID 
+    in the ENV variable `QASE_TESTOPS_RUN_ID`.
+2.  Other instances of the reporter read this variable and report test results 
+    to the existing test run.
+
+Nothing has changed in cases when there is a single instance of a reporter or
+when it is using a test run, created with other tools, such as with an API request
+or manually in the Qase app.
+
+# qase-javascript-commons@2.0.0-beta.8
+
+## What's new
+
+Renamed the `QASE_TESTOPS_CHUNK` environment variable to `QASE_TESTOPS_BATCH_SIZE`.
+Renamed the `chunk` field in the reporter's configuration to `batch.size`.
+
+```diff
+{
+  ...
+  "testops": {
+-   "chunk": 10
++   "batch": {
++      "size": 10
++    }
+    ...
+  },
+  ...
+}
+```
+
+# qase-javascript-commons@2.0.0-beta.7
+
+## What's new
+
+TestOps reporter supports uploading test result in real-time.
+It can be useful for long-running tests, where you want to see the results as soon as they are available.
+You can use chunk size to control the size of the data sent to the Qase.
+
+To enable real-time reporting, set an environment variable before running the tests or use the reporter's configuration:
+
+```bash
+QASE_TESTOPS_CHUNK=10
+```
+
+```diff
+{
+  ...
+  "testops": {
++   "chunk": 10
+    ...
+  },
+  ...
+}
+```
+
+where `10` is the size of the chunk in test result's count.
+
+# qase-javascript-commons@2.0.0-beta.6
+
+## What's new
+
+### Select the API version to use for reporting
+
+Qase TestOps API has two endpoints for reporting test results:
+
+- Version 1, stable and used my most test reporters.
+  https://developers.qase.io/reference/create-result-bulk
+- Version 2, currently in beta access, and currently supported only
+  in the `playwright-qase-reporter`.
+  https://developers.qase.io/v2.0/reference/create-results-v2
+
+This commit introduces a way to select the API version to use.
+It enables using all new features of v2 JS reporters with the stable v1 API,
+and elso experimenting with the new v2 API.
+
+**Warning**: v2 API is still in beta. 
+If you want to try the v2 JS reporters, you don't have to enable the new API.
+
+To enable using API v2, set an environment variable before running the tests:
+
+```bash
+QASE_TESTOPS_API_V2=true
+```
+
+### Support adding test suite description to a test report.
+
+Test reporters can now test suite description to test results.
+Such description can be collected from test's location and attributes
+or explicitly declared in the test.
+
+Add new data models:
+- Relation
+- Suite
+- SuiteData
+
+
+# qase-javascript-commons@2.0.0-beta.5
+
+## What's new
+
+* Update the config of reporters. Added `captureLogs` field. If it is set to `true`, the reporter will capture logs from the test framework.
+* Added `getMimeType` function to the commons package. It returns the MIME type of the file by its extension.
+
+# qase-javascript-commons@2.0.0-beta.4
+
+## What's new
+
+* Added support for uploading attachments from strings and buffers in the testops reporter.
+* Changed data type of `content` in the attachment data from `any` to `string | Buffer`.
+
+# qase-javascript-commons@2.0.0-beta.3
+
+## What's new
+
+* Changed data type of `fields` and `parameters` in the test result data
+  from `Map<string, string>` to `Record<string, string>`.
+
+# qase-javascript-commons@2.0.0-beta.2
+
+## Overview
+
+Package `qase-javascript-commons` contains common functions, used by all Qase JavaScript reporters.
+
+This is a beta channel release.
+Don't install this package explicitly.
+Instead, install the test reporter for your framework, for example:
+
+```bash
+npm install playwright-qase-reporter@beta
+```
+
+## What's new
+
+* Set a fallback reporter when the primary reporter can't be used,
+  such as when the `testops` reporter can't authenticate with the Qase API.
+* Rename some environment variables to keep naming consistent between reporters in all languages.
+* Add several environment variables for new config options.
+* Write outputs in JSONP format, which can be used with
+  [Qase Report](https://github.com/qase-tms/qase-report).
+* Logic for handling test with multiple case IDs moved to the commons package.

package/dist/config/config-loader-interface.d.ts

@@ -0,0 +1,4 @@
+import { ConfigType } from './config-type';
+export interface ConfigLoaderInterface<T extends Partial<ConfigType>> {
+    load(files: string[]): (T & ConfigType) | null;
+}

package/dist/config/config-loader-interface.js

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

package/dist/config/config-loader.d.ts

@@ -0,0 +1,10 @@
+import { JSONSchemaType } from 'ajv';
+import { ConfigLoaderInterface } from './config-loader-interface';
+import { ConfigType } from './config-type';
+export declare class ConfigLoader<T extends Partial<ConfigType> & Record<string, unknown>> implements ConfigLoaderInterface<T> {
+    private paths;
+    private validationSchema;
+    constructor(validationSchema?: JSONSchemaType<T>, paths?: string[]);
+    private read;
+    load(): (T & ConfigType) | null;
+}

package/dist/config/config-loader.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const lodash_merge_1 = __importDefault(require("lodash.merge"));
+const qase_error_1 = require("../utils/qase-error");
+const validate_json_1 = require("../utils/validate-json");
+const config_validation_schema_1 = require("./config-validation-schema");
+class ConfigLoader {
+    constructor(validationSchema, paths = ['qase.config.json', '.qaserc']) {
+        this.paths = paths;
+        this.validationSchema = (0, lodash_merge_1.default)({}, config_validation_schema_1.configValidationSchema, validationSchema);
+    }
+    read() {
+        for (const path of this.paths) {
+            const filePath = (0, path_1.join)(process.cwd(), path);
+            try {
+                return (0, fs_1.readFileSync)(filePath, 'utf8');
+            }
+            catch (error) {
+                const isNotFound = error instanceof Error &&
+                    'code' in error &&
+                    (error.code === 'ENOENT' || error.code === 'EISDIR');
+                if (!isNotFound) {
+                    throw new qase_error_1.QaseError('Cannot read config file', { cause: error });
+                }
+            }
+        }
+        return null;
+    }
+    load() {
+        try {
+            const data = this.read();
+            if (data) {
+                const json = JSON.parse(data);
+                (0, validate_json_1.validateJson)(this.validationSchema, json);
+                return json;
+            }
+        }
+        catch (error) {
+            if (error instanceof validate_json_1.JsonValidationError) {
+                const [validationError] = error.validationErrors;
+                const { instancePath = '', message = '' } = validationError ?? {};
+                const configPath = instancePath
+                    ? `\`${instancePath.substring(1).replace('/', '.')}\``
+                    : 'it';
+                throw new Error(`Invalid config: "${configPath}" ${message}`);
+            }
+            throw error;
+        }
+        return null;
+    }
+}
+exports.ConfigLoader = ConfigLoader;

package/dist/config/config-type.d.ts

@@ -0,0 +1,2 @@
+import { OptionsType } from '../options';
+export type ConfigType = Omit<OptionsType, 'frameworkPackage' | 'frameworkName' | 'reporterName'>;

package/dist/config/config-type.js

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

package/dist/config/config-validation-schema.d.ts

@@ -0,0 +1,6 @@
+import { JSONSchemaType } from 'ajv';
+import { ConfigType } from './config-type';
+/**
+ * @type {JSONSchemaType<ConfigType>}
+ */
+export declare const configValidationSchema: JSONSchemaType<ConfigType>;

package/dist/config/config-validation-schema.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configValidationSchema = void 0;
+const options_1 = require("../options");
+const writer_1 = require("../writer");
+/**
+ * @type {JSONSchemaType<ConfigType>}
+ */
+exports.configValidationSchema = {
+    type: 'object',
+    properties: {
+        mode: {
+            type: 'string',
+            enum: [options_1.ModeEnum.report, options_1.ModeEnum.testops, options_1.ModeEnum.off],
+            nullable: true,
+        },
+        fallback: {
+            type: 'string',
+            enum: [options_1.ModeEnum.report, options_1.ModeEnum.testops, options_1.ModeEnum.off],
+            nullable: true,
+        },
+        debug: {
+            type: 'boolean',
+            nullable: true,
+        },
+        environment: {
+            type: ['string', 'number'],
+            nullable: true,
+        },
+        captureLogs: {
+            type: 'boolean',
+            nullable: true,
+        },
+        testops: {
+            type: 'object',
+            nullable: true,
+            properties: {
+                api: {
+                    type: 'object',
+                    nullable: true,
+                    properties: {
+                        token: {
+                            type: 'string',
+                            nullable: true,
+                        },
+                        baseUrl: {
+                            type: 'string',
+                            nullable: true,
+                        },
+                        headers: {
+                            type: 'object',
+                            nullable: true,
+                            additionalProperties: false,
+                            patternProperties: {
+                                '^.*$': {
+                                    type: 'string',
+                                },
+                            },
+                        },
+                        retries: {
+                            type: 'number',
+                            nullable: true,
+                        },
+                        retryDelay: {
+                            type: 'number',
+                            nullable: true,
+                        },
+                    },
+                },
+                project: {
+                    type: 'string',
+                    nullable: true,
+                },
+                uploadAttachments: {
+                    type: 'boolean',
+                    nullable: true,
+                },
+                run: {
+                    type: 'object',
+                    nullable: true,
+                    properties: {
+                        id: {
+                            type: 'number',
+                            nullable: true,
+                        },
+                        title: {
+                            type: 'string',
+                            nullable: true,
+                        },
+                        description: {
+                            type: 'string',
+                            nullable: true,
+                        },
+                        complete: {
+                            type: 'boolean',
+                            nullable: true,
+                        },
+                    },
+                },
+                plan: {
+                    type: 'object',
+                    nullable: true,
+                    properties: {
+                        id: {
+                            type: 'number',
+                            nullable: true,
+                        },
+                    },
+                },
+                batch: {
+                    type: 'object',
+                    nullable: true,
+                    properties: {
+                        size: {
+                            type: 'number',
+                            nullable: true,
+                        },
+                    },
+                },
+                defect: {
+                    type: 'boolean',
+                    nullable: true,
+                },
+                useV2: {
+                    type: 'boolean',
+                    nullable: true,
+                },
+            },
+        },
+        report: {
+            type: 'object',
+            nullable: true,
+            properties: {
+                driver: {
+                    type: 'string',
+                    enum: [writer_1.DriverEnum.local],
+                    nullable: true,
+                },
+                connections: {
+                    type: 'object',
+                    nullable: true,
+                    properties: {
+                        [writer_1.DriverEnum.local]: {
+                            type: 'object',
+                            nullable: true,
+                            properties: {
+                                path: {
+                                    type: 'string',
+                                    nullable: true,
+                                },
+                                format: {
+                                    type: 'string',
+                                    enum: [writer_1.FormatEnum.json, writer_1.FormatEnum.jsonp],
+                                    nullable: true,
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};

package/dist/config/index.d.ts

@@ -0,0 +1,4 @@
+export { type ConfigType } from './config-type';
+export { configValidationSchema } from './config-validation-schema';
+export { type ConfigLoaderInterface } from './config-loader-interface';
+export { ConfigLoader } from './config-loader';

package/dist/config/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = exports.configValidationSchema = void 0;
+var config_validation_schema_1 = require("./config-validation-schema");
+Object.defineProperty(exports, "configValidationSchema", { enumerable: true, get: function () { return config_validation_schema_1.configValidationSchema; } });
+var config_loader_1 = require("./config-loader");
+Object.defineProperty(exports, "ConfigLoader", { enumerable: true, get: function () { return config_loader_1.ConfigLoader; } });