playwright-qase-reporter 2.0.15 → 2.0.17

package/README.md

@@ -155,7 +155,7 @@ https://app.qase.io/run/QASE_PROJECT_CODE
 ```
 
 <p align="center">
-  <img src="./screenshots/demo.gif">
+  <img width="85%" src="./screenshots/test-run.gif">
 </p>
 
 ## Configuration
@@ -165,11 +165,8 @@ Reporter options (\* - required):
 - `mode` - `testops`/`off` Enables reporter, default - `off`
 - `debug` - Enables debug logging, default - `false`
 - `environment` - To execute with the sending of the environment information 
-- *`testops.api.token` - Token for API access, you can find more information
-  [here](https://developers.qase.io/#authentication)
-- *`testops.project` - Code of your project (can be extracted from main
-  page of your project: `https://app.qase.io/project/DEMOTR` -
-  `DEMOTR` is project code here)
+- *`testops.api.token` - Token for API access, you can generate it [here](https://developers.qase.io/#authentication).
+- *`testops.project` - [Your project's code](https://help.qase.io/en/articles/9787250-how-do-i-find-my-project-code)
 - `testops.uploadAttachments` - Permission to send screenshots to Qase TMS
 - `testops.run.id` - Pass Run ID
 - `testops.run.title` - Set custom Run name, when new run is created

package/changelog.md

@@ -1,3 +1,15 @@
+# playwright-qase-reporter@2.0.17
+
+## What's new
+
+Introduced the ability to specify expected results and data for each step, improving step validation and customization.
+
+# playwright-qase-reporter@2.0.16
+
+## What's new
+
+Improve excluding default steps, like `Worker Cleanup`, `Before Hook`, and `After Hook`.
+
 # playwright-qase-reporter@2.0.15
 
 ## What's new

package/dist/playwright.d.ts

@@ -128,4 +128,17 @@ export declare const qase: {
      * });
      */
     comment(value: string): any;
+    /**
+     * Set a expected result and data for the test step
+     * @param action
+     * @param expectedResult
+     * @param data
+     * @example
+     * test('test', async ({ page }) => {
+     *    await test.step(qase.step('action', 'expected result', 'data'), async () => {
+     *      await page.goto('https://example.com');
+     *    });
+     * });
+     */
+    step(action: string, expectedResult: string | undefined, data: string | undefined): string;
 };

package/dist/playwright.js

@@ -231,6 +231,21 @@ exports.qase.comment = function (value) {
     });
     return this;
 };
