@testrigor/testrigor-cli 2.0.2 → 2.0.4

package/README.md

@@ -57,6 +57,22 @@ Or skip stored credentials entirely and set `TESTRIGOR_API_KEY`, or pass
 23. Authenticate with TestRigor and store credentials (interactive prompt): `testrigor authenticate`
 24. Run with override chrome extensions at runtime (one or more chrome extensions): `test-suite run <test-suite-id> --token <token> --chrome-extension "name=<extension-name> file=<extension-file>" --chrome-extension "name=<extension-name> file=<extension-file>"`
 
+### Test case files
+
+Each file passed with `--test-cases-path` is one test case, and its file name (without extension) becomes the test case name. `.txt` files contain only the steps. `.yaml` files support:
+
+```yaml
+testCaseUuid: 0f32d5b2-84aa-43ae-b8ae-17d4b33f114e # "uuid" is also accepted
+customSteps: |
+  click "Sign in"
+  check that page contains "Welcome"
+labels:
+  - smoke
+datasetName: users
+```
+
+With a UUID, the existing test case is matched by UUID and updated, including its name if the file was renamed. Without one, test cases are matched by name. With `--explicit-mutations`, renaming a file that has no UUID deletes the old test case and creates a new one.
+
 ### Mobile Testing
 
 Run mobile tests on your own local devices (emulators/simulators/real devices) using the same `--localhost` flag. The CLI auto-detects mobile suites and handles everything behind the scenes (mobile server, tunnel, configuration).
