newman-reporter-qase 2.2.0 → 2.3.0

package/README.md

@@ -1,90 +1,274 @@
-# Qase TMS Newman reporter
+# [Qase TestOps](https://qase.io) Newman Reporter
 
-Publish results simple and easy.
+[![License](https://lxgaming.github.io/badges/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![npm downloads](https://img.shields.io/npm/dm/newman-qase-reporter.svg)](https://www.npmjs.com/package/newman-qase-reporter)
 
-To install the latest version, run:
+Qase Newman Reporter enables seamless integration between your Newman/Postman collection tests and [Qase TestOps](https://qase.io), providing automatic test result reporting, test case management, and comprehensive test analytics.
 
-```bash
-npm install newman-reporter-qase
-```
-
-## Example of usage
+## Features
 
-### Define in tests
+- Link automated tests to Qase test cases by ID using special comments
+- Auto-create test cases from your Postman test scripts
+- Report test results with parameterized data
+- Multi-project reporting support
+- Flexible configuration (file, environment variables)
 
-The Newman reporter has the ability to auto-generate test cases
-and suites from your test data.
+> **Note:** Newman integration is unique - tests are defined in Postman collections, and Qase IDs are specified via special comments in test scripts, not via programmatic API imports.
 
-But if necessary, you can independently register the ID of already
-existing test cases from TMS before the executing tests.
-Example:
+## Installation
 
-```js
-//qase: 10
-// Qase: 1, 2, 3
-// qase: 4 5 6 14
-pm.test('expect response be 200', function() {
-  pm.response.to.be.info
-})
+```bash
+npm install --save-dev newman-reporter-qase
 ```
 
-### Execute rom CLI:
+## Quick Start
 
-```
-QASE_MODE=testops newman run ./sample-collection.json -r qase
+**1. Create `qase.config.json` in your project root:**
+
+```json
+{
+  "mode": "testops",
+  "testops": {
+    "project": "YOUR_PROJECT_CODE",
+    "api": {
+      "token": "YOUR_API_TOKEN"
+    }
+  }
+}
 ```
 
-<p align="center">
-  <img width="65%" src="./screenshots/screenshot.png">
-</p>
+**2. Add Qase ID to your Postman test using special comments:**
 
-A test run will be performed and available at:
+In your Postman collection test script:
 
-```
-https://app.qase.io/run/QASE_PROJECT_CODE
+```javascript
+// qase: 1
+pm.test('Response status is 200', function() {
+  pm.response.to.have.status(200);
+});
 ```
 
-<p align="center">
-  <img src="./screenshots/demo.gif">
-</p>
+**3. Run your Newman tests with Qase reporter:**
 
-You can find more information about using the reporter [here](./docs/usage.md).
+```bash
+QASE_MODE=testops newman run ./collection.json -r qase
+```
 
 ## Configuration
 
-Qase Newman reporter can be configured in multiple ways:
+The reporter is configured via (in order of priority):
+
+1. **Environment variables** (`QASE_*`)
+2. **Config file** (`qase.config.json`)
 
-- using a separate config file `qase.config.json`,
-- using environment variables (they override the values from the configuration files).
+### Minimal Configuration
 
-For a full list of configuration options, see
-the [Configuration reference](../qase-javascript-commons/README.md#configuration).
+| Option | Environment Variable | Description |
+|--------|---------------------|-------------|
+| `mode` | `QASE_MODE` | Set to `testops` to enable reporting |
+| `testops.project` | `QASE_TESTOPS_PROJECT` | Your Qase project code |
+| `testops.api.token` | `QASE_TESTOPS_API_TOKEN` | Your Qase API token |
 
-Example `qase.config.json` config:
+### Example `qase.config.json`
 
 ```json
 {
   "mode": "testops",
-  "debug": true,
+  "fallback": "report",
   "testops": {
+    "project": "YOUR_PROJECT_CODE",
     "api": {
-      "token": "api_key"
+      "token": "YOUR_API_TOKEN"
     },
-    "project": "project_code",
     "run": {
-      "complete": true
+      "title": "Newman Automated Run"
+    },
+    "batch": {
+      "size": 100
+    }
+  },
+  "report": {
+    "driver": "local",
+    "connection": {
+      "local": {
+        "path": "./build/qase-report",
+        "format": "json"
+      }
     }
   }
 }
 ```
 
+> **Full configuration reference:** See [qase-javascript-commons](../qase-javascript-commons/README.md) for all available options including logging, status mapping, execution plans, and more.
+
+## Usage
+
+### Link Tests with Test Cases
+
+Associate your Postman tests with Qase test cases using special comments in your test scripts:
+
+**Single ID:**
+```javascript
+// qase: 10
+pm.test('Response is successful', function() {
+  pm.response.to.be.info;
+});
+```
+
+**Multiple IDs:**
+```javascript
+// Qase: 1, 2, 3
+pm.test('Verify user data', function() {
+  pm.expect(pm.response.json()).to.have.property('user');
+});
+```
+
+**Alternative formats:**
+```javascript
+// qase: 4 5 6 14
+pm.test('Check multiple conditions', function() {
+  pm.response.to.have.status(200);
+});
+```
+
+> **Important:** The comment must be on the line immediately before the `pm.test()` call.
+
+### Add Parameters
+
+Newman supports parameterized tests when using data files. Specify which parameters to report using special comments:
+
+```javascript
+// qase.parameters: userId, user.name
+pm.test('User ID is correct', function() {
+  var jsonData = pm.response.json();
+  pm.expect(jsonData.userId).to.eql(pm.iterationData.get('userid'));
+});
+```
+
+You can also specify parameters at the collection or folder level:
+
+```json
+{
+  "item": [{
+    "name": "Folder Name",
+    "event": [{
+      "listen": "test",
+      "script": {
+        "exec": [
+          "// qase.parameters: userId, user.name"
+        ]
+      }
+    }]
+  }]
+}
+```
+
+### Auto-collect All Parameters
+
+To automatically report all parameters from data files without specifying them:
+
+```json
+{
+  "framework": {
+    "newman": {
+      "autoCollectParams": true
+    }
+  }
+}
+```
+
+### Ignore Tests
+
+Newman does not support ignoring individual tests. All tests in the collection will be executed and reported (unless filtered by Newman's own mechanisms like `--folder` flag).
+
+### Test Result Statuses
+
+| Newman Result | Qase Status |
+|---------------|-------------|
+| Passed | passed |
+| Failed | failed |
+| Skipped | skipped |
+
+> For more usage examples, see the [Usage Guide](docs/usage.md).
+
+## Running Tests
+
+### Basic Execution with CLI
+
+```bash
+# Run with Qase reporter
+QASE_MODE=testops newman run ./collection.json -r qase
+
+# Run with multiple reporters
+QASE_MODE=testops newman run ./collection.json -r cli,qase
+
+# Run specific folder
+QASE_MODE=testops newman run ./collection.json -r qase --folder "API Tests"
+```
+
+### Using Data Files
+
+```bash
+# Run with JSON data file
+newman run ./collection.json -r qase -d ./data.json
+
+# Run with CSV data file
+newman run ./collection.json -r qase -d ./users.csv
+```
+
+### Using Environment Variables
+
+```bash
+# Set environment variables
+newman run ./collection.json -r qase -e ./environment.json
+
+# Override config with environment variables
+QASE_MODE=testops \
+QASE_TESTOPS_PROJECT=DEMO \
+QASE_TESTOPS_API_TOKEN=your_token \
+newman run ./collection.json -r qase
+```
+
+### Programmatic Usage
+
+```javascript
+const newman = require('newman');
+
+newman.run({
+  collection: require('./collection.json'),
+  reporters: ['qase'],
+  reporter: {
+    qase: {
+      // Reporter options can be passed here
+      // But prefer using qase.config.json for consistency
+    }
+  }
+}, function(err) {
+  if (err) { throw err; }
+  console.log('Collection run complete');
+});
+```
+
 ## Requirements
 
-We maintain the reporter on LTS versions of Node. You can find the current versions by following
-the [link](https://nodejs.org/en/about/releases/)
+- Node.js >= 14
+- Newman >= 5.3.0
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Usage Guide](docs/usage.md) | Complete usage reference with parameters and examples |
+| [Attachments](docs/ATTACHMENTS.md) | Adding screenshots, logs, and files to test results |
+| [Steps](docs/STEPS.md) | Defining test steps for detailed reporting |
+| [Multi-Project Support](docs/MULTI_PROJECT.md) | Reporting to multiple Qase projects |
+| [Upgrade Guide](docs/UPGRADE.md) | Migration guide for breaking changes |
+| [Configuration Reference](../qase-javascript-commons/README.md) | Full configuration options |
+
+## Examples
 
-`newman >= 5.3.0`
+See the [examples directory](../examples/single/newman/) for complete working examples.
 
-<!-- references -->
+## License
 
-[auth]: https://developers.qase.io/#authentication
+Apache License 2.0. See [LICENSE](LICENSE) for details.

package/changelog.md

@@ -1,3 +1,14 @@
+# newman-reporter-qase@2.3.0
+
+## Changed
+
+- Decomposed `reporter.ts` (433 LOC) into a thin event-driven orchestrator plus 3 focused modules under `src/modules/` (`MetadataExtractor`, `IterationDataParser`, `ResultBuilder`). Public contract preserved 1:1: `NewmanQaseReporter` named export, all 3 static regexps (`qaseIdRegExp`, `qaseParamRegExp`, `qaseProjectRegExp`), all 4 static methods (`getCaseIds`, `getProjectMapping`, `getParameters`, `getParentTitles`), constructor signature, and `NewmanQaseOptionsType` re-export.
+- Bumped `qase-javascript-commons` peer dependency to `~2.7.0` (sync with monorepo; no helper migrations — newman doesn't import from `qase-javascript-commons/internal`).
+
+## Internal
+
+- Added per-module unit tests for the three new modules (37 new tests, 55 total).
+
 # qase-newman@2.2.0
 
 ## What's new

package/dist/modules/iterationDataParser.d.ts

@@ -0,0 +1,5 @@
+export declare class IterationDataParser {
+    parse(iterationData: unknown): Record<string, string>[];
+    private convertToRecord;
+    private isRecord;
+}

package/dist/modules/iterationDataParser.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IterationDataParser = void 0;
+class IterationDataParser {
+    parse(iterationData) {
+        if (!iterationData) {
+            return [];
+        }
+        if (Array.isArray(iterationData) &&
+            iterationData.every((item) => typeof item === 'object' && item !== null)) {
+            return iterationData.map((item) => this.convertToRecord(item));
+        }
+        return [];
+    }
+    convertToRecord(obj, parentKey = '') {
+        const record = {};
+        if (this.isRecord(obj)) {
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    const value = obj[key];
+                    const newKey = parentKey ? `${parentKey}.${key}` : key;
+                    if (this.isRecord(value)) {
+                        Object.assign(record, this.convertToRecord(value, newKey));
+                    }
+                    else {
+                        record[newKey.toLowerCase()] = String(value);
+                    }
+                }
+            }
+        }
+        return record;
+    }
+    isRecord(obj) {
+        return typeof obj === 'object' && obj !== null && !Array.isArray(obj);
+    }
+}
+exports.IterationDataParser = IterationDataParser;

package/dist/modules/metadataExtractor.d.ts

@@ -0,0 +1,12 @@
+import { EventList, Item, PropertyBase, PropertyBaseDefinition } from 'postman-collection';
+import { TestopsProjectMapping } from 'qase-javascript-commons';
+export declare class MetadataExtractor {
+    static qaseIdRegExp: RegExp;
+    static qaseParamRegExp: RegExp;
+    /** Matches // qase PROJ1: 1,2 or // qase PROJ2: 3 for multi-project. */
+    static qaseProjectRegExp: RegExp;
+    static getCaseIds(eventList: EventList): number[];
+    static getProjectMapping(eventList: EventList): TestopsProjectMapping;
+    static getParameters(item: Item): string[];
+    static getParentTitles(item: PropertyBase<PropertyBaseDefinition>): string[];
+}

package/dist/modules/metadataExtractor.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataExtractor = void 0;
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+class MetadataExtractor {
+    static qaseIdRegExp = /\/\/\s*?[qQ]ase:\s?((?:[\d]+[\s,]{0,})+)/;
+    static qaseParamRegExp = /qase\.parameters:\s*([\w.]+(?:\s*,\s*[\w.]+)*)/i;
+    /** Matches // qase PROJ1: 1,2 or // qase PROJ2: 3 for multi-project. */
+    static qaseProjectRegExp = /\/\/\s*[qQ]ase\s+([A-Za-z0-9_]+):\s*([\d,\s]+)/g;
+    static getCaseIds(eventList) {
+        const ids = [];
+        eventList.each((event) => {
+            if (event.listen === 'test' && event.script.exec) {
+                event.script.exec.forEach((line) => {
+                    const [, match] = line.match(MetadataExtractor.qaseIdRegExp) ?? [];
+                    if (match) {
+                        ids.push(...match.split(',').map((id) => Number(id)));
+                    }
+                });
+            }
+        });
+        return ids;
+    }
+    static getProjectMapping(eventList) {
+        const projectMapping = {};
+        eventList.each((event) => {
+            if (event.listen === 'test' && event.script.exec) {
+                event.script.exec.forEach((line) => {
+                    let m;
+                    const re = new RegExp(MetadataExtractor.qaseProjectRegExp.source, 'gi');
+                    while ((m = re.exec(line)) !== null) {
+                        const projectCode = m[1]?.trim();
+                        const idsStr = (m[2] ?? '').replace(/\s/g, '');
+                        const ids = idsStr.split(',').map((s) => parseInt(s, 10)).filter((n) => !Number.isNaN(n));
+                        if (projectCode && projectCode.toUpperCase() !== 'ID' && ids.length > 0) {
+                            const existing = projectMapping[projectCode] ?? [];
+                            projectMapping[projectCode] = [...existing, ...ids];
+                        }
+                    }
+                });
+            }
+        });
+        return projectMapping;
+    }
+    static getParameters(item) {
+        const params = [];
+        item.events.each((event) => {
+            if (event.listen === 'test' && event.script.exec) {
+                event.script.exec.forEach((line) => {
+                    const match = line.match(MetadataExtractor.qaseParamRegExp);
+                    if (match) {
+                        const parameters = match[1]?.split(/\s*,\s*/) ?? [];
+                        params.push(...parameters);
+                    }
+                });
+            }
+        });
+        const parent = item.parent();
+        if (parent && 'events' in parent) {
+            params.push(...MetadataExtractor.getParameters(parent));
+        }
+        return params;
+    }
+    static getParentTitles(item) {
+        let titles = [];
+        const parent = item.parent();
+        if (parent) {
+            titles = titles.concat(MetadataExtractor.getParentTitles(parent));
+        }
+        if ('name' in item) {
+            titles.push(String(item.name));
+        }
+        return titles;
+    }
+}
+exports.MetadataExtractor = MetadataExtractor;

package/dist/modules/resultBuilder.d.ts

@@ -0,0 +1,12 @@
+import { Item } from 'postman-collection';
+import { TestopsProjectMapping, TestResultType } from 'qase-javascript-commons';
+export interface BuildPendingArgs {
+    item: Item;
+    suites: string[];
+    ids: number[];
+    projectMapping: TestopsProjectMapping;
+    signature: string;
+}
+export declare class ResultBuilder {
+    static buildPending(args: BuildPendingArgs): TestResultType;
+}

package/dist/modules/resultBuilder.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResultBuilder = void 0;
+const qase_javascript_commons_1 = require("qase-javascript-commons");
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+class ResultBuilder {
+    static buildPending(args) {
+        const { item, suites, ids, projectMapping, signature } = args;
+        let relation = null;
+        if (suites.length > 0) {
+            const data = suites.map((title) => ({ title, public_id: null }));
+            relation = { suite: { data } };
+        }
+        return {
+            attachments: [],
+            author: null,
+            execution: {
+                status: qase_javascript_commons_1.TestStatusEnum.passed,
+                start_time: null,
+                end_time: null,
+                duration: 0,
+                stacktrace: null,
+                thread: null,
+            },
+            fields: {},
+            message: null,
+            muted: false,
+            params: {},
+            group_params: {},
+            relations: relation,
+            run_id: null,
+            signature,
+            steps: [],
+            testops_id: ids.length > 0 ? ids : null,
+            id: item.id,
+            title: item.name,
+            testops_project_mapping: Object.keys(projectMapping).length > 0 ? projectMapping : null,
+        };
+    }
+}
+exports.ResultBuilder = ResultBuilder;

package/dist/reporter.d.ts

@@ -1,113 +1,26 @@
 import { EventEmitter } from 'events';
 import { NewmanRunOptions } from 'newman';
-import { EventList, Item, PropertyBase, PropertyBaseDefinition } from 'postman-collection';
-import { ConfigType, TestopsProjectMapping, ConfigLoader } from 'qase-javascript-commons';
+import { ConfigType, ConfigLoader } from 'qase-javascript-commons';
+import { MetadataExtractor } from './modules/metadataExtractor';
 export type NewmanQaseOptionsType = ConfigType;
 /**
  * @class NewmanQaseReporter
  */
 export declare class NewmanQaseReporter {
-    /**
-     * @type {RegExp}
-     */
     static qaseIdRegExp: RegExp;
-    /**
-     * @type {RegExp}
-     */
     static qaseParamRegExp: RegExp;
-    /** Matches // qase PROJ1: 1,2 or // qase PROJ2: 3 for multi-project. */
     static qaseProjectRegExp: RegExp;
-    /**
-     * Parse multi-project mapping from test script comments (e.g. // qase PROJ1: 1,2).
-     * @param {EventList} eventList
-     * @returns {TestopsProjectMapping}
-     */
-    static getProjectMapping(eventList: EventList): TestopsProjectMapping;
-    /**
-     * @param {EventList} eventList
-     * @returns {number[]}
-     */
-    static getCaseIds(eventList: EventList): number[];
-    /**
-     * @param {Item} item
-     * @returns {string[]}
-     */
-    static getParameters(item: Item): string[];
-    /**
-     * @param {PropertyBase<PropertyBaseDefinition>} item
-     * @returns {string[]}
-     */
-    static getParentTitles(item: PropertyBase<PropertyBaseDefinition>): string[];
-    /**
-     * @type {ReporterInterface}
-     * @private
-     */
+    static getCaseIds: typeof MetadataExtractor.getCaseIds;
+    static getProjectMapping: typeof MetadataExtractor.getProjectMapping;
+    static getParameters: typeof MetadataExtractor.getParameters;
+    static getParentTitles: typeof MetadataExtractor.getParentTitles;
     private reporter;
-    /**
-     * @type {Map<string, TestResultType>}
-     * @private
-     */
     private pendingResultMap;
-    /**
-     * @type {Map<string, number>}
-     * @private
-     */
     private timerMap;
-    /**
-     * @type {Record<string, string>[]}
-     * @private
-     */
     private readonly parameters;
-    /**
-     * @type {boolean}
-     * @private
-     */
     private autoCollectParams;
-    /**
-     * @param {EventEmitter} emitter
-     * @param {NewmanQaseOptionsType} options
-     * @param {NewmanRunOptions} collectionOptions
-     * @param {ConfigLoaderInterface} configLoader
-     */
     constructor(emitter: EventEmitter, options: NewmanQaseOptionsType, collectionOptions: NewmanRunOptions, configLoader?: ConfigLoader<import("qase-javascript-commons").FrameworkOptionsType<"newman", import("./options").ReporterOptionsType>>);
-    /**
-     * @param {EventEmitter} runner
-     * @private
-     */
     private addRunnerListeners;
-    /**
-     * @private
-     */
-    private preventExit;
-    /**
-     * @param {string[]} suites
-     * @param {string} title
-     * @param {number[]} ids
-     * @private
-     */
-    private getSignature;
-    /**
-     * @param {Item} item
-     * @param {number} iteration
-     * @returns {Record<string, string>}
-     * @private
-     */
     private prepareParameters;
-    /**
-     * @param {unknown} iterationData
-     * @private
-     */
-    private getParameters;
-    /**
-     * @param {unknown} obj
-     * @param parentKey
-     * @returns {Record<string, string>}
-     * @private
-     */
-    private convertToRecord;
-    /**
-     * @param {unknown} obj
-     * @private
-     */
-    private isRecord;
+    private preventExit;
 }