Merge pull request #2650 from saucelabs/DEVX-2749-part2

docs: Fix incorrect and outdated saucectl cli content

Author: tianfeng92

docs/api-testing/integrations/apitesting-saucectl-integration.md

@@ -26,12 +26,12 @@ To utilize `saucectl` functionalities, you'll need to generate a webhook for you
 To generate a webhook:
 
 1. Log in to Sauce Labs, then click **API Testing**.
-1. Navigate to your Project and select the **WebHooks** tab.<br/>
+2. Navigate to your Project and select the **WebHooks** tab.<br/>
    <img src={useBaseUrl('img/api-testing/webhook_tab.png')} alt="webhook screenshot" width="200"/>
-1. Select **Create Hook**.<br/><img src={useBaseUrl('img/api-testing/createHook.png')} alt="Create New WebHook" width="300"/>
-1. Enter a **Hook Name** for your webhook (**Description** is optional), then click **Save**.<br/>
+3. Select **Create Hook**.<br/><img src={useBaseUrl('img/api-testing/createHook.png')} alt="Create New WebHook" width="300"/>
+4. Enter a **Hook Name** for your webhook (**Description** is optional), then click **Save**.<br/>
    <img src={useBaseUrl('img/api-testing/sampleHook.png')} alt="sample webhook details" width="300" />
-1. The generated **Hook URL** will then appear.
+5. The generated **Hook URL** will then appear.
 
 ### Step 2: Install `saucectl`
 

docs/dev/cli/saucectl/run.md

@@ -88,25 +88,70 @@ Execute tests according to the environment, framework, and test suite specificat
      <td>Usage information for the <code>run</code> command.</td>
     </tr>
     <tr>
-     <td><span className="t-cli"><a href="#--help">--live-logs</a></span></td>
+     <td><span className="t-cli"><a href="#--launch-order">--launch-order</a></span></td>
+     <td></td>
+     <td>Modify the execution order of suites.</td>
+    </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--live-logs">--live-logs</a></span></td>
      <td></td>
      <td>Tail the live log output from a running Sauce Orchestrate container.</td>
     </tr>
     <tr>
-     <td><span className="t-cli"><a href="#--no-color">--no-color</a></span></td>
+     <td><span className="t-cli"><a href="#--no-auto-tagging">--no-auto-tagging</a></span></td>
      <td></td>
-     <td>Disable colored console output.</td>
+     <td>Disable the automatic tagging of jobs with metadata, such as CI or Git information.</td>
     </tr>
+    <tr>
+      <td><span className="t-cli"><a href="#--no-color">--no-color</a></span></td>
+      <td></td>
+      <td>Disable colored console output.</td>
+     </tr>
     <tr>
      <td><span className="t-cli"><a href="#--region">--region</a></span></td>
      <td><span className="t-cli">-r</span></td>
      <td>Sauce Labs target data center.</td>
     </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--reportersjsonenabled">--reporters.json.enabled</a></span></td>
+     <td></td>
+     <td>Toggles saucectl's JSON test result reporting on/off.</td>
+    </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--reportersjsonfilename">--reporters.json.filename</a></span></td>
+     <td></td>
+     <td>Specifies the report filename. (default "saucectl-report.json").</td>
+    </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--reportersjsonwebhookurl">--reporters.json.webhookURL</a></span></td>
+     <td></td>
+     <td>Specifies the webhook URL. When saucectl test is finished, it'll send a HTTP POST payload to the configured webhook URL.</td>
+    </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--reportersjunitenabled">--reporters.junit.enabled</a></span></td>
+     <td></td>
+     <td>Toggles saucectl's own junit reporting on/off.</td>
+    </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--reportersjunitfilename">--reporters.junit.filename</a></span></td>
+     <td></td>
+     <td>Specifies the report filename. (default "saucectl-report.xml").</td>
+    </tr>
     <tr>
      <td><span className="t-cli"><a href="#--retries">--retries</a></span></td>
      <td></td>
      <td>Number of times to rerun a failed test suite.</td>
     </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--root-dir">--root-dir</a></span></td>
+     <td></td>
+     <td>Specifies the project directory. Not applicable to mobile frameworks. (default ".")</td>
+    </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--sauceignore">--sauceignore</a></span></td>
+     <td></td>
+     <td>Specifies the path to the .sauceignore file. (default ".sauceignore")</td>
+    </tr>
     <tr>
      <td><span className="t-cli"><a href="#--select-suite">--select-suite</a></span></td>
      <td></td>
@@ -124,13 +169,8 @@ Execute tests according to the environment, framework, and test suite specificat
     </tr>
     <tr>
      <td><span className="t-cli"><a href="#--timeout">--timeout</a></span></td>
-     <td></td>
-     <td>Set a max test duration.</td>
-    </tr>
-    <tr>
-     <td><span className="t-cli"><a href="#--uploadTimeout">--uploadTimeout</a></span></td>
-     <td></td>
-     <td>Set a max upload duration.</td>
+      <td><span className="t-cli">-t</span></td>
+     <td>Global timeout that limits how long saucectl can run in total. Supports duration values like '10s', '30m' etc. (default: no timeout).</td>
     </tr>
     <tr>
      <td><span className="t-cli"><a href="#--tunnel-name">--tunnel-name</a></span></td>