@@ -116,7 +132,188 @@ Pull requests to `master` must pass two CircleCI checks before they can be merge
    npm version patch --no-git-tag-version
    ```
 
-   This updates the version in `package.json` and in both root entries of `package-lock.json` (`version` and `packages[""].version`). `--no-git-tag-version` stops npm from creating its own commit and `v*` tag. npm also runs the `version` script (`oclif readme && git add README.md`). That script loads the commands from `dist`, which is why you build first. It only rewrites README sections between oclif's marker comments (`commands`, `usage`, `toc`). This README has none, so it stays unchanged. Don't write those markers literally anywhere in the README, not even in code spans: `oclif readme` also runs on every publish and would insert the command docs there.
+   This updates the version in `package.json` and in both root entries of `package-lock.json` (`version` and `packages[""].version`). `--no-git-tag-version` stops npm from creating its own commit and `v*` tag. npm also runs the `version` script (`oclif readme && git add README.md`). That script loads the commands from `dist`, which is why you build first. It only rewrites README sections between oclif markers such as `<!-- commands -->
+* [`testrigor authenticate`](#testrigor-authenticate)
+* [`testrigor help [COMMAND]`](#testrigor-help-command)
+* [`testrigor test-suite config`](#testrigor-test-suite-config)
+* [`testrigor test-suite run [TESTSUITEID]`](#testrigor-test-suite-run-testsuiteid)
+* [`testrigor test-suite validate-syntax [TESTSUITEID]`](#testrigor-test-suite-validate-syntax-testsuiteid)
+
+## `testrigor authenticate`
+
+Set your testRigor authentication token
+
+```
+USAGE
+  $ testrigor authenticate [--token <value>]
+
+FLAGS
+  --token=<value>  API authentication token to store, instead of prompting for it
+
+DESCRIPTION
+  Set your testRigor authentication token
+
+EXAMPLES
+  $ testrigor authenticate
+
+  Prompts for your API authentication token
+
+  $ testrigor authenticate --token YOUR_TOKEN
+
+  Sets the token without prompting (for CI and scripts)
+
+  Use 'testrigor test-suite config' to set default test suite ID separately
+
+  Config will be stored in ~/.testrigor/testrigor.yml
+```
+
+_See code: [src/commands/authenticate.ts](https://github.com/TestRigor/testrigor-cli/blob/v2.0.4/src/commands/authenticate.ts)_
+
+## `testrigor help [COMMAND]`
+
+Display help for testrigor.
+
+```
+USAGE
+  $ testrigor help [COMMAND...] [-n]
+
+ARGUMENTS
+  [COMMAND...]  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for testrigor.
+```
+
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.3.0/src/commands/help.ts)_
+
+## `testrigor test-suite config`
+
+Configure test suite settings and default test suite ID
+
+```
+USAGE
+  $ testrigor test-suite config [--default <value> | --delete | --show]
+
+FLAGS
+  --default=<value>  Set the default test suite ID
+  --delete           Remove the default test suite ID
+  --show             Show current configuration
+
+DESCRIPTION
+  Configure test suite settings and default test suite ID
+
+EXAMPLES
+  $ testrigor test-suite config --default TEST-SUITE-ID
+
+  $ testrigor test-suite config --show
+
+  $ testrigor test-suite config --delete
+```
+
+_See code: [src/commands/test-suite/config.ts](https://github.com/TestRigor/testrigor-cli/blob/v2.0.4/src/commands/test-suite/config.ts)_
+
+## `testrigor test-suite run [TESTSUITEID]`
+
+Run all tests of a Test Suite
+
+```
+USAGE
+  $ testrigor test-suite run [TESTSUITEID] [--auth-token <value>] [-t <value>] [--min-port <value>] [--max-port
+    <value>] [--verbose] [-w] [--branch <value> --commit <value>] [--localhost] [--url <value>]
+    [--junit-report-save-path <value>] [--variables-path <value>] [--test-cases-path <value>] [--rules-path <value>]
+    [--settings-path <value>] [--local-test-nodes-path <value>] [--test-case-uuid <value>...] [--auto-create-ai-rules]
+    [--explicit-mutations] [--labels <value>...] [--excluded-labels <value>...] [--base-url-web <value>] [--base-url-api
+    <value>] [--chrome-extension <value>... | --file-path <value>] [--xray-execution-key <value>]
+
+ARGUMENTS
+  [TESTSUITEID]  The test suite id (optional if set in config)
+
+FLAGS
+  -w, --async                           Don't wait for the test suite to finish
+      --auto-create-ai-rules            Enable auto create AI based rules
+      --base-url-api=<value>            Base URL for API2 (e.g., https://api2.testrigor.com)
+      --base-url-web=<value>            Base URL for web interface (e.g., https://app.testrigor.com)
+      --branch=<value>                  [env: TR_BRANCH] The branch name
+      --chrome-extension=<value>...     Chrome extension: "name=EXT_NAME file=PATH_TO_CRX"
+      --commit=<value>                  [env: TR_COMMIT] The commit
+      --excluded-labels=<value>...      Not run tests of specific labels
+      --explicit-mutations              In cases where you are always using mutations, such as storing test cases in
+                                        your own repository, and you always send us the set of test cases you have
+                                        through our API you should send "--explicit-mutations"
+      --file-path=<value>               Path to the file stored locally. It will upload the new file to be used. File
+                                        type should be according to the file type accepted for the Test Suite type of
+                                        testing. If the parameter --url is used, this parameter will be ignored.
+      --junit-report-save-path=<value>  JUnit report save path
+      --labels=<value>...               Run tests of specific labels
+      --local-test-nodes-path=<value>   Path to a YAML or JSON file with local test nodes configuration
+      --localhost                       Localhost run (auto-detects web vs mobile)
+      --max-port=<value>                [default: 50000] Max port for tunnel
+      --min-port=<value>                [default: 40000] Min port for tunnel
+      --rules-path=<value>              Rules path
+      --settings-path=<value>           Settings path
+      --test-case-uuid=<value>...       Test case uuid (can be repeated). Requires --url (web) or --file-path (mobile
+                                        app upload).
+      --test-cases-path=<value>         Test cases files
+      --url=<value>                     The url
+      --variables-path=<value>          Variables path
+      --xray-execution-key=<value>      Reuse an existing Xray Cloud Test Execution by key (e.g. XR-123) instead of
+                                        creating a new one. Optional; leave blank to create a new execution.
+
+GLOBAL FLAGS
+  -t, --token=<value>       Suite authentication token
+      --auth-token=<value>  Personal authentication token
+      --verbose             Verbose output
+
+DESCRIPTION
+  Run all tests of a Test Suite
+```
+
+_See code: [src/commands/test-suite/run.ts](https://github.com/TestRigor/testrigor-cli/blob/v2.0.4/src/commands/test-suite/run.ts)_
+
+## `testrigor test-suite validate-syntax [TESTSUITEID]`
+
+Validate step syntax against a test suite's reusable rules, without running the steps
+
+```
+USAGE
+  $ testrigor test-suite validate-syntax [TESTSUITEID] [--auth-token <value>] [-t <value>] [--min-port <value>] [--max-port
+    <value>] [--verbose] [--steps <value> | --test-cases-path <value>] [--base-url-api <value>] [--rules-path <value>]
+    [--explicit-mutations] [--use-suite-parsing-mode]
+
+ARGUMENTS
+  [TESTSUITEID]  The test suite id (optional if set in config)
+
+FLAGS
+  --base-url-api=<value>     Base URL for API2 (e.g., https://api2.testrigor.com)
+  --explicit-mutations       Validate using only the supplied rules instead of merging them with the suite's saved rules
+  --max-port=<value>         [default: 50000] Max port for tunnel
+  --min-port=<value>         [default: 40000] Min port for tunnel
+  --rules-path=<value>       Ad hoc reusable rules to validate against, for rules not yet saved to this suite (same glob
+                             format as `test-suite run --rules-path`)
+  --steps=<value>            Raw step text to validate directly
+  --test-cases-path=<value>  Test case files to validate (same glob format as `test-suite run --test-cases-path`)
+  --use-suite-parsing-mode   Validate with the suite's own parsing mode setting instead of strict parsing
+
+GLOBAL FLAGS
+  -t, --token=<value>       Suite authentication token
+      --auth-token=<value>  Personal authentication token
+      --verbose             Verbose output
+
+DESCRIPTION
+  Validate step syntax against a test suite's reusable rules, without running the steps
+
+EXAMPLES
+  $ testrigor test-suite validate-syntax <test-suite-id> --steps "click \"Login\""
+
+  $ testrigor test-suite validate-syntax <test-suite-id> --test-cases-path "test_cases/**/*.{yaml,txt}"
+```
+
+_See code: [src/commands/test-suite/validate-syntax.ts](https://github.com/TestRigor/testrigor-cli/blob/v2.0.4/src/commands/test-suite/validate-syntax.ts)_
+<!-- commandsstop -->`, so this README currently stays unchanged.
+
 3. Check that the diff only touches the version fields, then build and test from the lockfile:
 
    ```

package/dist/commands/test-suite/run.js

@@ -142,15 +142,20 @@ class Run extends command_base_1.CommandBase {
             }
         }
         if (testCasesPath) {
+            let testCases = [];
             try {
-                const testCases = await (0, parser_1.parseTestCases)(testCasesPath);
-                if (testCases.length) {
-                    context.configuration.baselineMutations = testCases;
-                }
+                testCases = await (0, parser_1.parseTestCases)(testCasesPath);
             }
             catch {
                 core_1.ux.error("--test-cases-path must be a valid JSON path");
             }
+            const duplicateUuids = (0, parser_1.findDuplicateUuids)(testCases);
+            if (duplicateUuids.length) {
+                core_1.ux.error(`--test-cases-path has test cases sharing a UUID: ${duplicateUuids.join("; ")}`);
+            }
+            if (testCases.length) {
+                context.configuration.baselineMutations = testCases;
+            }
         }
         if (rulesPath) {
             try {
@@ -218,9 +223,19 @@ class Run extends command_base_1.CommandBase {
             const suiteType = await this.fetchSuiteType(testSuiteId, token);
             context.isMobile = this.isMobileSuiteType(suiteType);
         }
+        const isLocalMobileRun = (flags.localhost || !!localTestNodesPath) && context.isMobile;
+        // A local mobile run has one Appium server and device behind it. Parallel
+        // runners would open sessions on it at once and kill each other's, so the
+        // run executes its test cases one by one (an override for this run only).
+        if (isLocalMobileRun) {
+            context.configuration.settings = {
+                ...context.configuration.settings,
+                useParallelCombinator: false,
+            };
+        }
         const tasks = [
             {
-                enabled: () => (flags.localhost || !!localTestNodesPath) && context.isMobile,
+                enabled: () => isLocalMobileRun,
                 task: (ctx, task) => {
                     task.title = "Starting mobile server";
                     // A driver that fails to install is tolerated (xcuitest is useless on

package/dist/commands/test-suite/validate-syntax.d.ts

@@ -9,6 +9,7 @@ export default class ValidateSyntax extends CommandBase<typeof ValidateSyntax> {
         "base-url-api": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         "rules-path": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         "explicit-mutations": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "use-suite-parsing-mode": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static args: {
         testSuiteId: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;

package/dist/commands/test-suite/validate-syntax.js

@@ -24,7 +24,8 @@ class ValidateSyntax extends command_base_1.CommandBase {
             ? await (0, parser_1.parseRules)(flags["rules-path"])
             : [];
         const explicitMutations = flags["explicit-mutations"];
-        await this.reportValidationResults(testSuiteId, token, casesToValidate, rules, explicitMutations);
+        const useSuiteParsingMode = flags["use-suite-parsing-mode"];
+        await this.reportValidationResults(testSuiteId, token, casesToValidate, rules, explicitMutations, useSuiteParsingMode);
     }
     async resolveStepsToValidate(steps, testCasesPath) {
         if (steps) {
@@ -36,10 +37,10 @@ class ValidateSyntax extends command_base_1.CommandBase {
             customSteps: testCase.customSteps,
         }));
     }
-    async reportValidationResults(testSuiteId, token, cases, rules, explicitMutations) {
+    async reportValidationResults(testSuiteId, token, cases, rules, explicitMutations, useSuiteParsingMode) {
         let hasAnyInvalidTestCases = false;
         for (const testCase of cases) {
-            const response = await this.callValidateSyntax(testSuiteId, testCase.customSteps, token, rules, explicitMutations);
+            const response = await this.callValidateSyntax(testSuiteId, testCase.customSteps, token, rules, explicitMutations, useSuiteParsingMode);
             if (response.data && response.data.length > 0) {
                 const parserErrors = response.data;
                 core_2.ux.stdout(`${testCase.description}: invalid`);
@@ -58,7 +59,7 @@ class ValidateSyntax extends command_base_1.CommandBase {
         core_2.ux.stdout("All provided steps are valid.");
         this.exit(0);
     }
-    async callValidateSyntax(testSuiteId, steps, token, rules, explicitMutations) {
+    async callValidateSyntax(testSuiteId, steps, token, rules, explicitMutations, useSuiteParsingMode) {
         const body = { steps };
         if (rules.length > 0) {
             body.rules = rules;
@@ -66,6 +67,9 @@ class ValidateSyntax extends command_base_1.CommandBase {
         if (explicitMutations) {
             body.explicitMutations = explicitMutations;
         }
+        if (useSuiteParsingMode) {
+            body.useSuiteParsingMode = useSuiteParsingMode;
+        }
         const response = await fetch(`${this.TESTRIGOR_API2_URL}/apps/${testSuiteId}/validate-syntax`, {
             method: "POST",
             body: JSON.stringify(body),
@@ -105,6 +109,10 @@ ValidateSyntax.flags = {
         description: "Validate using only the supplied rules instead of merging them with the suite's saved rules",
         default: false,
     }),
+    "use-suite-parsing-mode": core_1.Flags.boolean({
+        description: "Validate with the suite's own parsing mode setting instead of strict parsing",
+        default: false,
+    }),
 };
 ValidateSyntax.args = {
     testSuiteId: core_1.Args.string({

package/dist/util/parser.d.ts

@@ -1,4 +1,5 @@
 import { Rule, TestCase } from "../types";
 export declare function parseTestCases(path: string): Promise<TestCase[]>;
+export declare function findDuplicateUuids(testCases: TestCase[]): string[];
 export declare function parseRules(path: string): Promise<Rule[]>;
 export declare function parseSettings(path: string): Promise<object>;

package/dist/util/parser.js

@@ -1,13 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseTestCases = parseTestCases;
+exports.findDuplicateUuids = findDuplicateUuids;
 exports.parseRules = parseRules;
 exports.parseSettings = parseSettings;
 const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
 const fs_1 = tslib_1.__importDefault(require("@supercharge/fs"));
 const glob_1 = require("glob");
 const yaml_1 = require("yaml");
 const utils_1 = require("./utils");
+function normalizeUuid(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const uuid = String(value).trim();
+    return uuid || undefined;
+}
 async function parseTestCases(path) {
     const result = [];
     const files = await (0, glob_1.glob)(path, { withFileTypes: true });
@@ -20,8 +29,18 @@ async function parseTestCases(path) {
                     customSteps: json.customSteps,
                     description: (0, utils_1.removeExtension)(file.name),
                 };
-                if (json.testCaseUuid) {
-                    testCase.testCaseUuid = json.testCaseUuid;
+                // "uuid" is the key used by exported test cases. Dropping it makes
+                // the backend match by description instead, which with explicit
+                // mutations deletes and recreates the test (TR-17226).
+                const testCaseUuid = normalizeUuid(json.testCaseUuid ?? json.uuid);
+                if (testCaseUuid) {
+                    testCase.testCaseUuid = testCaseUuid;
+                }
+                const aliasUuid = normalizeUuid(json.uuid);
+                if (json.testCaseUuid != null &&
+                    aliasUuid &&
+                    aliasUuid !== testCaseUuid) {
+                    core_1.ux.warn(`${file.name} has both "testCaseUuid" and "uuid"; using "testCaseUuid"`);
                 }
                 if (json.labels) {
                     testCase.labels = json.labels;
@@ -42,6 +61,19 @@ async function parseTestCases(path) {
     }
     return result;
 }
+function findDuplicateUuids(testCases) {
+    const descriptionsByUuid = new Map();
+    for (const testCase of testCases) {
+        if (testCase.testCaseUuid) {
+            const descriptions = descriptionsByUuid.get(testCase.testCaseUuid) ?? [];
+            descriptions.push(testCase.description);
+            descriptionsByUuid.set(testCase.testCaseUuid, descriptions);
+        }
+    }
+    return [...descriptionsByUuid]
+        .filter(([, descriptions]) => descriptions.length > 1)
+        .map(([uuid, descriptions]) => `${uuid} (${descriptions.join(", ")})`);
+}
 async function parseRules(path) {
     const result = [];
     const files = await (0, glob_1.glob)(path, { withFileTypes: true });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@testrigor/testrigor-cli",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@testrigor/testrigor-cli",
-      "version": "2.0.2",
+      "version": "2.0.4",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/oclif.manifest.json

@@ -431,6 +431,12 @@
           "name": "explicit-mutations",
           "allowNo": false,
           "type": "boolean"
+        },
+        "use-suite-parsing-mode": {
+          "description": "Validate with the suite's own parsing mode setting instead of strict parsing",
+          "name": "use-suite-parsing-mode",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -450,5 +456,5 @@
       ]
     }
   },
-  "version": "2.0.2"
+  "version": "2.0.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testrigor/testrigor-cli",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "TestRigor Command Line",
   "author": "Ivo Parun Rua @parunruaivo",
   "bin": {