+/**
+ * Set a expected result and data for the test step
+ * @param action
+ * @param expectedResult
+ * @param data
+ * @example
+ * test('test', async ({ page }) => {
+ *    await test.step(qase.step('action', 'expected result', 'data'), async () => {
+ *      await page.goto('https://example.com');
+ *    });
+ * });
+ */
+exports.qase.step = function (action, expectedResult, data) {
+    return `${action} QaseExpRes:${expectedResult ? `: ${expectedResult}` : ''} QaseData:${data ? `: ${data}` : ''}`;
+};
 const addMetadata = (metadata) => {
     test_1.default.info().attach('qase-metadata.json', {
         contentType: exports.ReporterContentType,

package/dist/reporter.d.ts

@@ -103,4 +103,11 @@ export declare class PlaywrightQaseReporter implements Reporter {
      * @private
      */
     private extractQaseIdsFromAnnotation;
+    /**
+     * @param {TestStep[]} steps
+     * @returns {boolean}
+     * @private
+     */
+    private checkChildrenSteps;
+    private extractAndCleanStep;
 }

package/dist/reporter.js

@@ -36,6 +36,21 @@ const defaultSteps = ['Before Hooks', 'After Hooks', 'Worker Cleanup'];
  * @implements Reporter
  */
 class PlaywrightQaseReporter {
+    /**
+     * @type {Record<TestStatus, TestStatusEnum>}
+     */
+    static statusMap = {
+        passed: qase_javascript_commons_1.TestStatusEnum.passed,
+        failed: qase_javascript_commons_1.TestStatusEnum.failed,
+        skipped: qase_javascript_commons_1.TestStatusEnum.skipped,
+        timedOut: qase_javascript_commons_1.TestStatusEnum.failed,
+        interrupted: qase_javascript_commons_1.TestStatusEnum.failed,
+    };
+    /**
+     * @type {Map<string, number[]>}
+     * @private
+     */
+    static qaseIds = new Map();
     /**
      * @param {TestCase} test
      * @returns {string[]}
@@ -44,6 +59,16 @@ class PlaywrightQaseReporter {
     static transformSuiteTitle(test) {
         return test.titlePath().filter(Boolean);
     }
+    /**
+     * @type {Map<TestStep, TestCase>}
+     * @private
+     */
+    stepCache = new Map();
+    /**
+     * @type {Map<string, TestStep>}
+     * @private
+     */
+    stepAttachments = new Map();
     /**
      * @param {ArrayItemType<TestResult['attachments']>[]} testAttachments
      * @returns {TestCaseMetadata}
@@ -184,17 +209,19 @@ class PlaywrightQaseReporter {
                 || testStep.title.match(stepAttachRegexp)) {
                 continue;
             }
-            if (defaultSteps.includes(testStep.title) && testStep.steps.length === 0) {
+            if (defaultSteps.includes(testStep.title) && this.checkChildrenSteps(testStep.steps)) {
                 continue;
             }
             const attachments = this.stepAttachments.get(testStep);
+            const stepData = this.extractAndCleanStep(testStep.title);
             const id = (0, uuid_1.v4)();
             const step = {
                 id: id,
                 step_type: qase_javascript_commons_1.StepType.TEXT,
                 data: {
-                    action: testStep.title,
-                    expected_result: null,
+                    action: stepData.cleanedString,
+                    expected_result: stepData.expectedResult,
+                    data: stepData.data,
                 },
                 parent_id: parentId,
                 execution: {
@@ -210,21 +237,16 @@ class PlaywrightQaseReporter {
         }
         return steps;
     }
+    /**
+     * @type {ReporterInterface}
+     * @private
+     */
+    reporter;
     /**
      * @param {PlaywrightQaseOptionsType} options
      * @param {ConfigLoaderInterface} configLoader
      */
     constructor(options, configLoader = new qase_javascript_commons_1.ConfigLoader()) {
-        /**
-         * @type {Map<TestStep, TestCase>}
-         * @private
-         */
-        this.stepCache = new Map();
-        /**
-         * @type {Map<string, TestStep>}
-         * @private
-         */
-        this.stepAttachments = new Map();
         const config = configLoader.load();
         this.reporter = qase_javascript_commons_1.QaseReporter.getInstance({
             ...(0, qase_javascript_commons_1.composeOptions)(options, config),
@@ -411,20 +433,41 @@ class PlaywrightQaseReporter {
         }
         return ids;
     }
+    /**
+     * @param {TestStep[]} steps
+     * @returns {boolean}
+     * @private
+     */
+    checkChildrenSteps(steps) {
+        if (steps.length === 0) {
+            return true;
+        }
+        for (const step of steps) {
+            if (step.category === 'test.step' || step.category === 'hook') {
+                return false;
+            }
+        }
+        return true;
+    }
+    extractAndCleanStep(input) {
+        let expectedResult = null;
+        let data = null;
+        let cleanedString = input;
+        const hasExpectedResult = /QaseExpRes:/.test(input);
+        const hasData = /QaseData:/.test(input);
+        if (hasExpectedResult || hasData) {
+            const regex = /QaseExpRes:\s*:?\s*(.*?)\s*(?=QaseData:|$)QaseData:\s*:?\s*(.*)?/;
+            const match = input.match(regex);
+            if (match) {
+                expectedResult = match[1]?.trim() || null;
+                data = match[2]?.trim() || null;
+                cleanedString = input
+                    .replace(/QaseExpRes:\s*:?\s*.*?(?=QaseData:|$)/, '')
+                    .replace(/QaseData:\s*:?\s*.*/, '')
+                    .trim();
+            }
+        }
+        return { expectedResult, data, cleanedString };
+    }
 }
 exports.PlaywrightQaseReporter = PlaywrightQaseReporter;
-/**
- * @type {Record<TestStatus, TestStatusEnum>}
- */
-PlaywrightQaseReporter.statusMap = {
-    passed: qase_javascript_commons_1.TestStatusEnum.passed,
-    failed: qase_javascript_commons_1.TestStatusEnum.failed,
-    skipped: qase_javascript_commons_1.TestStatusEnum.skipped,
-    timedOut: qase_javascript_commons_1.TestStatusEnum.failed,
-    interrupted: qase_javascript_commons_1.TestStatusEnum.failed,
-};
-/**
- * @type {Map<string, number[]>}
- * @private
- */
-PlaywrightQaseReporter.qaseIds = new Map();

package/docs/usage.md

@@ -0,0 +1,265 @@
+# Qase Syntax
+
+> [**Click here**](../../examples/playwright/test/) to view Example tests for the following syntax.
+
+Here is the complete list of syntax options available for the reporter:
+- [Qase Id](#qase-id)
+- [Qase Title](#qase-title)
+- [Steps](#steps)
+- [Fields](#fields)
+- [Suite](#suite)
+- [Parameters](#parameters)
+- [Comment](#comment)
+- [Attach](#attach)
+- [Ignore](#ignore)
+
+If you do not use any Qase syntax, the reporter uses the title from the `describe` and `test` functions as the Suite and Test case title respectively, when publishing results.
+
+<br>
+
+### Import Statement
+---
+Add the following statement at the beginning of your spec file, before any tests.
+
+```javascript
+import { qase } from 'playwright-qase-reporter';
+```
+<br>
+
+### Example Spec file
+---
+```javascript
+import { qase } from 'playwright-qase-reporter';
+
+describe('Suite title', () => {
+
+  test(qase(1, "This is the test name"), () => {
+    qase.title("This overrides the test name");
+    qase.suite("Suite name");
+    qase.fields({ 'severity': 'high', 'priority': 'medium' });
+    qase.attach({ paths: './tests/examples/attachments/test-file.txt' });
+    qase.comment("A comment for this result");
+    qase.ignore(); // doesn't report his result to Qase.
+    qase.parameters({ Username: "@test" }); 
+    qase.groupParameters({ Username: username, Password: "123" });
+    await test.step('Test step title', async () => // step logic });
+  });
+
+```
+<br>
+
+### Qase ID
+---
+
+Qase IDs can be defined using two different methods. It is best to select one method and consistently use it throughout your tests. The first method is recommended.
+
+Only one Qase Id can be linked to a test. 
+
+**Inline with the `test` Function**: 
+
+```javascript
+test(qase(1, 'A simple test'), () => {
+    ..
+```
+
+**Inside the `test` Body**: 
+
+```javascript
+test('A simple test', () => {
+    qase.id(1);
+    // Test logic here
+});
+```
+
+**In the test's annotations**:
+
+```js
+test('A simple test',
+{
+  annotation: { type: 'QaseID', description: '1' },
+},
+  async () => {
+    // Test logic here
+});
+```
+<br>
+
+### Qase Title
+--- 
+
+The `qase.title()` method is used to set the title of a test case, both when creating a new test case from the result, and when updating the title of an existing test case - *if used with `qase.id()`.*
+
+```javascript
+test("This won't appear in Qase", () => {
+  qase.title("This text will be the title of the test, in Qase");
+  // Test logic here
+});
+```
+
+If you don’t explicitly set a title using this method, the title specified in the `test(..)` function will be used for creating new test cases. However, if this method is defined, it always takes precedence and overrides the title from the `test(..)` function.
+
+<br>
+
+### Steps
+--- 
+
+The reporter uses the title from the `test.step` function as the step title. By providing clear and descriptive step names, you make it easier to understand the test’s flow when reviewing the test case.
+
+Additionally, these steps get their own result in the Qase Test run, offering a well-organized summary of the test flow. This helps quickly identify the cause of any failures.
+
+```javascript
+test('A Test case with steps, updated from code', async () => {
+  await test.step('Initialize the environment', async () => {
+    // Set up test environment
+  });
+  await test.step('Test Core Functionality of the app', async () => {
+    // Exercise core functionality
+  });
+
+  await test.step('Verify Expected Behavior of the app', async () => {
+    // Assert expected behavior
+  });
+});
+```
+
+You also can use the `qase.step()` method to set the expected result and data of the step, which will be used in the Qase report.
+
+```javascript
+test('A Test case with steps, updated from code', async () => {
+  await test.step(qase.step('Initialize the environment'), async () => {
+    // Set up test environment
+  });
+  await test.step(qase.step('Test Core Functionality of the app', 'expected result'), async () => {
+    // Exercise core functionality
+  });
+
+  await test.step(qase.step('Verify Expected Behavior of the app', 'expected result', 'data'), async () => {
+    // Assert expected behavior
+  });
+});
+```
+
+<br>
+
+### Fields
+---
+
+You can define the `description`, `pre-conditions`, `post-conditions`, and fields such as `severity`, `priority`, and `layer` using this method, which enables you to specify and maintain the context of the case directly within your code.
+
+```javascript
+test('Maintain your test meta-data from code', async () => {
+  qase.fields({
+      severity: 'high',
+      priority: 'medium',
+      layer: 'api',
+      precondition: 'add your precondition'
+      postcondition: 'add your postcondition'
+      description: `Code it quick, fix it slow,
+                    Tech debt grows where shortcuts go,
+                    Refactor later? Ha! We know.`
+    })
+    //  test logic here
+});
+```
+
+<br>
+
+
+### Suite 
+---
+
+You can use this method to nest the resulting test cases in a particular suite. There's something to note here – suites, unlike test cases, are not identified uniquely by the Reporter. Therefore, when defining an existing suite - the title of the suite is used for matching.
+
+```js
+test("Test with a defined suite", () => {
+  qase.suite("Suite defined with qase.suite()");
+    /*
+     *  Or, nest multiple levels of suites. 
+     *  `\t` is used for dividing each suite name.
+     */
+     
+test("Test with a nested suite", () => {
+  qase.suite("Application\tAuthentication\tLogin\tEdge_case");
+  //  test logic here
+});
+```
+<br>
+
+### Parameters
+---
+Parameters are a great way to make your tests more dynamic, reusable, and data-driven. By defining parameters in this method, you can ensure only one test case with all the parameters is created in your Qase project, avoiding duplication.
+
+
+```javascript
+const testCases = [
+  { browser: "Chromium", username: "@alice", password: "123" },
+  { browser: "Firefox", username: "@bob", password: "456" },
+  { browser: "Webkit", username: "@charlie", password: "789" },
+];
+
+testCases.forEach(({ browser, username, password,  }) => {
+  test(`Test login with ${browser}`, async () => {
+    qase.title("Verify if page loads on all browsers");
+
+    qase.parameters({ Browser: browser });  // Single parameter
+  // test logic
+
+testCases.forEach(({ username, password }) => {
+  test(`Test login with ${username} using qase.groupParameters`, () => {
+    qase.title("Verify if user is able to login with their username.");
+
+    qase.groupParameters({  // Group parameters
+      Username: username,
+      Password: password,
+    });
+  // test logic
+```
+<br>
+
+### Comment
+---
+In addition to `test.step()`, this method can be used to provide any additional context to your test, it helps maintiain the code by clarifying the expected result of the test.
+
+```js
+test("A test case with qase.comment()", () => {
+    /*
+     * Please note, this comment is added to a Result, not to the Test case.
+     */
+  qase.comment("This comment is added to the result");
+  // test logic here
+});
+```
+<br>
+
+### Attach
+---
+This method can help attach one, or more files to the test's result. You can also add the file's contents directly from code. For example: 
+
+```js
+test('Test result with attachment', async () => {
+
+       // To attach a single file
+    qase.attach({
+      paths: "./tests/examples/attachments/test-file.txt",
+    });
+
+       // Add multiple attachments. 
+    qase.attach({ paths: ['/path/to/file', '/path/to/another/file'] });
+
+
+       // Upload file's contents directly from code.
+    qase.attach({ name: 'attachment.txt', content: 'Hello, world!', contentType: 'text/plain' });
+      // test logic here
+});
+```
+<br>
+
+### Ignore
+---
+If this method is added, the reporter will exclude the test’s result from the report sent to Qase. While the test will still executed by Playwright, its result will not be considered by the reporter.
+
+```js
+test("This test is executed using Playwright; however, it is NOT reported to Qase", () => {
+  qase.ignore();
+//  test logic here
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-qase-reporter",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "description": "Qase TMS Playwright Reporter",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -44,7 +44,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "chalk": "^4.1.2",
-    "qase-javascript-commons": "~2.2.0",
+    "qase-javascript-commons": "~2.2.14",
     "uuid": "^9.0.0"
   },
   "peerDependencies": {