@testiny/cli/README.md

A command-line client for Testiny

# Testiny CLI

Use the Testiny CLI to import test cases and test runs into your Testiny Organization.

- Test cases can be imported from CSV files (see example below)
- Test runs can be imported from CSV, JUnit and Playwright JSON files & many more formats

## Quickstart
  
- Create an API key with write permissions on the project you want to import to
- Set the API key as the TESTINY_API_KEY environment variable or pass with ``--apikey``
- Running just  ``testiny-importer testcase``, ``testiny-importer testrun`` or ``testiny-importer automation`` command prompts for required options

## General options

```plain
Usage: testiny-importer [options] [command]

Options:
  --app <url>                    App endpoint to use
  -P, --project <nameOrKey>      Target project id or key
  -y, --confirm                  Do not prompt for confirmation before starting import
  -q, --quiet                    Do not prompt for optional settings
  --disable-custom-fields        Disable custom field import. Will fail if required custom fields
                                 with no defaults are enabled
  --enable-custom-fields         Enable custom field import. Will fail if required custom fields
                                 with no defaults are enabled
  --disable-tc-keys              Disable test case import key hints (If enabled use #1234 or
                                 TC-1234 in title for referencing test cases)
  --disable-nested-folders       Disable nesting of imported folders (flat mode), applies to CSV
                                 files only
  --enable-nested-folders        Enable nesting of imported folders (flat mode), applies to CSV
                                 files only
  --folder-separator <token>     Token for folder name separation (default empty = automatic)
  --markdown                     Enable Markdown conversion
  --skip-invalid                 Skip invalid test cases (default: false)
  --duplicates <duplicate mode>  Controls how duplicates are detected (choices: "off", "title",
                                 "folder_title", default: "folder_title")
  --apikey <apiKey>              The API key to use. Not recommended - use the environment variable
                                 TESTINY_API_KEY or TESTINY_IMPORT_API_KEY instead
  -h, --help                     display help for command

Commands:
  testcase [options]             Import test cases (with folders)
  testrun [options]              Import test case results as a testrun
  automation [options]           Import automated test run results, including test cases and
                                 environment data
  licenses                       Show included package licenses
  help [command]                 display help for command

```

## Importing manual test cases

```plain
Usage: testiny-importer testcase [options]

Import manual test cases (with folders)

Options:
  --csv <file>                     Import this CSV file
  --csv-encoding <encoding>        CSV file encoding (default: "utf8")
  --trl <file>                     Import TestRail XML export
  --trl-api <server url>           Import from TestRail API
  --trl-user <user name>           Username/email for TestRail API
  --trl-export-users <file>        Export TestRail users to CSV file
  --trl-tc-limit <count>           Limits the number of test cases fetched
  --trl-rate-limit <rps>           Limits the number of requests to the TestRail api (default 160, zero for no limit)
  --steps <step mode>              Controls how steps are imported (choices: "auto", "off", "rows", "row_blocks", "newlines",
                                   "numbered", "numbered_bracket", "asterisk")
  --attachments <attachment mode>  Controls how test case attachments are imported (choices: "off", "inline", "all")
  --work-items                     Import work items (e.g. Jira issues) when importing from TestRail API
  --integration <name or id>       Name or Id of the integration to use for workitem import
  -h, --help                       display help for command

```

## Importing manual test runs

```plain
Usage: testiny-importer testrun [options]

Import manual test case results as a testrun

Options:
  --csv <file>                             Import this CSV file
  --csv-encoding <encoding>                CSV file encoding (default: "utf8")
  --junit <file>                           Import this JUnit XML file
  --playwright <file>                      Import this Playwright JSON file
  --name <test run name>                   Name of the test run (use %date, %host and %source as placeholders)
  --update                                 Allow run with given name to be updated, otherwise creates a new run with that name (default: false)
  --close                                  Close the testrun after a successful import (default: false)
  --folder <folder name>                   Override folder name for all created test cases
  --testplan <nameOrKey>                   Target test plan id or title
  --junit-ignore-classname                 JUnit: do not include 'classname' attribute in test case title (default: false)
  --junit-classname-as-folder              JUnit: The 'classname' attribute is used for folder names and not the test case title (default: false)
  --junit-strip-classname-prefix <prefix>  JUnit: Remove the specified prefix string from classnames before processing
  --testcases <tc mode>                    Controls how test cases are created if no existing TC is found (choices: "ignore", "fail", "create", default: "create")
  -h, --help                               display help for command

```

## Importing automated test runs/results

```plain
Usage: testiny-importer automation [options]

Import automated test run results, including test cases and environment data

Options/Subcommands:
  --show-env [env]                             Show the field values for the specified (or autodetected) environment
  --list-envs                                  List names of available environments and exit
  --complete-runs                              Mark open runs matching the current environment's run field values (e.g. pipeline id) as 'complete'
  --codeceptjs                                 Import CodeceptJS Mochawesome JSON report file
  --cypress                                    Import Cypress Mochawesome JSON report file
  --junit                                      Import JUnit-compatible file
  --mochawesome                                Import Mochawesome JSON report file
  --nunit                                      Import NUnit-compatible file
  --playwright                                 Import Playwright JSON report file
  --rxlog                                      Ranorex compressed report file
  --testng                                     Import TestNG report XML file
  --vitest                                     Import Vitest json report file
  --vstest                                     Import VSTest trx test results XML file
  --xunit                                      Import XUnit-compatible file
  --no-attachments                             Disables importing of attachments
  --attachment-path <path>                     Base directory for relative attachment file paths, defaults to input file directory
  --source <source>                            The name of the Testiny automation source for import (will be created if it does not exist)
  --run-fields <runFields>                     A comma-separated list of field names to use for uniquely identifying test runs. Defaults to automatic detection from the CI environment
  --run-title-pattern <pattern>                A pattern for creating test run titles out of field values, use %{field_name} as placeholders
  --environment <envName>                      The name of the CI environment, overrides automatic detection (default: "auto")
  --field-values <fieldValues>                 A list of fixed field values to add to every result: field1=value1,field2=value2
  --incomplete                                 Does not mark test runs as complete - set this flag if more results will be added later (e.g. another job)
  --ignore-errors                              Ignore errors and only log warnings instead
  --config <opts.json>                         Read options from JSON file (command line arguments override these)
  --junit-ignore-classname                     JUnit: do not include 'classname' attribute in test case title (default: false)
  --junit-classname-as-folder <single|nested>  JUnit: The 'classname' attribute is used for one 'single' folder name or 'nested' folder names (and not the test case title)
  --junit-strip-classname-prefix <prefix>      JUnit: Remove the specified prefix string from classnames before processing
  --junit-duration-unit <format>               JUnit: specify the unit of time durations, defaults to auto-detect (choices: "sec", "ms")
  -h, --help                                   display help for command

```

## Example files

CSV Example for importing test cases

```csv
folder,title,precondition,steps,expected_result
"Folder Name", "Test case title", "Precondition text, can be empty", "Steps text (depends on step mode setting)", "Expected result, can be empty"
"Folder Name > Subfolder Name", "Another test case title", "", "Folders can be nested by using the folder separator token", ""
```

## Bundled licenses

For licenses of bundled dependencies, please see LICENSE.txt in the package directory