@@ -142,6 +182,11 @@ Execute tests according to the environment, framework, and test suite specificat
      <td></td>
      <td>The tunnel owner, if it is not the testing account.</td>
     </tr>
+    <tr>
+     <td><span className="t-cli"><a href="#--upload-timeout">--upload-timeout</a></span></td>
+     <td></td>
+     <td>Set a max upload duration.</td>
+    </tr>
     <tr>
      <td><span className="t-cli"><a href="#--verbose">--verbose</a></span></td>
      <td></td>
@@ -168,7 +213,7 @@ saucectl run --artifacts.cleanup true
 ### <span className="cli">--artifacts.download.directory</span>
 
 <div className="cli-desc">
-<p><small>| OPTIONAL | PATH | <span className="sauceGreen">RDC Only</span> |</small></p>
+<p><small>| OPTIONAL | PATH |</small></p>
 
 Specifies the path to the folder location in which to download artifacts. A separate subdirectory is generated in this location for each suite for which artifacts are downloaded. Must be set in conjunction with `--artifacts.download.match` and `--artifacts.download.when`.
 
@@ -223,9 +268,9 @@ Allows you to launch tests without waiting for results of the preceding tests. T
 ### <span className="cli">--build</span>
 
 <div className="cli-desc">
-<p><small>| OPTIONAL | STRING | <span className="sauceGreen">VDC Only</span> |</small></p>
+<p><small>| OPTIONAL | STRING |</small></p>
 
-Associates the tests with a build to support easy filtering of related test results in the Sauce Labs UI. This option is not yet supported for mobile real device tests.
+Associates the tests with a build to support easy filtering of related test results in the Sauce Labs UI.
 
 ```bash
 saucectl run --build myBuildID
@@ -371,10 +416,25 @@ Usage information for the `run` command.
 
 </div>
 
+### <span className="cli">--launch-order</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+Modify the execution order of suites.
+
+Supported value `fail rate`: Jobs with the highest failure rate are prioritized for launch.
+
+```bash
+saucectl run --launch-order="fail rate"
+```
+
+</div>
+
 ### <span className="cli">--live-logs</span>
 
 <div className="cli-desc">
-<p><small>| OPTIONAL | BOOLEAN | <span className="sauceGreen">Sauce Orchestrate Only</span></small></p>
+<p><small>| OPTIONAL | BOOLEAN | <span className="sauceGreen">Sauce Orchestrate Only</span> |</small></p>
 
 Tail the live log output from a running Sauce Orchestrate container.
 
@@ -384,6 +444,19 @@ saucectl run --live-logs
 
 </div>
 
+### <span className="cli">--no-auto-tagging</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | BOOLEAN |</small></p>
+
+Disables the automatic tagging of jobs with metadata, such as CI or Git information.
+
+```bash
+saucectl run --no-auto-tagging
+```
+
+</div>
+
 ### <span className="cli">--no-color</span>
 
 <div className="cli-desc">
@@ -402,7 +475,7 @@ saucectl run --no-color
 <div className="cli-desc">
 <p><small>| REQUIRED | STRING |</small></p>
 
-Specifies the Sauce Labs data center through which tests will run. Valid values are: `us-west-1` (default) or `eu-central-1`.
+Specifies the Sauce Labs data center through which tests will run. Valid values are: `us-west-1`, `us-east-4` or `eu-central-1`.
 
 **Shorthand:** `-r`
 
@@ -412,10 +485,80 @@ saucectl run --region us-west-1
 
 </div>
 
+### <span className="cli">--reporters.json.enabled</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | BOOLEAN |</small></p>
+
+Toggles saucectl's JSON test result reporting on/off. This only affects the reports that saucectl itself generates as a summary of your tests.
+
+```bash
+saucectl run --reporters.json.enabled=true
+```
+
+</div>
+
+### <span className="cli">--reporters.json.filename</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | FILEPATH |</small></p>
+
+Sets the report filename, with the default being `saucectl-report.json`.
+
+To use this option, make sure to activate the JSON reporter by including `--reporters.json.enabled=true`.
+
+```bash
+saucectl run --reporters.json.enabled=true --reporters.json.filename="path/to/my_report.json"
+```
+
+</div>
+
+### <span className="cli">--reporters.json.webhookURL</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | URL |</small></p>
+
+Specifies the webhook URL. When saucectl test is finished, it'll send an HTTP POST payload to the configured webhook URL.
+
+To use this option, make sure to activate the JSON reporter by including `--reporters.json.enabled=true`.
+
+```bash
+saucectl run --reporters.json.enabled=true --reporters.json.webhookURL="my_webhook_url"
+```
+
+</div>
+
+### <span className="cli">--reporters.junit.enabled</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | BOOLEAN |</small></p>
+
+Toggles saucectl's own junit reporting on/off. This only affects the reports that saucectl itself generates as a summary of your tests. Each Job in Sauce Labs has an independent report regardless.
+
+```bash
+saucectl run --reporters.junit.enabled=true
+```
+</div>
+
+### <span className="cli">--reporters.junit.filename</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | FILEPATH |</small></p>
+
+Sets the report filename, with the default being `saucectl-report.xml`.
+
+To use this option, make sure to activate the JUnit reporter by including `--reporters.junit.enabled=true`.
+
+```bash
+saucectl run --reporters.junit.enabled=true --reporters.junit.filename="path/to/my_report.xml"
+```
+
+</div>
+
 ### <span className="cli">--retries</span>
 
 <div className="cli-desc">
-<p><small>| REQUIRED | INTEGER |</small></p>
+<p><small>| OPTIONAL | INTEGER |</small></p>
 
 Instructs `saucectl` to rerun failed tests this many times.
 
@@ -425,6 +568,32 @@ saucectl run --retries 2
 
 </div>
 
+### <span className="cli">--root-dir</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | FILEPATH |</small></p>
+
+Specifies the project directory. Not applicable to mobile frameworks. Default: `.`.
+
+```bash
+saucectl run --root-dir="path/to/my/root_dir"
+```
+
+</div>
+
+### <span className="cli">--sauceignore</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | FILEPATH |</small></p>
+
+Specifies the path to the .sauceignore file. Default: `.sauceignore`.
+
+```bash
+saucectl run --sauceignore="path/to/my/.sauceignore"
+```
+
+</div>
+
 ### <span className="cli">--select-suite</span>
 
 <div className="cli-desc">
@@ -458,9 +627,9 @@ saucectl run --show-console-log
 ### <span className="cli">--tags</span>
 
 <div className="cli-desc">
-<p><small>| OPTIONAL | LIST | <span className="sauceGreen">VDC Only</span> |</small></p>
+<p><small>| OPTIONAL | LIST |</small></p>
 
-A keyword that may help you distinguish the test in Sauce Labs, and also helps you apply filters to easily isolate tests based on metrics that are meaningful to you. This option is not yet supported for mobile real device tests.
+Keywords that may help you distinguish the test in Sauce Labs, and also help you apply filters to easily isolate tests based on metrics that are meaningful to you.
 
 ```bash
 saucectl run --tags e2e,team2
