Merge branch 'main' into hg/sc5_cli

Author: waggledans

docs/basics/acct-team-mgmt/concurrency-limits.md

@@ -59,7 +59,7 @@ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
 
 :::caution
 
-Queuing will be disabled on March 1st, 2024. To better manage your usage, check the [Usage Analytics](https://docs.saucelabs.com/dev/api/usage/) that Sauce Labs provides for you 
+Queuing will be disabled on May 1st, 2024 (implemented upon contract renewal). To better manage your usage, check the [Usage Analytics](https://docs.saucelabs.com/dev/api/usage/) that Sauce Labs provides for you 
 
 :::
 

docs/basics/acct-team-mgmt/private-device-mgmt.md

@@ -65,6 +65,8 @@ This setting does **NOT** install the app. You must manually or via automation i
 `com.google.chrome.ios`  
 `com.apps.app1`  
 `com.ios.app2`  
+
+*Multiple entries must be comma-separated.*
 :::
 
 ## System App Allow List (iOS)
@@ -75,8 +77,10 @@ Certain iOS preinstalled apps are hidden by default, e.g. Messages, Mail, Notes.
 For a list of native iPhone and iPad apps and their corresponding bundle IDs, please follow the reference link below.  
 https://support.apple.com/en-gb/guide/deployment/depece748c41/web
 
-`com.apple.MobileSMS`  
-`com.apple.mobilenotes`  
+`com.apple.MobileSMS`
+`com.apple.mobilenotes`
+
+*Multiple entries must be comma-separated.*
 :::
 
 ## Account Allow List
@@ -89,6 +93,8 @@ Update this setting for each account email to preserve store and payment account
 :::important
 `[email protected]`  
 `[email protected]`  
+
+*Multiple entries must be comma-separated.*
 :::
 
 ## Retain folders/filepath (Android)
@@ -114,6 +120,8 @@ Invalid path: `/data/local/tmp/`
 :::important
 `/data/com.wavelink.velocity/files`  
 `/com.my.app/data/temp/folder`
+
+*Multiple entries must be comma-separated.*
 :::
 
 ## Enable Apple Pay

docs/dev/api/accounts.md

@@ -1774,6 +1774,12 @@ Assign user to one or multiple teams. New team assignments will replace the exis
      <td><p><small>| PATH | REQUIRED | STRING |</small></p><p>The unique identifier of the Sauce Labs user. You can look up the ID of a user in your organization using the <a href="#lookup-users">Lookup Users</a> endpoint.</p></td>
     </tr>
   </tbody>
+  <tbody>
+    <tr>
+     <td><code>teams</code></td>
+     <td><p><small>| BODY | REQUIRED | ARRAY OF STRINGS |</small></p><p>List of unique team identifiers. You can look up the ID of teams in your organization using the <a href="#lookup-teams">Lookup Teams</a> endpoint.</p></td>
+    </tr>
+  </tbody>
 </table>
 
 <Tabs
@@ -1790,7 +1796,7 @@ values={[
 curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
 --request PUT 'https://api.us-west-1.saucelabs.com/team-management/v1/users/<user-id>/teams/' \
 --header 'Content-Type: application/json' \
---data-raw '["<team1-id>", "<team2-id>"]' | json_pp
+--data-raw '{"teams": ["<team1-id>", "<team2-id>"]}' | json_pp
 ```
 
 </TabItem>
@@ -1800,7 +1806,7 @@ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
 curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
 --request PUT 'https://api.eu-central-1.saucelabs.com/team-management/v1/users/<user-id>/teams/' \
 --header 'Content-Type: application/json' \
---data-raw '["<team1-id>", "<team2-id>"]' | json_pp
+--data-raw '{"teams": ["<team1-id>", "<team2-id>"]}' | json_pp
 ```
 
 </TabItem>

docs/dev/api/rdc.md

@@ -108,7 +108,7 @@ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
         "isAlternativeIoEnabled": true,
         "supportsManualWebTesting": true,
         "supportsMultiTouch": true,
-        "supportsXcuiTest": true
+        "supportsXcuiTest": false
     },
     {...more devices},
 ]
@@ -801,7 +801,7 @@ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \
       "supportsMinicapSocketConnection" : false,
       "supportsMockLocations" : true,
       "supportsMultiTouch" : true,
-      "supportsXcuiTest" : true
+      "supportsXcuiTest" : false
    },
    "device_log_url" : "https://api.eu-central-1.saucelabs.com/v1/rdc/jobs/51873a114a6141239c933042e948aa54/deviceLogs",
    "device_name" : "Samsung Galaxy S10",

docs/dev/cli/saucectl/run.md

@@ -182,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="#--tunnel-timeout">--tunnel-timeout</a></span></td>
+     <td></td>
+     <td>How long to wait for the specified tunnel to be ready. Supports duration values like '10s', '30m' etc. (default: 30s)</td>
+    </tr>
     <tr>
      <td><span className="t-cli"><a href="#--upload-timeout">--upload-timeout</a></span></td>
      <td></td>
@@ -538,6 +543,7 @@ Toggles saucectl's own junit reporting on/off. This only affects the reports tha
 ```bash
 saucectl run --reporters.junit.enabled=true
 ```
+
 </div>
 
 ### <span className="cli">--reporters.junit.filename</span>
@@ -703,6 +709,19 @@ saucectl run --tunnel-name not-my-tunnel --tunnel-owner another.sauce.username
 
 </div>
 
+### <span className="cli">--tunnel-timeout</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | DURATION |</small></p>
+
+How long to wait for the specified tunnel to be ready. Supports duration values like '10s', '30m' etc. (default: 30s)
+
+```bash
+saucectl run --tunnel-name who-knows-when-ready --tunnel-timeout 1m
+```
+
+</div>
+
 ### <span className="cli">--verbose</span>
 
 <div className="cli-desc">

docs/dev/test-configuration-options.md

@@ -176,6 +176,21 @@ Describes the current session’s user prompt handler. The default value is `"di
 
 ---
 
+### `webSocketUrl`
+
+<p><small>| BOOLEAN | <span className="sauceGreen">Desktop Only</span> | <span className="sauceGreen">BETA</span> |</small></p>
+
+Enables [W3C WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) support. This allows Selenium 4 clients to use [Bi-Directional functionality](https://www.selenium.dev/documentation/webdriver/bidirectional/). It also enables BiDi for other test frameworks, like [WebDriverIO](https://webdriver.io/docs/api/webdriverBidi/). In particular, this capability exposes the WebSocket endpoint which is available under `webSocketUrl` field in session startup response body. This endpoint can be used to issue WebDriver BiDi commands as described by the [specification](https://w3c.github.io/webdriver-bidi/). The default value is `false`.
+
+The `webSocketUrl` capability is **not compatible** with [`extendedDebugging`](#extendeddebugging) capability.
+
+
+```java
+"webSocketUrl": true
+```
+
+---
+
 ## Desktop Browser Capabilities: Sauce-Specific – Optional
 
 Browser-specific optional capabilities you can add to the `sauce:options` block of your test session creation code.
@@ -345,6 +360,20 @@ Sets idle test timeout in seconds. As a safety measure to prevent tests from run
 
 ---
 
+### `devTools`
+
+<p><small>| OPTIONAL | BOOLEAN | <span className="sauceGreen">Desktop Only</span> | <span className="sauceGreen">BETA</span> | </small></p>
+
+Enables [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) support, which is disabled by default on Sauce Labs platform. This allows Selenium 4 clients to use [Bi-Directional functionality](https://www.selenium.dev/documentation/webdriver/bidirectional/). In particular, this capability exposes the WebSocket endpoint which is available under `se:cdp` field in session startup response body. This endpoint can be used to issue Chrome DevTools Protocol commands as described by the [specification](https://chromedevtools.github.io/devtools-protocol/). The default value is `false`.
+
+The `devTools` capability is **not compatible** with [`extendedDebugging`](#extendeddebugging) capability.
+
+```java
+"devTools": true
+```
+
+---
+
 ## Mobile Appium Capabilities
 
 As the W3C WebDriver Protocol is supported in Appium v1.6.5 and higher, and required for Appium v2.0, we encourage and support using it for your Appium mobile app tests instead of the JSON Wire Protocol (JWP). We'll continue to support JWP in all currently supported Appium 1.X versions, but please be aware that with Appium 2.0, JWP support will be fully deprecated in favor of W3C.

docs/mobile-apps/automated-testing/appium/appium-versions.md

@@ -155,6 +155,12 @@ The current end-of-life strategy outlined above is specific to Real Devices. We
 
 ## Real Devices
 
+:::info Supported Custom Appium Plugins:
+The following list of custom Appium plugins are supported:
+- [Appium Images Plugin](https://www.npmjs.com/package/@appium/images-plugin). This plugin will now be included by default with Appium version `latest` and all subsequent versions released after April 1st.
+- [Deque axe DevTools® Mobile Analyzer Accessibility plugin](https://docs.deque.com/devtools-mobile/appium). This plugin helps you with automated accessibility testing. Empower your team to focus on identifying and resolving accessibility issues. Requires Deque axe DevTools® Mobile license.
+:::
+
 ### Appium 2.x
 
 <table>
@@ -204,6 +210,29 @@ The current end-of-life strategy outlined above is specific to Real Devices. We
         </ul>
       </td>
     </tr>
+    <tr>
+      <td>
+        <code>appium2-deque-accessibility</code>
+      </td>
+      <td>
+        <span className="sauceGreen">Active</span>
+      </td>
+      <td>  
+        <a href="https://docs.deque.com/devtools-mobile/2024.2.14/en/march-2024" target="_blank">
+              Deque axe DevTools® Mobile Analyzer Accessibility plugin</a> helps you with automated accessibility testing. Contains only the latest version of Appium. The plugin helps to identify and to resolve accessibility issues. Requires Deque axe DevTools® license.
+        <br />
+        <ul>
+          <li>
+            <a href="https://docs.deque.com/devtools-mobile/2024.2.14/en/march-2024" target="_blank">
+              <code>axeDevToolsMobile Appium Plugin</code>: 2.0.0 </a>
+          </li>
+          <li>
+            <a href="https://github.com/appium/appium/releases/tag/appium%402.5.1" target="_blank">
+              <code>appium</code>: 2.5.1 </a>
+          </li>
+        </ul>
+      </td>
+    </tr>
     <tr>
       <td>
         <code>appium2-20240301</code>

docs/mobile-apps/features/appium-inspector.md

@@ -97,8 +97,6 @@ x/y coordinates
 
 ## Hybrid Apps / WebView
 
-<p><span className="sauceGreen">iOS Only</span></p>
-
 Utilize [Dev Tools](https://docs.saucelabs.com/web-apps/live-testing/dev-tools/) to validate hybrid or web views within native applications. 
 This feature enables seamless validation of web content integrated within native apps, providing comprehensive testing capabilities for a 
 smooth user experience across different platforms.

docs/mobile-apps/features/virtual-usb.md

@@ -37,6 +37,11 @@ It integrates into your development and test environment, meaning you can use yo
   - Android Studio 4 or higher.
 - If you need to use [Sauce Connect Proxy](/secure-connections/sauce-connect), you'll need to have the client installed first.
 
+:::note Limitations
+vUSB is currently only supported for test automation. Debugging with any IDE, and attaching debuggers with Xcode and Android Studio, are not advised and won't be supported at this time). 
+iOS17 is not supported at this time. We will soon introduce a new CLI tool to connect to a device and run automated tests. 
+:::
+
 ## Using Virtual USB
 
 :::tip CLI Reference
@@ -282,11 +287,11 @@ adb connect localhost:7000
 
 ### Test and Debug
 
-8. Now, you can debug and run tests on your app. For guidance and ideas, see the [Example Use Cases](/mobile-apps/features/virtual-usb/#example-use-cases).
+8. Now, you can debug and run tests on your app. We advise you to use our Sauce App Storage to upload the apps and run tests against them. 
 
 <!-- prettier-ignore-start -->
-:::caution iOS Limitation
-To do proper debugging, the iOS device symbols will need to be downloaded to your local machine. This happens automatically when you're connecting to a Sauce Labs iOS device for the first time via a remote debug vUSB session with Xcode. **Xcode will attempt to download the iOS device symbols over the vUSB tunnel, causing a lag that can last up to a few minutes.**
+:::caution iOS Limitations
+Attaching a debugger is not supported due to the amount of data that the iOS device symbols will need to be downloaded to your local machine. This process occurs automatically when you're connecting to a Sauce Labs iOS device for the first time via a remote debug vUSB session with Xcode. Xcode will attempt to download the iOS device symbols over the vUSB tunnel, causing a lag that can last from a few minutes to an hour..**
 
 - **What to Do**: Go to `~/Library/Developer/Xcode/iOS DeviceSupport/` and check the used iOS version of the phone to see if the symbols have been downloaded. The total used space per OS should be more than 1GB. If they are less than 1MB, delete the folder and restart Xcode again so it can re-fetch them.
   This a one-time action that you won't need to do again for future tests.
@@ -336,10 +341,6 @@ java -jar virtual-usb-client.jar disconnect --sessionId 37D274BC3A65A34BB3DA4DDF
 
 ## Example Use Cases
 
-### Exploratory Testing
-
-Introduce breakpoints in your IDE, for example, Android Studio or XCODE, and then do exploratory testing.
-
 ### ADB commands
 
 You can execute `adb` commands on the device connected over vUSB as you would normally also use. This is a simple example to capture a screenshot and pull it to your local machine.
@@ -393,92 +394,3 @@ The following example sets up forwarding of host port 40000 (laptop/CI) to devic
 To for example profile your Android app you can follow the instructions as mentioned [here](https://developer.android.com/studio/profile). This can result in the following data.
 
 <img src={useBaseUrl('img/virtual-usb/vusb-android-profiling.png')} alt="Virtual USB Android Studio Profiling" />
-
-### Chrome DevTools Web Debugging
-
-This example demonstrates how to connect your test device to Chrome Inspector and export an [Http ARchive (HAR)](<https://en.wikipedia.org/wiki/HAR_(file_format)>) file to your local machine from a live testing session. Chrome Inspector's suite of developer tools provides a powerful way to work with your web pages while leveraging our real devices.
-
-HAR files are useful for identifying performance issues, network traffic, and other information, such as:
-
-- HTTP requests generated by your web pages
-- API calls
-- User analytics
-- Third-party web service calls
-
-1. Follow the steps in the previous section to start up a test session (i.e., download vUSB client, connect to Data Center, connect to your device, and initialize an `adb` connection). Have your Sauce Labs device test session up on your screen.
-
-2. Open a Chrome tab locally and run `chrome://inspect` in the address bar. This opens the Chrome Inspector.
-   <img src={useBaseUrl('img/virtual-usb/vusb4.png')} alt="Virtual USB" width="400" />
-
-3. Use your command line terminal to open Chrome on the device by running the `adb` commands below. The first one launches the Chrome app:
-
-```java
-$ ./adb shell am start -n com.android.chrome/com.google.android.apps.chrome.Main
-```
-
-Then, navigate to a website (for this example, we'll use our demo site).
-
-```java
-$ ./adb shell am start -a android.intent.action.VIEW -d http://www.saucedemo.com
-```
-
-4. If the above commands are successful, you should see a new set of options under the **Remote Target** heading in your `chrome://inspect` tab.
-
-If you click **Inspect**, a new window will open, displaying Chrome DevTools the same as if the device were sitting on your desk, connected to a USB cable.
-<img src={useBaseUrl('img/virtual-usb/vusb3.png')} alt="Virtual USB" width="400" />
-<img src={useBaseUrl('img/virtual-usb/vusb2.png')} alt="Virtual USB" width="600" />
-
-5. Click the **Network** tab and reload the page to display all HTTP requests made during the refresh:
-
-6. Under the **Network** tab, click the down arrow icon to export a HAR file locally. This will prompt you with a Save dialog. Choose a location for the HAR file.
-   <img src={useBaseUrl('img/virtual-usb/vusb6.png')} alt="Virtual USB HAR" width="600" />
-
-7. Review your HAR file. It should contain every HTTP request/response gathered during the page load, as well as all of the headers, parameters, timing info. Using this information, you can dive deep into the way your web pages are put together. You can do it on any configured device, without having to worry about power management or keeping up with the physical device.
-
-:::tip
-For more tips on working with HAR Files, check out [Visualize HAR Files with the Sauce Labs React Network Viewer Component](https://opensource.saucelabs.com/blog/react_network_viewer).
-:::
-
-You can execute `adb` commands on the device connected over vUSB as you would normally also use. This is a simple example to capture a screenshot and pull it to your local machine.
-
-```bash
-#Create a temporary folder to save a screenshot.
-mkdir tmp
-#Capture a screenshot and save to /sdcard/screen.png on your Android divice.
-adb shell screencap -p /sdcard/screen.png
-
-#Grab the screenshot from /sdcard/screen.png to /tmp/screen.png on your PC.
-adb pull /sdcard/screen.png /tmp/screen.png
-
-#Delete /sdcard/screen.png.
-adb shell rm /sdcard/screen.png
-
-#open the screenshot on your PC.
-open /tmp/screen.png
-```
-
-### iOS Debugging
-
-To deploy and debug your iOS apps, you can use Xcode. To debug your website, we recommend using the developer tools within Safari.
-
-### **Xcode Debugging**
-
-:::note
-Before debugging with Xcode, please read the known limitations under [Test and Debug](/mobile-apps/features/virtual-usb/#test-and-debug).
-:::
-
-To profile your app: from your Xcode nav, select **Product** > **Profile**. It will automatically profile the app and generate a new menu, as shown below.
-
-<img src={useBaseUrl('img/virtual-usb/vusb-ios-profiling.png')} alt="Virtual USB Profiling" />
-
-<br/>
-
-In this example below, **Energy Log** has been selected and recording has been started. This can result in the following screen.
-
-<img src={useBaseUrl('img/virtual-usb/vusb-energy-logs.png')} alt="Virtual USB Energy Logs" />
-
-### **Safari Web Debugging**
-
-To debug with Safari: Open Safari > From the nav, select **Develop** > **Select your device** > **Select the view** you want to debug. In our example, we want to debug the [Sauce Swag Labs demo website](https://www.saucedemo.com).
-
-<img src={useBaseUrl('img/virtual-usb/vusb-safari-debug.png')} alt="Virtual USB Energy Logs" />

docs/mobile-apps/mobile-faq.md

@@ -83,9 +83,11 @@ We maintain an allowlist of commands that can be executed within our Real Device
 * pm clear
 * input
 * (ls|cp|mkdir|echo|grep|cut|pwd|dumpsys)
-* getProp
+* getprop
 * am compat enable
 * cmd connectivity airplane-mode (enable|disable)
+* settings put global (animator_duration_scale|transition_animation_scale|window_animation_scale) <value\>
+* setprop debug.firebase.analytics.app <value\>
 
 If the command you require is not listed, you can submit a request through this [form](https://docs.google.com/forms/d/1t4MCf6ClHlLxX80RP5bNU9wVJBhQOd4ll6IjP0ecMgc) 
 or reach out to your Customer Success Manager or Sauce Labs Support for assistance.

docs/visual-testing/_partials/_clipping-description.md

@@ -0,0 +1,7 @@
+You can clip to a specific element on the page by using the `clipSelector` option when calling Sauce visual.
+
+Notes:
+
+- Clipping is done by taking a screenshot of the page then clipping it to the location of the requested element.
+- We will attempt to scroll the element into view before taking the snapshot.
+- We can only take a screenshot of what is visible in the current viewport, however, this can be combined with full page option to enable clipping large vertical elements.

docs/visual-testing/_partials/_clipping-webdriver.md

@@ -0,0 +1,12 @@
+import ClippingDescription from './_clipping-description.md'
+
+<ClippingDescription />
+
+Example:
+
+```ts
+await browser.sauceVisualCheck('Visible Sale Banner', {
+  // A document.querySelector compatible selector that we should crop the screenshot to
+  clipSelector: '.your-css-selector',
+})
+```