docs: update BrowserStack mobile config (#497)

Author: MohabMohie

docs/Basic_Config/basicConfig2.md

@@ -72,6 +72,29 @@ mobile_udid=00008110-001A23456789AB01
 
 ---
 
+## BrowserStack Native Apps
+
+When `executionAddress=browserstack`, SHAFT can start native mobile sessions from either a BrowserStack app URL or a remote app value in `mobile_app`:
+
+```properties title="src/main/resources/properties/custom.properties"
+executionAddress=browserstack
+targetOperatingSystem=ANDROID
+mobile_automationName=UiAutomator2
+mobile_deviceName=Google Pixel 7
+mobile_platformVersion=13.0
+
+# Preferred when you already know the uploaded BrowserStack app URL
+browserStack.appUrl=bs://<uploaded-app-id>
+
+# Also supported for remote app references when browserStack.appUrl is not set
+# mobile_app=bs://<uploaded-app-id>
+# mobile_app=https://example.com/apps/MyApp.apk
+```
+
+If both `browserStack.appUrl` and `mobile_app` point to remote app values, `browserStack.appUrl` takes precedence. Use local `mobile_app` paths when SHAFT should upload the app for you.
+
+---
+
 ## Mobile Web (Browser on Device)
 
 For mobile browser testing, configure the same properties as [Web GUI](./basicConfig) and add the mobile target:

docs/Best_Practices/Cross_Platform_Strategy.md

@@ -82,11 +82,11 @@ public void testLogin() {
 :::tip
 Switch platforms by changing a single property — no code changes needed:
 ```properties title="src/main/resources/properties/custom.properties"
-targetPlatform=ANDROID
+targetOperatingSystem=ANDROID
 ```
 Or override it from the command line:
 ```bash
-mvn test -DtargetPlatform=IOS
+mvn test -DtargetOperatingSystem=IOS
 ```
 :::
 
@@ -134,5 +134,5 @@ my-company-tests/
 For most teams, starting with a **single project** is the best default. You get maximum code reuse and a single source of truth for your test scenarios. If the apps diverge significantly over time, you can always split later.
 
 :::info
-SHAFT Engine's property-based platform switching makes it easy to run the same tests against both platforms from a single project. Just parameterize `targetPlatform` in your CI/CD pipeline.
+SHAFT Engine's property-based platform switching makes it easy to run the same tests against both platforms from a single project. Just parameterize `targetOperatingSystem` in your CI/CD pipeline.
 :::

docs/Getting_Started/Flutter_Testing.mdx

@@ -76,8 +76,8 @@ SHAFT includes `appium_flutterfinder_java` (v1.0.12) **transitively** via `com.s
 Add these properties to `src/main/resources/properties/custom.properties`:
 
 ```properties title="src/main/resources/properties/custom.properties"
-# Target platform: Android or IOS
-targetPlatform=Android
+# Target operating system: ANDROID or IOS
+targetOperatingSystem=ANDROID
 
 # Appium Flutter Driver automation name
 mobile_automationName=FlutterIntegration

docs/Getting_Started/first_steps_6.md

@@ -211,7 +211,7 @@ AppiumDriver driver = new AndroidDriver(new URL("http://localhost:4723"), caps);
 
 ```java title="After — SHAFT (capabilities in custom.properties)"
 // custom.properties:
-// targetPlatform=ANDROID
+// targetOperatingSystem=ANDROID
 // executionAddress=127.0.0.1:4723
 // mobile_automationName=UIAUTOMATOR2
 // mobile_app=src/test/resources/apps/MyApp.apk

docs/Getting_Started/integrations.mdx

@@ -63,8 +63,8 @@ executionAddress=https://hub-cloud.browserstack.com/wd/hub
 targetBrowserName=chrome
 
 # Credentials (use environment variables in CI)
-browserStack.user=${BROWSERSTACK_USERNAME}
-browserStack.key=${BROWSERSTACK_ACCESS_KEY}
+browserStack.userName=${BROWSERSTACK_USERNAME}
+browserStack.accessKey=${BROWSERSTACK_ACCESS_KEY}
 
 # Capabilities
 browserStack.os=Windows
@@ -79,12 +79,12 @@ browserStack.buildName=Build 1
 
 ```properties title="custom.properties"
 executionAddress=https://hub-cloud.browserstack.com/wd/hub
-targetPlatform=ANDROID
+targetOperatingSystem=ANDROID
 
-browserStack.user=${BROWSERSTACK_USERNAME}
-browserStack.key=${BROWSERSTACK_ACCESS_KEY}
+browserStack.userName=${BROWSERSTACK_USERNAME}
+browserStack.accessKey=${BROWSERSTACK_ACCESS_KEY}
 
-mobile_app=bs://your_uploaded_app_hash
+browserStack.appUrl=bs://your_uploaded_app_hash
 mobile_deviceName=Google Pixel 7
 mobile_platformVersion=13.0
 ```
@@ -126,7 +126,7 @@ lambdaTest.build=Build 1
 
 ```properties title="custom.properties"
 executionAddress=https://mobile-hub.lambdatest.com/wd/hub
-targetPlatform=ANDROID
+targetOperatingSystem=ANDROID
 
 lambdaTest.user=${LAMBDATEST_USERNAME}
 lambdaTest.accessKey=${LAMBDATEST_ACCESS_KEY}

docs/Getting_Started/setup_mobile.mdx

@@ -34,7 +34,7 @@ Configure your mobile target in `src/main/resources/properties/custom.properties
 
 ```properties
 # Platform
-targetPlatform=ANDROID
+targetOperatingSystem=ANDROID
 
 # Appium server
 executionAddress=127.0.0.1:4723
@@ -57,7 +57,7 @@ mobile_autoGrantPermissions=true
 
 ```properties
 # Platform
-targetPlatform=IOS
+targetOperatingSystem=IOS
 
 # Appium server
 executionAddress=127.0.0.1:4723
@@ -130,9 +130,9 @@ Run on real devices in the cloud:
 ```properties
 # BrowserStack
 executionAddress=https://hub.browserstack.com/wd/hub
-browserStack.user=YOUR_USERNAME
-browserStack.key=YOUR_ACCESS_KEY
-mobile_app=bs://your_app_hash
+browserStack.userName=YOUR_USERNAME
+browserStack.accessKey=YOUR_ACCESS_KEY
+browserStack.appUrl=bs://your_app_hash
 
 # LambdaTest
 executionAddress=https://mobile-hub.lambdatest.com/wd/hub

docs/Getting_Started/shaft_wizard.mdx

@@ -97,7 +97,7 @@ driver.quit();
 **Switch to Android with two properties:**
 
 ```properties
-targetPlatform=ANDROID
+targetOperatingSystem=ANDROID
 mobile_automationName=UIAUTOMATOR2
 executionAddress=127.0.0.1:4723
 mobile_app=src/test/resources/apps/MyApp.apk
@@ -107,7 +107,7 @@ mobile_deviceName=Pixel_7_API_34
 **Switch to iOS:**
 
 ```properties
-targetPlatform=IOS
+targetOperatingSystem=IOS
 mobile_automationName=XCUITEST
 executionAddress=127.0.0.1:4723
 mobile_app=src/test/resources/apps/MyApp.app

docs/Properties/PropertiesList.mdx

@@ -726,6 +726,8 @@ This section lists all configurable properties related to Swagger/OpenAPI contra
 ### BrowserStack
 
 - These properties control SHAFT's built-in integration with BrowserStack.
+- Use the canonical authentication keys `browserStack.userName` and `browserStack.accessKey`; the legacy aliases `browserStack.user` and `browserStack.key` are normalized for compatibility.
+- For native mobile apps, `browserStack.appUrl` is resolved before remote `mobile_app` values such as `bs://...`, `http://...`, or `https://...`.
 - You can find all supported Web-based (Desktop or Mobile) execution properties & values in BrowserStack's [Web Capability Generator](https://www.browserstack.com/docs/automate/capabilities)
 - You can find all supported Native Mobile App execution properties & values in BrowserStack's [Appium Capability Generator](https://www.browserstack.com/app-automate/capabilities?tag=w3c)
 
@@ -741,10 +743,10 @@ This section lists all configurable properties related to Swagger/OpenAPI contra
 | browserStack.accessKey               | ``            |                 | BrowserStack access key for authentication.                                                           |
 | browserStack.platformVersion         | ``            |                 | Mobile platform version for BrowserStack execution.                                                   |
 | browserStack.deviceName              | ``            |                 | Mobile device name for BrowserStack execution.                                                        |
-| browserStack.appUrl                  | ``            |                 | Use appUrl to test a previously uploaded app file.                                                    |
+| browserStack.appUrl                  | ``            |                 | Use a BrowserStack app URL for a previously uploaded app; takes precedence over remote `mobile_app`.   |
 | browserStack.customID                | ``            |                 | Use customID to test the latest uploaded version as the above url expires regularly.                  |
 | browserStack.appName                 | ``            |                 | App name for uploading to BrowserStack.                                                               |
-| browserStack.appRelativeFilePath     | ``            |                 | Relative file path to the app for uploading to BrowserStack.                                          |
+| browserStack.appRelativeFilePath     | ``            |                 | Relative file path to the app for SHAFT/BrowserStack upload workflows.                                |
 | browserStack.osVersion               | ``            |                 | In case of Desktop web testing you must also set the `targetOperatingSystem`, and `targetBrowserName`.|
 | browserStack.browserVersion          | ``            |                 | Browser version, optional, uses random by default.                                                    |
 | browserStack.local                   | `false`       | `true`, `false` | Enable BrowserStack local testing.                                                                    |