@testrigor/testrigor-cli 1.0.0 → 2.0.0

package/README.md

@@ -4,12 +4,35 @@ This is a command line tool for TestRigor. It allows you to run TestRigor tests
 
 ### Installation
 
-1. Install [Node.js](https://nodejs.org/en/download/) (version 18 or higher)
-2. Install TestRigor CLI: `npm install -g testrigor-cli`
+1. Install [Node.js](https://nodejs.org/en/download/) (version 20.19+, 22.12+ or 24+)
+2. Install TestRigor CLI: `npm install -g @testrigor/testrigor-cli`
+3. Check it: `testrigor --version`
+
+> The unscoped `testrigor-cli` package on npm is an old, unmaintained build.
+> Install the scoped `@testrigor/testrigor-cli` package shown above; if you
+> installed the unscoped one, run `npm uninstall -g testrigor-cli` first.
+
+### Authentication
+
+Store your token once, interactively:
+
+```
+testrigor authenticate
+```
+
+For CI or any non-interactive shell, pass it in instead of being prompted:
+
+```
+testrigor authenticate --token YOUR_TOKEN
+echo YOUR_TOKEN | testrigor authenticate
+```
+
+Or skip stored credentials entirely and set `TESTRIGOR_API_KEY`, or pass
+`--token` to each command.
 
 ### Examples
 
-1. Basic  `testrigor test-suite run <test-suite-id> --token <token>`
+1. Basic `testrigor test-suite run <test-suite-id> --token <token>`
 2. With new URL `testrigor test-suite run <test-suite-id> --token <token> --url <url>`
 3. With file upload `testrigor test-suite run <test-suite-id> --token <token> --file-path <path-to-file>`
 4. With branch `testrigor test-suite run <test-suite-id> --token <token> --branch <branch> --commit <commit>`
@@ -47,6 +70,7 @@ testrigor test-suite run <test-suite-id> --token <token> --localhost --local-tes
 ```
 
 The CLI will:
+
 - Detect it's a mobile suite
 - Start the mobile server (Appium) automatically
 - Open a tunnel to TestRigor cloud
@@ -73,3 +97,206 @@ overrideTestNodes: true
 ```
 
 This overrides the device config stored in the test suite and forces mobile mode (no need for `--localhost`).
+
+### Releasing a new version
+
+Every push to `master` runs the CircleCI `publish` workflow. It builds the tarballs, then publishes the package to npm under the `latest` tag. npm refuses to republish an existing version, so a change is only released when it bumps the version.
+
+1. Pick the [semver](https://semver.org) bump: `patch` for fixes, `minor` for new flags or commands, `major` for breaking changes.
+2. Bump the version with npm (don't edit `package.json` by hand):
+
+   ```
+   npm run build
+   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 markers such as `<!-- commands -->
+* [`testrigor authenticate`](#testrigor-authenticate)
+* [`testrigor help [COMMANDS]`](#testrigor-help-commands)
+* [`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.0/src/commands/authenticate.ts)_
+
+## `testrigor help [COMMANDS]`
+
+Display help for testrigor.
+
+```
+USAGE
+  $ testrigor help [COMMANDS...] [-n]
+
+ARGUMENTS
+  [COMMANDS...]  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/v5.2.20/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.0/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.0/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]
+
+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`)
+
+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.0/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:
+
+   ```
+   git diff package.json package-lock.json
+   npm ci && npm run build && npm test
+   ```
+
+4. Commit (e.g. `Updating to version 1.0.1 #TR-XXXX`), open a PR and merge it to `master`.
+
+If the version was edited by hand anyway, run `npm install --package-lock-only` to bring `package-lock.json` back in sync. CI installs with `npm ci`, which fails when `package.json` and `package-lock.json` don't match, so commit the lockfile along with any dependency change.

package/dist/commands/authenticate.d.ts

@@ -2,5 +2,19 @@ import { Command } from "@oclif/core";
 export default class Authenticate extends Command {
     static description: string;
     static examples: string[];
+    static flags: {
+        token: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
     run(): Promise<void>;
+    /**
+     * Where the token comes from, in order: the --token flag, an interactive
+     * hidden prompt, or piped stdin.
+     *
+     * The hidden prompt is only usable on a TTY. Without one, @oclif/core falls
+     * back to `sh -c 'read -s ...'`, which fails on any system where /bin/sh is
+     * dash (the Debian and Ubuntu default) with "read: Illegal option -s" and
+     * then silently skips the setup.
+     */
+    private resolveToken;
+    private readStdin;
 }

package/dist/commands/authenticate.js

@@ -3,25 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const core_2 = require("@oclif/core");
 const config_1 = require("../util/config");
+// Time to wait for a token on a piped stdin before giving up. Stdin that is
+// neither a TTY nor a closed/redirected stream would otherwise hang forever.
+const STDIN_TIMEOUT_MS = 5000;
 class Authenticate extends core_2.Command {
     async run() {
+        const { flags } = await this.parse(Authenticate);
+        // readConfig reports parse problems itself and falls back to an empty
+        // config, so it needs no wrapping here.
+        const config = await (0, config_1.readConfig)();
+        // Resolved outside the try below so that "no terminal to prompt on" is
+        // reported as itself, not as a failure to save the configuration.
+        const token = await this.resolveToken(flags.token, !!config.authToken);
         try {
-            // Load existing config (readConfig handles parse errors gracefully)
-            const config = await (0, config_1.readConfig)();
-            // Handle authentication token
-            let tokenPromptText;
-            if (config.authToken) {
-                tokenPromptText =
-                    "Enter your testRigor API token (press enter to remove)";
-            }
-            else {
-                tokenPromptText =
-                    "Enter your testRigor API token (press enter to skip)";
-            }
-            const token = await core_1.ux.prompt(tokenPromptText, {
-                type: "hide",
-                required: false,
-            });
             if (!token || token.trim() === "") {
                 if (config.authToken) {
                     delete config.authToken;
@@ -31,29 +25,96 @@ class Authenticate extends core_2.Command {
                 else {
                     core_1.ux.info("Authentication token setup skipped");
                 }
+                return;
+            }
+            config.authToken = token.trim();
+            await (0, config_1.writeConfig)(config);
+            core_1.ux.info("Authentication token successfully saved");
+            if (config.defaultTestSuiteId) {
+                core_1.ux.info("You can now use 'testrigor run' to run your default test suite");
             }
             else {
-                config.authToken = token.trim();
-                await (0, config_1.writeConfig)(config);
-                core_1.ux.info("Authentication token successfully saved");
-                if (config.defaultTestSuiteId) {
-                    core_1.ux.info("You can now use 'testrigor run' to run your default test suite");
-                }
-                else {
-                    core_1.ux.info("Use 'testrigor test-suite config --default TEST_SUITE_ID' to set your default test suite ID, then use 'testrigor run'");
-                }
+                core_1.ux.info("Use 'testrigor test-suite config --default TEST_SUITE_ID' to set your default test suite ID, then use 'testrigor run'");
             }
         }
         catch (error) {
             core_1.ux.error(`Failed to save configuration: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Where the token comes from, in order: the --token flag, an interactive
+     * hidden prompt, or piped stdin.
+     *
+     * The hidden prompt is only usable on a TTY. Without one, @oclif/core falls
+     * back to `sh -c 'read -s ...'`, which fails on any system where /bin/sh is
+     * dash (the Debian and Ubuntu default) with "read: Illegal option -s" and
+     * then silently skips the setup.
+     */
+    async resolveToken(flagToken, hasExistingToken) {
+        if (flagToken !== undefined) {
+            return flagToken;
+        }
+        if (process.stdin.isTTY) {
+            return core_1.ux.prompt(hasExistingToken
+                ? "Enter your testRigor API token (press enter to remove)"
+                : "Enter your testRigor API token (press enter to skip)", { type: "hide", required: false });
+        }
+        const piped = await this.readStdin();
+        if (piped) {
+            return piped;
+        }
+        this.error("No interactive terminal available to prompt for a token.\n" +
+            "Provide it another way:\n" +
+            "  testrigor authenticate --token YOUR_TOKEN\n" +
+            "  echo YOUR_TOKEN | testrigor authenticate\n" +
+            "Or skip this command and set the TESTRIGOR_API_KEY environment variable instead.");
+    }
+    readStdin() {
+        return new Promise((resolve) => {
+            let data = "";
+            // resolve() past the first call is a no-op, so no "settled" guard is
+            // needed for whichever of the timeout or the stream gets there first.
+            const cleanup = () => {
+                process.stdin.removeAllListeners("data");
+                process.stdin.pause();
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve("");
+            }, STDIN_TIMEOUT_MS);
+            const finish = () => {
+                clearTimeout(timer);
+                cleanup();
+                resolve(data.trim());
+            };
+            process.stdin.setEncoding("utf8");
+            process.stdin.on("data", (chunk) => {
+                data += chunk;
+                // A token is a single line; stop as soon as one arrives.
+                const newlineIndex = data.indexOf("\n");
+                if (newlineIndex !== -1) {
+                    data = data.slice(0, newlineIndex);
+                    finish();
+                }
+            });
+            process.stdin.once("end", finish);
+            process.stdin.once("error", finish);
+            process.stdin.resume();
+        });
+    }
 }
-exports.default = Authenticate;
 Authenticate.description = "Set your testRigor authentication token";
 Authenticate.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",
 ];
+Authenticate.flags = {
+    token: core_2.Flags.string({
+        description: "API authentication token to store, instead of prompting for it",
+    }),
+};
+exports.default = Authenticate;

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

@@ -74,7 +74,6 @@ class Config extends core_1.Command {
         }
     }
 }
-exports.default = Config;
 Config.description = "Configure test suite settings and default test suite ID";
 Config.examples = [
     "testrigor test-suite config --default TEST-SUITE-ID",
@@ -95,3 +94,4 @@ Config.flags = {
         exclusive: getExclusiveFlags("show"),
     }),
 };
+exports.default = Config;