README for iOS and fix uuid -> udid (#4)

Co-authored-by: Priyansh Garg <[email protected]>
nightwatchjs · Nov 2, 2022 · f2199ff · f2199ff
1 parent 9915f07
commit f2199ff
Show file tree

Hide file tree

Showing 3 changed files with 110 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -26,6 +26,8 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g
     // other envs above this line
     'android.chrome': {
       desiredCapabilities: {
+        real_mobile: false,
+        avd: 'nightwatch-android-11',
         browserName: 'chrome',
         'goog:chromeOptions': {
           w3c: true,
@@ -53,6 +55,8 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g
 
     'android.firefox': {
       desiredCapabilities: {
+        real_mobile: false,
+        avd: 'nightwatch-android-11',
         browserName: 'firefox',
         acceptInsecureCerts: true,
         'moz:firefoxOptions': {
@@ -80,6 +84,8 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g
 7. If testing on real-device:
    1. Make sure latest version of Chrome/Firefox browsers are installed. If not, install them from Google Play Store.
    2. [Turn on USB Debugging](https://developer.android.com/studio/debug/dev-options#enable) on your Android Device and connect it to your system via data cable.
+   3. Set `real_mobile` capability to true in the configuration.
+
 8. If testing on emulator, make sure `chromedriver-mobile/chromedriver` is present in your Nightwatch project's root dir. If not present, re-run the command in first step.
 9. Run your nightwatch tests on Android mobile browsers:
    ```sh
@@ -88,3 +94,97 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g
     # for chrome
     npx nightwatch --env android.chrome
    ```
+
+### iOS
+
+1. From your [Nightwatch](https://nightwatch.org) project's root dir, run:
+
+   ```sh
+   npx @nightwatch/mobile-helper ios
+   ```
+2. Answer a device related question:
+
+   <img width="352" alt="image" src="https://user-images.githubusercontent.com/94462364/199410412-e40da151-e545-4039-90db-e68697358665.png">
+
+
+3. It will verify if all the requirements are being met.
+4. If some requirements are not being met, follow the guide to setup those requirements.
+
+   <img width="662" alt="image" src="https://user-images.githubusercontent.com/94462364/199419711-43e7793a-df82-4d67-a832-679eb5c1f7b9.png">
+
+
+5. Great :tada: Your setup is now complete. (Re-run the command in the first step to verify.)
+
+6. Add the following env configuration to your `nightwatch.conf.js` or `nightwatch.json` file:
+   ```js
+   "test_settings": {
+     // other envs above this line
+     'ios.real.safari': {
+       desiredCapabilities: {
+         browserName: 'safari',
+         platformName: 'iOS',
+         // add the device UDID to run tests on (necessary)
+         // Run command: `xcrun simctl list devices`
+         // 'safari:deviceUDID': '00008030-00024C2C3453402E',
+       },
+
+       webdriver: {
+         start_process: true,
+         server_path: '',
+         cli_args: [
+           // --verbose
+         ]
+       }
+     },
+
+     'ios.simulator.safari': {
+       desiredCapabilities: {
+         browserName: 'safari',
+         platformName: 'iOS',
+         'safari:useSimulator': true,
+         // change the deviceName, platformVersion accordingly to run tests on 
+         // Run command: `xcrun simctl list devices`
+         // 'safari:platformVersion': '15.0',
+         'safari:deviceName': 'iPhone 13'
+       },
+
+       webdriver: {
+         start_process: true,
+         server_path: '',
+         cli_args: [
+           // --verbose
+         ]
+       }
+     },
+   }
+   ```
+7. (**Real Device**) Run the following command to get the *UDID*:
+   ```sh
+    system_profiler SPUSBDataType | sed -n '/iPhone/,/Serial/p' | grep 'Serial Number:' | awk -F ': ' '{print $2}'
+    ```
+
+8. (**Optional**) Update the configurations : 
+
+    **Real Device**
+
+    Set `safari:deviceUDID` capability to *UDID* from the previous step, in your Nightwatch configuration for `ios.real.safari` environment.
+
+    **Simulators**
+
+    Run the following command to get a list of simulators:
+    ```sh
+    xcrun simctl list devices
+    ```
+    And then update `safari:deviceName` (eg: 'iphone 13') and `safari:platformVersion` (eg: '15.0') in your Nightwatch configuration for `ios.simulator.safari` environment according to your preference.
+
+
+8. Run your nightwatch tests on Android mobile browsers:
+   ```sh
+    # for simulators
+    npx nightwatch --env ios.simulator.safari
+
+    # for real device
+    npx nightwatch --env ios.real.safari --udid <YOUR-DEVICE-UDID>
+    # for real device (if updated the config in the previous step)
+    npx nightwatch --env ios.real.safari
+   ```
diff --git a/src/commands/ios/index.ts b/src/commands/ios/index.ts
@@ -1,6 +1,6 @@
 import { prompt } from 'inquirer';
 import { Options, SetupConfigs, IosSetupResult } from './interfaces';
-import { getPlatformName, iosRealDeviceUUID, symbols } from '../../utils';
+import { getPlatformName, iosRealDeviceUDID, symbols } from '../../utils';
 import { AVAILABLE_OPTIONS, SETUP_CONFIG_QUES } from './constants';
 import colors from 'ansi-colors';
 import { execSync } from 'child_process';
@@ -105,8 +105,9 @@ export class IosSetup {
 
         if (stdout.toString() !== '') {
           Logger.log(boxen(
-            colors.white(`Update ${colors.cyan('UUID')} in nightwatch configuration for ${colors.gray.italic('ios.real.safari')} environment.`) +
-            colors.cyan("\nUUID: " + iosRealDeviceUUID(stdout.toString())), {padding: 1}));
+            colors.white(`Update ${colors.cyan('UDID')} in nightwatch configuration for ${colors.gray.italic('ios.real.safari')} environment.`) +
+            "\nUDID: " + 
+            colors.cyan(iosRealDeviceUDID(stdout.toString())), {padding: 1}));
         } else {
           throw "Device is not connected";
         }
@@ -171,11 +172,11 @@ export class IosSetup {
     if (setupConfigs.mode === 'real' || setupConfigs.mode === 'both') {
       Logger.log("\nSetting up missing requirements for real devices...")
 
-      let msg = colors.cyan("Remote Automation should be turned on (necessary) ") +
+      let msg = colors.cyan("1. Remote Automation should be turned on your iOS device.") +
         colors.grey.italic("\n(turn it on via Settings → Safari → Advanced → Remote Automation.)");
 
       if (missingRequirements.includes('Device is not connected')) {
-        msg += colors.cyan(`\n\nAlso make sure your device is connected and turned on properly`);
+        msg += colors.cyan(`\n\n2. Device is connected via data cable and turned on properly.`);
         result.real = false;
       }
       Logger.log(boxen(msg, {padding: 1}));

diff --git a/src/utils.ts b/src/utils.ts
@@ -64,10 +64,10 @@ export const rmDirSync = (dirPath: string) => {
   }
 };
 
-export const iosRealDeviceUUID = (uuid: string) => {
-  if (uuid.length > 25) {
-    return uuid;
+export const iosRealDeviceUDID = (udid: string) => {
+  if (udid.length > 25) {
+    return udid;
   }
 
-  return `${uuid.substring(0, 8)}-${uuid.substring(9, 25)}`;
+  return `${udid.substring(0, 8)}-${udid.substring(9, 25)}`;
 };