@@ -486,16 +655,16 @@ saucectl run --timeout 30m
 
 </div>
 
-### <span className="cli">--uploadTimeout</span>
+### <span className="cli">--upload-timeout</span>
 
 <div className="cli-desc">
 <p><small>| OPTIONAL | DURATION |</small></p>
 
-Upload timeout that limits how long saucectl will wait for an upload to finish. Supports duration values like '10s' '30m' etc. (default: 5m)
+Uploads timeout that limits how long saucectl will wait for an upload to finish. Supports duration values like '10s' '30m' etc. (default: 5m)
 
 ```bash
-saucectl run --uploadTimeout 10s
-saucectl run --uploadTimeout 30m
+saucectl run --upload-timeout 10s
+saucectl run --upload-timeout 30m
 ```
 
 </div>
@@ -505,7 +674,7 @@ saucectl run --uploadTimeout 30m
 <div className="cli-desc">
 <p><small>| OPTIONAL | STRING |</small></p>
 
-Specifies an active [Sauce Connect](/secure-connections/sauce-connect/proxy-tunnels/) tunnel to establish a secure connection to run this test on Sauce Labs.
+Specifies an active [Sauce Connect](/secure-connections) tunnel to establish a secure connection to run this test on Sauce Labs.
 
 :::note
 Replaces the former `--tunnel_id` option, which is deprecated.

docs/dev/cli/saucectl/usage/ci/azure.md

@@ -21,11 +21,11 @@ These examples can apply to virtually any Azure DevOps deployment, provided that
 To run tests on Sauce Labs from Azure DevOps, you need to make your Sauce Labs credentials available to your Pipelines. We'll set a secret variable in the UI.
 
 1. Log in to Azure DevOps.
-1. Go to the **Pipelines** page, select a pipeline, then **Edit**.
-1. Click on **Variables**, then **New Variable**.
-1. Enter the name `sauceUsername` and set the value to your Sauce Labs username and click **OK**.
-1. Add another variable, this time named `sauceAccessKey`, set it to your Sauce Labs access key, select the `Keep this value secret` option, and click **OK**.
-1. Click **Save**.
+2. Go to the **Pipelines** page, select a pipeline, then **Edit**.
+3. Click on **Variables**, then **New Variable**.
+4. Enter the name `sauceUsername` and set the value to your Sauce Labs username and click **OK**.
+5. Add another variable, this time named `sauceAccessKey`, set it to your Sauce Labs access key, select the `Keep this value secret` option, and click **OK**.
+6. Click **Save**.
 
 ## Add Azure Pipeline Configuration