Command Line

Ivo Parun Rua

This is a command line tool for testRigor. It allows you to run TestRigor tests from the command line.

Installation

Install Node.js (version 18 or higher)
Open your terminal/command prompt, then paste the following command and press Enter:
```
npm install -g testrigor-cli
```

Test Suite Credentials

The the test suite ID is the unique identifier of your suite, and it is found in the suite’s URL.
For example, if your suite’s URL is https://app.testrigor.com/test-suites/1234567890/ then 1234567890 is the test suite ID number.

The authentication token is the user’s unique personal token required to access CI/CD functionalities with testRigor.
At the CI/CD Integration page, you can find the authentication token under the format

auth-token: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

The sequence of characters separated by hyphens is the token.

Now that we have both the test suite ID and the authentication token, we can use them to run the test suite in the command line.

Usage

The following command calls testRigor to perform a full run of the suite using the user’s personal authentication token, which is found in the testRigor suite’s CI/CD Integration page.

testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN [OPTIONS]

Let’s break down each component of this command:

Command Structure

testrigor – The executable name
test-suite run – The subcommand that tells testRigor to execute a test suite
TEST_SUITE_ID – Replace this with your actual test suite ID found in your testRigor suite URL.
--token – Required flag for authentication.
SUITE_CI_TOKEN – Replace this with your personal API token from testRigor CI/CD Integration page.
[OPTIONS] – Optional flags and parameters from the table below can be added here

When running the command, you can optionally replace the field [OPTIONS] with the options from the table below. If you do not want to use any options, just run the command without the [OPTIONS] portion.

Options

The following options can be added at the end of the command to customize the test run:

Option	Description	Precondition
`--verbose`	Enable detailed output during command execution. This is useful for debugging and troubleshooting.
`--async`	Start test execution and exit the command line without waiting for results.
`--url TARGET_URL`	Override the default test suite URL with a custom URL	Replace `TARGET_URL` with the new url to run tests on.
`--branch BRANCH_NAME`	Triggers a run on the specified branch. This run will not affect the baseline state of the test suite.	Requires `--commit`. Replace `BRANCH_NAME` with the actual name of the branch.
`--commit COMMIT_HASH`	Specify the Git commit hash for test execution	Requires `--branch`. Replace `COMMIT_HASH` with the actual hash of the commit.
`--localhost` `--url TARGET_URL`	Enable localhost tunneling for local application testing on the specified URL.	Requires `--url`. Replace `TARGET_URL` with the actual URL of the local application.
`--file-path file.{apk,ipa,app.zip}`	Upload local file for mobile testing (ignored if URL provided)	Replace `file.{apk,ipa,zip}` with the actual path to the mobile file.
`--variables-path variables.json`	Load test variables from JSON file path. Replace `VARIABLES.json` with the actual path to the JSON file.
`--test-cases-path testcases/*/.{yaml,yml,txt}`	Load test cases from specified files using glob pattern. Important: When referencing multiple files in a directory, you must use glob syntax. For a single file, use the direct file path.	Replace `testcases/*/.{yaml,yml,txt}` with the actual glob pattern for your test cases. Examples: `testcases/*/.yml` (all YML files in the directory) or `testcases/*/.txt` (all TXT files in the directory).
`--rules-path rules/*/.yaml`	Load custom rules from specified files using glob pattern. Important: When referencing multiple files in a directory, you must use glob syntax. For a single file, use the direct file path.	Replace `rules/*/.yaml` with the actual glob pattern for your rules. Example: `rules/*/.yaml` (all YAML files in subdirectories).
`--settings-path settings.{yaml,json}`	Load test suite settings from YAML or JSON file
`--test-case-uuid TEST_CASE_UUID`	Run a single specific test case by providing it’s test case UUID. Replace `TEST_CASE_UUID` with the actual UUID of the test case, found at the test cases page under each test case execution.	Requires `--url`
`--auto-create-ai-rules`	Enable automatic AI-based rule generation during test execution
`--explicit-mutations`	Allow this run to update and merge the test suite with data from local files.	Requires `--test-cases-path`
`--labels`	Filter tests to run only those with specified labels	Comma-separated values
`--excluded-labels`	Exclude tests with specified labels from execution	Comma-separated values
`--junit-report-save-path`	Save JUnit XML report to specified file path	Works only in sync mode

Understanding File Path Patterns

Important: When working with file paths that reference multiple files, you must use glob patterns. Here’s when and how to use them:

Single File vs Multiple Files

Single file: Use the direct file path (e.g., settings.yaml, variables.json)
Multiple files: Use glob patterns with wildcards (e.g., test_cases/**/*.txt, rules/**/*.yaml)

Note: If you specify just a directory name without glob patterns (e.g., test_cases), the command may not find your files. Always use glob patterns when you want to include multiple files from a directory.

Now let’s see these options in action with practical examples:

Examples

Basic Usage

Basic: This triggers a full run of the test suite.

testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN

With new URL: This triggers a full run of the test suite on a new URL, overriding the default URL from settings.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --url TARGET_URL
```
Don’t wait for the test suite run to finish: This will start the test suite run and exit the command line without waiting for results.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --async
```

For local development scenarios:

Local Development & Testing

With file upload: This triggers a full run of the test suite overriding the default mobile file.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --file-path PATH_TO_FILE
```
Localhost mode: This triggers a full run of the test suite on a local URL where the command is executed.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --localhost --url TARGET_URL
```
Run single test case: This triggers a single run of the test case which the UUID is provided. The UUID is found at the test cases page under each test case execution.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --test-case-uuid TEST_CASE_UUID --url TARGET_URL
```

When working with version control:

Version Control Integration

With branch: This triggers a full run of the test suite on a new branch, not affecting the baseline state of the test suite.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --branch BRANCH_NAME --commit COMMIT_HASH
```

To manage test data and configurations:

File & Data Management

With variables: This triggers a full run of the test suite with variables loaded from a JSON file.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --variables-path file.json
```
With test cases: This triggers a full run of the test suite with test cases loaded from a specified directory.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --test-cases-path test_cases/**/*.{yaml,txt}
```
With rules: This triggers a full run of the test suite with rules loaded from a specified directory.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --rules-path rules/**/*.yaml
```
With settings (can be JSON or YAML): This triggers a full run of the test suite with settings loaded from a specified file.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --settings-path settings.yaml
```

Run with explicit mutations enabled: This will update and merge the test suite with data from local files.

testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --test-cases-path test_cases/**/*.{yaml,txt} --explicit-mutations

For more advanced use cases:

Advanced Features

Run with auto create AI rules enabled: This triggers a new run with AI-based rules creation when a test case step is not recognized.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --test-cases-path test_cases/**/*.{yaml,txt} --auto-create-ai-rules
```

With comma-separated labels: This runs only the tests with the specified labels.

testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --labels LABEL_LIST

Excluding comma-separated labels: This runs all tests except those with the specified labels.

testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --excluded-labels EXCLUDED_LABEL_LIST

Finally, for reporting and CI/CD integration:

Reporting & CI/CD

Save JUnit report (works only in sync mode): This will save a JUnit XML report to the specified file path.
```
testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --junit-report-save-path ./report.xml
```

With all options: This triggers a full run of the test suite with all options enabled.

testrigor test-suite run TEST_SUITE_ID --token SUITE_CI_TOKEN --localhost --url TARGET_URL --branch BRANCH_NAME --commit COMMIT_HASH --variables-path file.json --test-cases-path test_cases/**/*.{yaml,txt} --rules-path rules/**/*.{yaml,txt} --auto-create-ai-rules --explicit-mutations