From 2142087fc48bf9d96a4e0a261660b14a5f6098cd Mon Sep 17 00:00:00 2001 From: itsspriyansh Date: Tue, 3 Sep 2024 14:44:10 +0530 Subject: [PATCH 01/11] add: subcommand instructions in readme --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/README.md b/README.md index 600f329..6cb6982 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,8 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g - [Mobile app testing](#mobile-app-testing---android) - [On Android](#mobile-app-testing---android) - [On iOS](#mobile-app-testing---ios) +- [Do more with Android SDK](#do-more-with-android-sdk) +- [Run Android SDK binaries](#run-android-sdk-binaries) ### Mobile web testing - Android @@ -536,3 +538,85 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g # test on real-device (assuming test saved as `test/wikipedia-ios.js`) npx nightwatch test/wikipedia-ios.js --env app.ios.real ``` + +### Do more with Android SDK + +The tool supports various Android SDK workflows, accessible through the following subcommands: + +1. [connect](./docs/subcommands/connect.md) +2. [list](./docs/subcommands/list.md) +3. [install](./docs/subcommands/install.md) +4. [uninstall](./docs/subcommands/uninstall.md) + +#### Syntax + +The following syntax is used for executing subcommands: + +```bash +npx @nightwatch/mobile-helper android [flags|cliConfigs] +``` + +#### 1. Connect a real device or launch an AVD + +```sh +npx @nightwatch/mobile-helper android connect [flags] +``` + + +| Flag | Description | +| ---------- | ------------------------------------- | +| --wireless | Connect a real device wirelessly | + +#### 2. List all the connected devices and installed AVDs + +```sh +npx @nightwatch/mobile-helper android list [flags] +``` + +| Flag | Description | +| ---------- | ------------------------------------------------------ | +| --device | Show a list of all the connected real devices and AVDs | +| --avd | Show a list of all the currently installed AVDs | + + +#### 3. Install an APK or create a new AVD + +```sh +npx @nightwatch/mobile-helper android install [flags] +``` + +| Flag | Description | +| ----- | ------------------------------------------ | +| --app | Install an APK on a real device or an AVD | +| --avd | Create a new AVD | + + +#### 4. Uninstall an app or delete an AVD + +```sh +npx @nightwatch/mobile-helper android uninstall [flags] +``` + +| Flag | Description | +| ----- | ---------------------------------------------- | +| --app | Uninstall an app from a real device or an AVD | +| --avd | Delete an AVD | + +### Run Android SDK binaries + +Easily run Android SDK binaries without needing to locate them manually by using the `mobile-helper` CLI. + +**Syntax** + +```sh +npx @nightwatch/mobile-helper android. [args] +``` + +**Currenty supported binaries:** +- adb +- avdmanager +- sdkmanager +- emulator + +Check the [docs](./docs/) to know more about using the above binaries. + From fcac830ac788b7e35b75231850584652c9ebe155 Mon Sep 17 00:00:00 2001 From: itsspriyansh Date: Tue, 3 Sep 2024 15:37:57 +0530 Subject: [PATCH 02/11] fix --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6cb6982..530dbdc 100644 --- a/README.md +++ b/README.md @@ -612,11 +612,7 @@ Easily run Android SDK binaries without needing to locate them manually by using npx @nightwatch/mobile-helper android. [args] ``` -**Currenty supported binaries:** -- adb -- avdmanager -- sdkmanager -- emulator - -Check the [docs](./docs/) to know more about using the above binaries. +Currenty supported binaries: `adb`, `avdmanager`, `sdkmanager` and `emulator`. +Check the following docs to know more about usage of the above binaries: +- [Using emulator from CLI](./docs/use-emulator-from-command-line.md) \ No newline at end of file From f4640b87036605936be899d066fc304e6ad986a4 Mon Sep 17 00:00:00 2001 From: itsspriyansh Date: Tue, 3 Sep 2024 16:04:53 +0530 Subject: [PATCH 03/11] refactor --- README.md | 58 +++++-------------------------------------------------- 1 file changed, 5 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 530dbdc..cf53859 100644 --- a/README.md +++ b/README.md @@ -541,66 +541,18 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g ### Do more with Android SDK -The tool supports various Android SDK workflows, accessible through the following subcommands: - -1. [connect](./docs/subcommands/connect.md) -2. [list](./docs/subcommands/list.md) -3. [install](./docs/subcommands/install.md) -4. [uninstall](./docs/subcommands/uninstall.md) +The tool supports various Android SDK workflows, accessible through the following subcommands: `connect`, `list`, `install` and `uninstall`. #### Syntax -The following syntax is used for executing subcommands: - ```bash npx @nightwatch/mobile-helper android [flags|cliConfigs] ``` -#### 1. Connect a real device or launch an AVD - -```sh -npx @nightwatch/mobile-helper android connect [flags] -``` - - -| Flag | Description | -| ---------- | ------------------------------------- | -| --wireless | Connect a real device wirelessly | - -#### 2. List all the connected devices and installed AVDs - -```sh -npx @nightwatch/mobile-helper android list [flags] -``` - -| Flag | Description | -| ---------- | ------------------------------------------------------ | -| --device | Show a list of all the connected real devices and AVDs | -| --avd | Show a list of all the currently installed AVDs | - - -#### 3. Install an APK or create a new AVD - -```sh -npx @nightwatch/mobile-helper android install [flags] -``` - -| Flag | Description | -| ----- | ------------------------------------------ | -| --app | Install an APK on a real device or an AVD | -| --avd | Create a new AVD | - - -#### 4. Uninstall an app or delete an AVD - -```sh -npx @nightwatch/mobile-helper android uninstall [flags] -``` - -| Flag | Description | -| ----- | ---------------------------------------------- | -| --app | Uninstall an app from a real device or an AVD | -| --avd | Delete an AVD | +1. [Connect a real device or launch an AVD](./docs/subcommands/connect.md) +2. [List all the connected devices and installed AVDs](./docs/subcommands/list.md) +3. [Install an APK or create a new AVD](./docs/subcommands/install.md) +4. [Uninstall an app or delete an AVD](./docs/subcommands/uninstall.md) ### Run Android SDK binaries From c802da4722c79ab42661beb3b9c81d1fd6112061 Mon Sep 17 00:00:00 2001 From: itsspriyansh Date: Tue, 3 Sep 2024 14:44:10 +0530 Subject: [PATCH 04/11] add: subcommand instructions in readme --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cf53859..2003e84 100644 --- a/README.md +++ b/README.md @@ -541,18 +541,66 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to g ### Do more with Android SDK -The tool supports various Android SDK workflows, accessible through the following subcommands: `connect`, `list`, `install` and `uninstall`. +The tool supports various Android SDK workflows, accessible through the following subcommands: + +1. [connect](./docs/subcommands/connect.md) +2. [list](./docs/subcommands/list.md) +3. [install](./docs/subcommands/install.md) +4. [uninstall](./docs/subcommands/uninstall.md) #### Syntax +The following syntax is used for executing subcommands: + ```bash npx @nightwatch/mobile-helper android [flags|cliConfigs] ``` -1. [Connect a real device or launch an AVD](./docs/subcommands/connect.md) -2. [List all the connected devices and installed AVDs](./docs/subcommands/list.md) -3. [Install an APK or create a new AVD](./docs/subcommands/install.md) -4. [Uninstall an app or delete an AVD](./docs/subcommands/uninstall.md) +#### 1. Connect a real device or launch an AVD + +```sh +npx @nightwatch/mobile-helper android connect [flags] +``` + + +| Flag | Description | +| ---------- | ------------------------------------- | +| --wireless | Connect a real device wirelessly | + +#### 2. List all the connected devices and installed AVDs + +```sh +npx @nightwatch/mobile-helper android list [flags] +``` + +| Flag | Description | +| ---------- | ------------------------------------------------------ | +| --device | Show a list of all the connected real devices and AVDs | +| --avd | Show a list of all the currently installed AVDs | + + +#### 3. Install an APK or create a new AVD + +```sh +npx @nightwatch/mobile-helper android install [flags] +``` + +| Flag | Description | +| ----- | ------------------------------------------ | +| --app | Install an APK on a real device or an AVD | +| --avd | Create a new AVD | + + +#### 4. Uninstall an app or delete an AVD + +```sh +npx @nightwatch/mobile-helper android uninstall [flags] +``` + +| Flag | Description | +| ----- | ---------------------------------------------- | +| --app | Uninstall an app from a real device or an AVD | +| --avd | Delete an AVD | ### Run Android SDK binaries @@ -567,4 +615,4 @@ npx @nightwatch/mobile-helper android. [args] Currenty supported binaries: `adb`, `avdmanager`, `sdkmanager` and `emulator`. Check the following docs to know more about usage of the above binaries: -- [Using emulator from CLI](./docs/use-emulator-from-command-line.md) \ No newline at end of file +- [Using emulator from CLI](./docs/use-emulator-from-command-line.md) From cd8968ea259eb803f0a3a16527d6b3507700bcb7 Mon Sep 17 00:00:00 2001 From: itsspriyansh Date: Wed, 4 Sep 2024 13:48:39 +0530 Subject: [PATCH 05/11] tidy up readme --- README.md | 544 +------------------------------------ docs/mobile-app-testing.md | 330 ++++++++++++++++++++++ docs/mobile-web-testing.md | 201 ++++++++++++++ 3 files changed, 543 insertions(+), 532 deletions(-) create mode 100644 docs/mobile-app-testing.md create mode 100644 docs/mobile-web-testing.md diff --git a/README.md b/README.md index 2003e84..75e1ce9 100644 --- a/README.md +++ b/README.md @@ -2,542 +2,22 @@ Official Nightwatch helper-tool to easily setup all the requirements needed to get started with mobile testing using Nightwatch.js. -> **Note** -> Although this tool is designed with Nightwatch in mind, it can also be used as a standalone tool to download all the required Android SDKs needed to get the Android Emulator setup and running with Android v11. It can also download and install the latest version of Firefox browser on the Android Emulator. - ## Usage -- [Mobile web testing](#mobile-web-testing---android) - - [On Android](#mobile-web-testing---android) - - [On iOS](#mobile-web-testing---ios) -- [Mobile app testing](#mobile-app-testing---android) - - [On Android](#mobile-app-testing---android) - - [On iOS](#mobile-app-testing---ios) +- [Mobile web testing](./docs/mobile-web-testing.md) +- [Mobile app testing](./docs/mobile-app-testing.md) +- [Setup Android SDK]() - [Do more with Android SDK](#do-more-with-android-sdk) - [Run Android SDK binaries](#run-android-sdk-binaries) -### Mobile web testing - Android - -1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: - ```sh - npm i @nightwatch/mobile-helper --save-dev - ``` -2. From your project's root dir, run: - - ```sh - npx @nightwatch/mobile-helper android - ``` -3. Answer a few questions related to your requirements: - - image - - -4. It will verify if all the requirements are being met. -5. If some requirements are not being met, it will ask whether to download and setup those requirements: - - image - -6. Voila :tada: Your setup is now complete. (If something fails, follow the instructions and re-run the command.) -7. Add the following env configuration to your `nightwatch.conf.js` or `nightwatch.json` file: - ```js - "test_settings": { - // other envs above this line - 'android.chrome': { - desiredCapabilities: { - real_mobile: false, - avd: 'nightwatch-android-11', - browserName: 'chrome', - 'goog:chromeOptions': { - w3c: true, - args: [ - //'--no-sandbox', - //'--ignore-certificate-errors', - //'--allow-insecure-localhost', - //'--headless' - ], - androidPackage: 'com.android.chrome', - // add the device serial to run tests on, if multiple devices are online - // Run command: `$ANDROID_HOME/platform-tools/adb devices` - // androidDeviceSerial: '' - }, - }, - - webdriver: { - start_process: true, - server_path: 'chromedriver-mobile/chromedriver', - cli_args: [ - // --verbose - ] - } - }, - - 'android.firefox': { - desiredCapabilities: { - real_mobile: false, - avd: 'nightwatch-android-11', - browserName: 'firefox', - acceptInsecureCerts: true, - 'moz:firefoxOptions': { - args: [ - // '-headless', - // '-verbose' - ], - androidPackage: 'org.mozilla.firefox', - // add the device serial to run tests on, if multiple devices are online - // Run command: `$ANDROID_HOME/platform-tools/adb devices` - // androidDeviceSerial: 'ZD2222W62Y' - } - }, - webdriver: { - start_process: true, - server_path: '', - cli_args: [ - // very verbose geckodriver logs - // '-vv' - ] - } - }, - } - ``` -8. 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. - -9. 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: - ```sh - npx @nightwatch/mobile-helper android - ``` -10. Run your nightwatch tests on Android mobile browsers: - ```sh - # for firefox - npx nightwatch --env android.firefox - # for chrome - npx nightwatch --env android.chrome - ``` - -### Mobile web testing - iOS - -1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: - ```sh - npm i @nightwatch/mobile-helper --save-dev - ``` -2. From your project's root dir, run: - - ```sh - npx @nightwatch/mobile-helper ios - ``` -3. Answer a device related question: - - image - - -4. It will verify if all the requirements are being met. -5. If some requirements are not being met, follow the guide to setup those requirements. - - image - - -6. Great :tada: Your setup is now complete. (Re-run the command in the first step to verify.) - -7. 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 udid of the device to run tests on (necessary) - // Run command: `xcrun xctrace 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, - // To find the available deviceName/platformName 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 - ] - } - }, - } - ``` -8. (**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}' - ``` - -9. (**Optional**) Update the configurations : - - **Real Device** - - In your Nightwatch configuration, set `safari:deviceUDID` capability of `ios.real.safari` environment to *UDID* from the previous step. - - **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') capabilities of `ios.simulator.safari` environment in your Nightwatch configuration according to your preference. - -10. 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 --deviceId - # for real device (if updated the config in the previous step) - npx nightwatch --env ios.real.safari - ``` - -### Mobile app testing - Android - -#### Setup Android SDK requirements - -1. From your [Nightwatch](https://nightwatchjs.org) project's root dir, run: - ```sh - npx @nightwatch/mobile-helper android --appium - ``` -2. Answer a few questions related to your requirements: - - image - -3. It will verify if all the requirements are being met. -4. If some requirements are not being met, it will ask whether to download and setup those requirements: - - image - -5. And done! :tada: Your setup is now complete. (If something fails, follow the instructions and re-run the command.) - -#### Setup mobile app testing and run first sample test - -1. In your [Nightwatch](https://nightwatchjs.org) project, install Appium v2 as a dev-dependency: - ```sh - npm i appium@next --save-dev - ``` -2. Install Appium UiAutomator2 driver for Android: - ```sh - npx appium driver install uiautomator2 - ``` -3. Download the [sample wikipedia app](https://raw.githubusercontent.com/priyansh3133/wikipedia/main/wikipedia.apk) and save it in your project's root directory (alongside `nightwatch.conf.js` file). -4. Add the following env configuration to your `nightwatch.conf.js` file: - ```js - "test_settings": { - // other envs above this line - - app: { - selenium: { - start_process: true, - use_appium: true, - host: 'localhost', - port: 4723, - server_path: '', - // args to pass when starting the Appium server - cli_args: [ - // automatically download the required chromedriver - // '--allow-insecure=chromedriver_autodownload' - ], - // Remove below line if using Appium v1 - default_path_prefix: '' - }, - webdriver: { - timeout_options: { - timeout: 150000, - retry_attempts: 3 - }, - keep_alive: false, - start_process: false - } - }, - - 'app.android.emulator': { - extends: 'app', - 'desiredCapabilities': { - // More capabilities can be found at https://github.com/appium/appium-uiautomator2-driver#capabilities - browserName: null, - platformName: 'android', - // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. - // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` - // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. - 'appium:options': { - automationName: 'UiAutomator2', - // Android Virtual Device to run tests on - avd: 'nightwatch-android-11', - // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. - // Appium v2 does not support relative paths. - app: `${__dirname}/wikipedia.apk`, - appPackage: 'org.wikipedia', - appActivity: 'org.wikipedia.main.MainActivity', - appWaitActivity: 'org.wikipedia.onboarding.InitialOnboardingActivity', - // chromedriver executable to use for testing web-views in hybrid apps. - // add '.exe' at the end below (making it 'chromedriver.exe') if testing on windows. - chromedriverExecutable: `${__dirname}/chromedriver-mobile/chromedriver`, - newCommandTimeout: 0 - } - } - }, - - 'app.android.real': { - extends: 'app', - 'desiredCapabilities': { - // More capabilities can be found at https://github.com/appium/appium-uiautomator2-driver#capabilities - browserName: null, - platformName: 'android', - // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. - // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` - // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. - 'appium:options': { - automationName: 'UiAutomator2', - // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. - // Appium v2 does not support relative paths. - app: `${__dirname}/wikipedia.apk`, - appPackage: 'org.wikipedia', - appActivity: 'org.wikipedia.main.MainActivity', - appWaitActivity: 'org.wikipedia.onboarding.InitialOnboardingActivity', - // 'chromedriver' binary is required while testing hybrid mobile apps. - // - // Set `chromedriverExecutable` to '' to use binary from `chromedriver` NPM package (if installed). - // Or, put '--allow-insecure=chromedriver_autodownload' in `cli_args` property of `selenium` - // config (see 'app' env above) to automatically download the required version of chromedriver - // (delete `chromedriverExecutable` capability below in that case). - chromedriverExecutable: '', - newCommandTimeout: 0, - // add device id of the device to run tests on, if multiple devices are online - // Run command: `$ANDROID_HOME/platform-tools/adb devices` to get all connected devices - // udid: '', - } - } - }, - } - ``` -5. Add the following sample test to your test-suite (`test/wikipedia-android.js`): - ```js - describe('Wikipedia Android app test', function() { - before(function(app) { - app.click('id', 'org.wikipedia:id/fragment_onboarding_skip_button'); - }); - - it('Search for BrowserStack', async function(app) { - app - .click('id', 'org.wikipedia:id/search_container') - .sendKeys('id', 'org.wikipedia:id/search_src_text', 'browserstack') - .click({selector: 'org.wikipedia:id/page_list_item_title', locateStrategy: 'id', index: 0}) - .waitUntil(async function() { - // wait for webview context to be available - const contexts = await this.appium.getContexts(); - - return contexts.includes('WEBVIEW_org.wikipedia'); - }) - .appium.setContext('WEBVIEW_org.wikipedia') - .assert.textEquals('.pcs-edit-section-title', 'BrowserStack'); // command run in webview context - }); - }); - ``` -6. If testing on real-device: - 1. [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. - 2. Make sure latest version of Chrome browser is installed on your Android device. If not, install from Google Play Store. - 3. Make sure latest version of `chromedriver` NPM package is installed in your project. If not, install by running: - ```sh - npm i chromedriver@latest --save-dev - ``` -7. 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: - ```sh - npx @nightwatch/mobile-helper android --appium - ``` -8. Run your Nightwatch tests on Android emulator/real device: - ```sh - # test on emulator (assuming test saved as `test/wikipedia-android.js`) - npx nightwatch test/wikipedia-android.js --env app.android.emulator - # test on real-device (assuming test saved as `test/wikipedia-android.js`) - npx nightwatch test/wikipedia-android.js --env app.android.real - ``` - -### Mobile app testing - iOS - -#### Setup iOS SDK requirements - -1. From your [Nightwatch](https://nightwatchjs.org) project's root dir, run: - ```sh - npx @nightwatch/mobile-helper ios --setup - ``` -2. Answer a device related question: - - image - -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. - - image - -5. And done! :tada: Your setup is now complete. (Re-run the command in the first step to verify.) - -#### Setup mobile app testing and run first sample test - -1. In your [Nightwatch](https://nightwatchjs.org) project, install Appium v2 as a dev-dependency: - ```sh - npm i appium@next --save-dev - ``` -2. Install Appium XCUITest driver for iOS: - ```sh - npx appium driver install xcuitest - ``` -3. Download the [sample wikipedia app](https://raw.githubusercontent.com/priyansh3133/wikipedia/main/wikipedia.zip) and save it in your project's root directory (alongside `nightwatch.conf.js` file). -4. Add the following env configuration to your `nightwatch.conf.js` file (skip 'app' env if already followed Android setup above): - ```js - "test_settings": { - // other envs above this line - - app: { - selenium: { - start_process: true, - use_appium: true, - host: 'localhost', - port: 4723, - server_path: '', - // args to pass when starting the Appium server - cli_args: [ - // automatically download the required chromedriver - // '--allow-insecure=chromedriver_autodownload' - ], - // Remove below line if using Appium v1 - default_path_prefix: '' - }, - webdriver: { - timeout_options: { - timeout: 150000, - retry_attempts: 3 - }, - keep_alive: false, - start_process: false - } - }, - - 'app.ios.simulator': { - extends: 'app', - 'desiredCapabilities': { - // More capabilities can be found at https://github.com/appium/appium-xcuitest-driver#capabilities - browserName: null, - platformName: 'ios', - // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. - // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` - // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. - 'appium:options': { - automationName: 'XCUITest', - // platformVersion: '15.5', - deviceName: 'iPhone 13', - // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. - // Appium v2 does not support relative paths. - app: `${__dirname}/wikipedia.zip`, - bundleId: 'org.wikimedia.wikipedia', - newCommandTimeout: 0 - } - } - }, - - 'app.ios.real': { - extends: 'app', - 'desiredCapabilities': { - // More capabilities can be found at https://github.com/appium/appium-xcuitest-driver#capabilities - browserName: null, - platformName: 'ios', - // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. - // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` - // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. - 'appium:options': { - automationName: 'XCUITest', - // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. - // Appium v2 does not support relative paths. - app: `${__dirname}/wikipedia.zip`, - bundleId: 'org.wikimedia.wikipedia', - newCommandTimeout: 0, - // add udid of the device to run tests on. Or, pass the id to `--deviceId` flag when running tests. - // device id could be retrieved from Xcode > Window > "Devices and Simulators" window. - // udid: '00008030-00024C2C3453402E' - } - } - }, - } - ``` -5. Add the following sample test to your test-suite (`test/wikipedia-ios.js`): - ```js - describe('Wikipedia iOS app test', function() { - before(function(app) { - app.click('xpath', '//XCUIElementTypeButton[@name="Skip"]'); - }); - - it('Search for BrowserStack', async function(app) { - app - .useXpath() - .click('//XCUIElementTypeSearchField[@name="Search Wikipedia"]') - .sendKeys('//XCUIElementTypeSearchField[@name="Search Wikipedia"]', 'browserstack') - .click('//XCUIElementTypeStaticText[@name="BrowserStack"]') - .waitUntil(async function() { - // wait for webview context to be available - const contexts = await this.appium.getContexts(); - - return contexts.length > 1; - }, 5000) - .perform(async function() { - // switch to webview context - const contexts = await this.appium.getContexts(); - - await this.appium.setContext(contexts[1]); - }) - .useCss() - .assert.textEquals('.pcs-edit-section-title', 'BrowserStack'); // command run in webview context - }); - }); - ``` -6. (**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}' - ``` - -7. (**Optional**) Update the configurations : - - **Real Device** - - In your Nightwatch configuration, set `udid` property of `appium:options` capability inside `app.ios.real` environment to *UDID* from the previous step. - - **Simulators** - - Run the following command to get a list of simulators: - ```sh - xcrun simctl list devices - ``` - And then update `deviceName` (eg: 'iPhone 13') and `platformVersion` (eg: '15.0') properties of `appium:options` capability, defined for `app.ios.simulator` environment in your Nightwatch configuration, according to your preference. - -8. Run your Nightwatch tests on iOS simulator/real device: - ```sh - # test on simulator (assuming test saved as `test/wikipedia-ios.js`) - npx nightwatch test/wikipedia-ios.js --env app.ios.simulator - - # test on real-device (assuming test saved as `test/wikipedia-ios.js`) - npx nightwatch test/wikipedia-ios.js --env app.ios.real - ``` +### Setup Android SDK + +Run the below command to download all the required Android SDKs needed to get the Android Emulator setup and running with Android v11: + + +```sh +npx @nightwatch/mobile-helper android --standalone +``` ### Do more with Android SDK @@ -614,5 +94,5 @@ npx @nightwatch/mobile-helper android. [args] Currenty supported binaries: `adb`, `avdmanager`, `sdkmanager` and `emulator`. -Check the following docs to know more about usage of the above binaries: +Check the following docs to know more about the usage of the above mentioned binaries: - [Using emulator from CLI](./docs/use-emulator-from-command-line.md) diff --git a/docs/mobile-app-testing.md b/docs/mobile-app-testing.md new file mode 100644 index 0000000..cd5d5dc --- /dev/null +++ b/docs/mobile-app-testing.md @@ -0,0 +1,330 @@ +## Mobile app testing + +- [On Android](#mobile-app-testing---android) +- [On iOS](#mobile-app-testing---ios) + +### Mobile app testing - Android + +#### Setup Android SDK requirements + +1. From your [Nightwatch](https://nightwatchjs.org) project's root dir, run: + ```sh + npx @nightwatch/mobile-helper android --appium + ``` +2. Answer a few questions related to your requirements: + + image + +3. It will verify if all the requirements are being met. +4. If some requirements are not being met, it will ask whether to download and setup those requirements: + + image + +5. And done! :tada: Your setup is now complete. (If something fails, follow the instructions and re-run the command.) + +#### Setup mobile app testing and run first sample test + +1. In your [Nightwatch](https://nightwatchjs.org) project, install Appium v2 as a dev-dependency: + ```sh + npm i appium@next --save-dev + ``` +2. Install Appium UiAutomator2 driver for Android: + ```sh + npx appium driver install uiautomator2 + ``` +3. Download the [sample wikipedia app](https://raw.githubusercontent.com/priyansh3133/wikipedia/main/wikipedia.apk) and save it in your project's root directory (alongside `nightwatch.conf.js` file). +4. Add the following env configuration to your `nightwatch.conf.js` file: + ```js + "test_settings": { + // other envs above this line + + app: { + selenium: { + start_process: true, + use_appium: true, + host: 'localhost', + port: 4723, + server_path: '', + // args to pass when starting the Appium server + cli_args: [ + // automatically download the required chromedriver + // '--allow-insecure=chromedriver_autodownload' + ], + // Remove below line if using Appium v1 + default_path_prefix: '' + }, + webdriver: { + timeout_options: { + timeout: 150000, + retry_attempts: 3 + }, + keep_alive: false, + start_process: false + } + }, + + 'app.android.emulator': { + extends: 'app', + 'desiredCapabilities': { + // More capabilities can be found at https://github.com/appium/appium-uiautomator2-driver#capabilities + browserName: null, + platformName: 'android', + // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. + // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` + // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. + 'appium:options': { + automationName: 'UiAutomator2', + // Android Virtual Device to run tests on + avd: 'nightwatch-android-11', + // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. + // Appium v2 does not support relative paths. + app: `${__dirname}/wikipedia.apk`, + appPackage: 'org.wikipedia', + appActivity: 'org.wikipedia.main.MainActivity', + appWaitActivity: 'org.wikipedia.onboarding.InitialOnboardingActivity', + // chromedriver executable to use for testing web-views in hybrid apps. + // add '.exe' at the end below (making it 'chromedriver.exe') if testing on windows. + chromedriverExecutable: `${__dirname}/chromedriver-mobile/chromedriver`, + newCommandTimeout: 0 + } + } + }, + + 'app.android.real': { + extends: 'app', + 'desiredCapabilities': { + // More capabilities can be found at https://github.com/appium/appium-uiautomator2-driver#capabilities + browserName: null, + platformName: 'android', + // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. + // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` + // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. + 'appium:options': { + automationName: 'UiAutomator2', + // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. + // Appium v2 does not support relative paths. + app: `${__dirname}/wikipedia.apk`, + appPackage: 'org.wikipedia', + appActivity: 'org.wikipedia.main.MainActivity', + appWaitActivity: 'org.wikipedia.onboarding.InitialOnboardingActivity', + // 'chromedriver' binary is required while testing hybrid mobile apps. + // + // Set `chromedriverExecutable` to '' to use binary from `chromedriver` NPM package (if installed). + // Or, put '--allow-insecure=chromedriver_autodownload' in `cli_args` property of `selenium` + // config (see 'app' env above) to automatically download the required version of chromedriver + // (delete `chromedriverExecutable` capability below in that case). + chromedriverExecutable: '', + newCommandTimeout: 0, + // add device id of the device to run tests on, if multiple devices are online + // Run command: `$ANDROID_HOME/platform-tools/adb devices` to get all connected devices + // udid: '', + } + } + }, + } + ``` +5. Add the following sample test to your test-suite (`test/wikipedia-android.js`): + ```js + describe('Wikipedia Android app test', function() { + before(function(app) { + app.click('id', 'org.wikipedia:id/fragment_onboarding_skip_button'); + }); + + it('Search for BrowserStack', async function(app) { + app + .click('id', 'org.wikipedia:id/search_container') + .sendKeys('id', 'org.wikipedia:id/search_src_text', 'browserstack') + .click({selector: 'org.wikipedia:id/page_list_item_title', locateStrategy: 'id', index: 0}) + .waitUntil(async function() { + // wait for webview context to be available + const contexts = await this.appium.getContexts(); + + return contexts.includes('WEBVIEW_org.wikipedia'); + }) + .appium.setContext('WEBVIEW_org.wikipedia') + .assert.textEquals('.pcs-edit-section-title', 'BrowserStack'); // command run in webview context + }); + }); + ``` +6. If testing on real-device: + 1. [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. + 2. Make sure latest version of Chrome browser is installed on your Android device. If not, install from Google Play Store. + 3. Make sure latest version of `chromedriver` NPM package is installed in your project. If not, install by running: + ```sh + npm i chromedriver@latest --save-dev + ``` +7. 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: + ```sh + npx @nightwatch/mobile-helper android --appium + ``` +8. Run your Nightwatch tests on Android emulator/real device: + ```sh + # test on emulator (assuming test saved as `test/wikipedia-android.js`) + npx nightwatch test/wikipedia-android.js --env app.android.emulator + # test on real-device (assuming test saved as `test/wikipedia-android.js`) + npx nightwatch test/wikipedia-android.js --env app.android.real + ``` + +### Mobile app testing - iOS + +#### Setup iOS SDK requirements + +1. From your [Nightwatch](https://nightwatchjs.org) project's root dir, run: + ```sh + npx @nightwatch/mobile-helper ios --setup + ``` +2. Answer a device related question: + + image + +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. + + image + +5. And done! :tada: Your setup is now complete. (Re-run the command in the first step to verify.) + +#### Setup mobile app testing and run first sample test + +1. In your [Nightwatch](https://nightwatchjs.org) project, install Appium v2 as a dev-dependency: + ```sh + npm i appium@next --save-dev + ``` +2. Install Appium XCUITest driver for iOS: + ```sh + npx appium driver install xcuitest + ``` +3. Download the [sample wikipedia app](https://raw.githubusercontent.com/priyansh3133/wikipedia/main/wikipedia.zip) and save it in your project's root directory (alongside `nightwatch.conf.js` file). +4. Add the following env configuration to your `nightwatch.conf.js` file (skip 'app' env if already followed Android setup above): + ```js + "test_settings": { + // other envs above this line + + app: { + selenium: { + start_process: true, + use_appium: true, + host: 'localhost', + port: 4723, + server_path: '', + // args to pass when starting the Appium server + cli_args: [ + // automatically download the required chromedriver + // '--allow-insecure=chromedriver_autodownload' + ], + // Remove below line if using Appium v1 + default_path_prefix: '' + }, + webdriver: { + timeout_options: { + timeout: 150000, + retry_attempts: 3 + }, + keep_alive: false, + start_process: false + } + }, + + 'app.ios.simulator': { + extends: 'app', + 'desiredCapabilities': { + // More capabilities can be found at https://github.com/appium/appium-xcuitest-driver#capabilities + browserName: null, + platformName: 'ios', + // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. + // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` + // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. + 'appium:options': { + automationName: 'XCUITest', + // platformVersion: '15.5', + deviceName: 'iPhone 13', + // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. + // Appium v2 does not support relative paths. + app: `${__dirname}/wikipedia.zip`, + bundleId: 'org.wikimedia.wikipedia', + newCommandTimeout: 0 + } + } + }, + + 'app.ios.real': { + extends: 'app', + 'desiredCapabilities': { + // More capabilities can be found at https://github.com/appium/appium-xcuitest-driver#capabilities + browserName: null, + platformName: 'ios', + // `appium:options` is not natively supported in Appium v1, but works with Nightwatch. + // If copying these capabilities elsewhere while using Appium v1, make sure to remove `appium:options` + // and add `appium:` prefix to each one of its capabilities, e.g. change 'app' to 'appium:app'. + 'appium:options': { + automationName: 'XCUITest', + // While Appium v1 supports relative paths, it's more safe to use absolute paths instead. + // Appium v2 does not support relative paths. + app: `${__dirname}/wikipedia.zip`, + bundleId: 'org.wikimedia.wikipedia', + newCommandTimeout: 0, + // add udid of the device to run tests on. Or, pass the id to `--deviceId` flag when running tests. + // device id could be retrieved from Xcode > Window > "Devices and Simulators" window. + // udid: '00008030-00024C2C3453402E' + } + } + }, + } + ``` +5. Add the following sample test to your test-suite (`test/wikipedia-ios.js`): + ```js + describe('Wikipedia iOS app test', function() { + before(function(app) { + app.click('xpath', '//XCUIElementTypeButton[@name="Skip"]'); + }); + + it('Search for BrowserStack', async function(app) { + app + .useXpath() + .click('//XCUIElementTypeSearchField[@name="Search Wikipedia"]') + .sendKeys('//XCUIElementTypeSearchField[@name="Search Wikipedia"]', 'browserstack') + .click('//XCUIElementTypeStaticText[@name="BrowserStack"]') + .waitUntil(async function() { + // wait for webview context to be available + const contexts = await this.appium.getContexts(); + + return contexts.length > 1; + }, 5000) + .perform(async function() { + // switch to webview context + const contexts = await this.appium.getContexts(); + + await this.appium.setContext(contexts[1]); + }) + .useCss() + .assert.textEquals('.pcs-edit-section-title', 'BrowserStack'); // command run in webview context + }); + }); + ``` +6. (**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}' + ``` + +7. (**Optional**) Update the configurations : + + **Real Device** + + In your Nightwatch configuration, set `udid` property of `appium:options` capability inside `app.ios.real` environment to *UDID* from the previous step. + + **Simulators** + + Run the following command to get a list of simulators: + ```sh + xcrun simctl list devices + ``` + And then update `deviceName` (eg: 'iPhone 13') and `platformVersion` (eg: '15.0') properties of `appium:options` capability, defined for `app.ios.simulator` environment in your Nightwatch configuration, according to your preference. + +8. Run your Nightwatch tests on iOS simulator/real device: + ```sh + # test on simulator (assuming test saved as `test/wikipedia-ios.js`) + npx nightwatch test/wikipedia-ios.js --env app.ios.simulator + + # test on real-device (assuming test saved as `test/wikipedia-ios.js`) + npx nightwatch test/wikipedia-ios.js --env app.ios.real + ``` \ No newline at end of file diff --git a/docs/mobile-web-testing.md b/docs/mobile-web-testing.md new file mode 100644 index 0000000..13a208d --- /dev/null +++ b/docs/mobile-web-testing.md @@ -0,0 +1,201 @@ +## Mobile web testing + + - [On Android](#mobile-web-testing---android) + - [On iOS](#mobile-web-testing---ios) + +### Mobile web testing - Android + +1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: + ```sh + npm i @nightwatch/mobile-helper --save-dev + ``` +2. From your project's root dir, run: + + ```sh + npx @nightwatch/mobile-helper android + ``` +3. Answer a few questions related to your requirements: + + image + + +4. It will verify if all the requirements are being met. +5. If some requirements are not being met, it will ask whether to download and setup those requirements: + + image + +6. Voila :tada: Your setup is now complete. (If something fails, follow the instructions and re-run the command.) +7. Add the following env configuration to your `nightwatch.conf.js` or `nightwatch.json` file: + ```js + "test_settings": { + // other envs above this line + 'android.chrome': { + desiredCapabilities: { + real_mobile: false, + avd: 'nightwatch-android-11', + browserName: 'chrome', + 'goog:chromeOptions': { + w3c: true, + args: [ + //'--no-sandbox', + //'--ignore-certificate-errors', + //'--allow-insecure-localhost', + //'--headless' + ], + androidPackage: 'com.android.chrome', + // add the device serial to run tests on, if multiple devices are online + // Run command: `$ANDROID_HOME/platform-tools/adb devices` + // androidDeviceSerial: '' + }, + }, + + webdriver: { + start_process: true, + server_path: 'chromedriver-mobile/chromedriver', + cli_args: [ + // --verbose + ] + } + }, + + 'android.firefox': { + desiredCapabilities: { + real_mobile: false, + avd: 'nightwatch-android-11', + browserName: 'firefox', + acceptInsecureCerts: true, + 'moz:firefoxOptions': { + args: [ + // '-headless', + // '-verbose' + ], + androidPackage: 'org.mozilla.firefox', + // add the device serial to run tests on, if multiple devices are online + // Run command: `$ANDROID_HOME/platform-tools/adb devices` + // androidDeviceSerial: 'ZD2222W62Y' + } + }, + webdriver: { + start_process: true, + server_path: '', + cli_args: [ + // very verbose geckodriver logs + // '-vv' + ] + } + }, + } + ``` +8. 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. + +9. 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: + ```sh + npx @nightwatch/mobile-helper android + ``` +10. Run your nightwatch tests on Android mobile browsers: + ```sh + # for firefox + npx nightwatch --env android.firefox + # for chrome + npx nightwatch --env android.chrome + ``` + +### Mobile web testing - iOS + +1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: + ```sh + npm i @nightwatch/mobile-helper --save-dev + ``` +2. From your project's root dir, run: + + ```sh + npx @nightwatch/mobile-helper ios + ``` +3. Answer a device related question: + + image + + +4. It will verify if all the requirements are being met. +5. If some requirements are not being met, follow the guide to setup those requirements. + + image + + +6. Great :tada: Your setup is now complete. (Re-run the command in the first step to verify.) + +7. 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 udid of the device to run tests on (necessary) + // Run command: `xcrun xctrace 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, + // To find the available deviceName/platformName 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 + ] + } + }, + } + ``` +8. (**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}' + ``` + +9. (**Optional**) Update the configurations : + + **Real Device** + + In your Nightwatch configuration, set `safari:deviceUDID` capability of `ios.real.safari` environment to *UDID* from the previous step. + + **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') capabilities of `ios.simulator.safari` environment in your Nightwatch configuration according to your preference. + +10. 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 --deviceId + # for real device (if updated the config in the previous step) + npx nightwatch --env ios.real.safari + ``` \ No newline at end of file From 89e508c7bbd4b0351376ad22f1b070d31c947235 Mon Sep 17 00:00:00 2001 From: Priyansh Garg Date: Thu, 12 Sep 2024 22:58:42 +0530 Subject: [PATCH 06/11] Update mobile-web-testing.md --- docs/mobile-web-testing.md | 46 +++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/docs/mobile-web-testing.md b/docs/mobile-web-testing.md index 13a208d..e4c0a35 100644 --- a/docs/mobile-web-testing.md +++ b/docs/mobile-web-testing.md @@ -1,24 +1,38 @@ -## Mobile web testing +# Mobile web testing - - [On Android](#mobile-web-testing---android) - - [On iOS](#mobile-web-testing---ios) +With Nightwatch.js, users can now test websites on real mobile browsers, along with the desktop browsers. -### Mobile web testing - Android +For new users, the setup is pretty easy. To set up a new Nightwatch.js project with support for mobile-web testing out-of-the-box, run: + +```sh +npm init nightwatch@latest +``` + +and answer the questions that follow. And that's it! + +For existing Nightwatch.js users, the setup for mobile-web testing can be done by following the steps below: + +* [Setup on Android](#android) +* [Setup on iOS](#ios) + +## Android 1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: + ```sh npm i @nightwatch/mobile-helper --save-dev ``` + 2. From your project's root dir, run: ```sh npx @nightwatch/mobile-helper android ``` + 3. Answer a few questions related to your requirements: image - 4. It will verify if all the requirements are being met. 5. If some requirements are not being met, it will ask whether to download and setup those requirements: @@ -26,6 +40,7 @@ 6. Voila :tada: Your setup is now complete. (If something fails, follow the instructions and re-run the command.) 7. Add the following env configuration to your `nightwatch.conf.js` or `nightwatch.json` file: + ```js "test_settings": { // other envs above this line @@ -86,16 +101,20 @@ }, } ``` + 8. 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. 9. 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: + ```sh npx @nightwatch/mobile-helper android ``` + 10. Run your nightwatch tests on Android mobile browsers: + ```sh # for firefox npx nightwatch --env android.firefox @@ -103,31 +122,33 @@ npx nightwatch --env android.chrome ``` -### Mobile web testing - iOS +### iOS 1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: + ```sh npm i @nightwatch/mobile-helper --save-dev ``` + 2. From your project's root dir, run: ```sh npx @nightwatch/mobile-helper ios ``` + 3. Answer a device related question: image - 4. It will verify if all the requirements are being met. 5. If some requirements are not being met, follow the guide to setup those requirements. image - 6. Great :tada: Your setup is now complete. (Re-run the command in the first step to verify.) 7. Add the following env configuration to your `nightwatch.conf.js` or `nightwatch.json` file: + ```js "test_settings": { // other envs above this line @@ -170,7 +191,9 @@ }, } ``` + 8. (**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}' ``` @@ -182,14 +205,17 @@ In your Nightwatch configuration, set `safari:deviceUDID` capability of `ios.real.safari` environment to *UDID* from the previous step. **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') capabilities of `ios.simulator.safari` environment in your Nightwatch configuration according to your preference. 10. Run your nightwatch tests on Android mobile browsers: + ```sh # for simulators npx nightwatch --env ios.simulator.safari @@ -198,4 +224,4 @@ npx nightwatch --env ios.real.safari --deviceId # for real device (if updated the config in the previous step) npx nightwatch --env ios.real.safari - ``` \ No newline at end of file + ``` From e32b3766602bc521d3f7f30019aedf8dd5334bb3 Mon Sep 17 00:00:00 2001 From: Priyansh Garg Date: Thu, 12 Sep 2024 23:19:21 +0530 Subject: [PATCH 07/11] Update mobile-app-testing.md. --- docs/mobile-app-testing.md | 72 ++++++++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 15 deletions(-) diff --git a/docs/mobile-app-testing.md b/docs/mobile-app-testing.md index cd5d5dc..e22677f 100644 --- a/docs/mobile-app-testing.md +++ b/docs/mobile-app-testing.md @@ -1,16 +1,29 @@ -## Mobile app testing +# Mobile app testing -- [On Android](#mobile-app-testing---android) -- [On iOS](#mobile-app-testing---ios) +Nightwatch.js now supports testing of native mobile applications via Appium, on both Android and iOS devices. For more details, follow this [guide](https://nightwatchjs.org/guide/mobile-app-testing/introduction.html). -### Mobile app testing - Android +If you're setting up Nightwatch.js for the first time in your project, the setup is pretty straightforward. To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box, go to your project root directory, run the Nightwatch init command and answer the questions that follow. -#### Setup Android SDK requirements +```sh +cd path/to/project/root +npm init nightwatch@latest . +``` + +For existing Nightwatch.js project, the setup for mobile app testing can be done by following the steps below: + +* [Setup for Android](#android) +* [Setup for iOS](#ios) + +## Android + +### Setup Android SDK requirements 1. From your [Nightwatch](https://nightwatchjs.org) project's root dir, run: + ```sh npx @nightwatch/mobile-helper android --appium ``` + 2. Answer a few questions related to your requirements: image @@ -22,18 +35,23 @@ 5. And done! :tada: Your setup is now complete. (If something fails, follow the instructions and re-run the command.) -#### Setup mobile app testing and run first sample test +### Setup mobile app testing and run first sample test 1. In your [Nightwatch](https://nightwatchjs.org) project, install Appium v2 as a dev-dependency: + ```sh npm i appium@next --save-dev ``` + 2. Install Appium UiAutomator2 driver for Android: + ```sh npx appium driver install uiautomator2 ``` + 3. Download the [sample wikipedia app](https://raw.githubusercontent.com/priyansh3133/wikipedia/main/wikipedia.apk) and save it in your project's root directory (alongside `nightwatch.conf.js` file). 4. Add the following env configuration to your `nightwatch.conf.js` file: + ```js "test_settings": { // other envs above this line @@ -44,14 +62,15 @@ use_appium: true, host: 'localhost', port: 4723, - server_path: '', // args to pass when starting the Appium server cli_args: [ // automatically download the required chromedriver // '--allow-insecure=chromedriver_autodownload' ], // Remove below line if using Appium v1 - default_path_prefix: '' + default_path_prefix: '', + // Uncomment below line if Appium is installed globally + // server_path: 'appium' }, webdriver: { timeout_options: { @@ -123,7 +142,9 @@ }, } ``` + 5. Add the following sample test to your test-suite (`test/wikipedia-android.js`): + ```js describe('Wikipedia Android app test', function() { before(function(app) { @@ -146,18 +167,24 @@ }); }); ``` + 6. If testing on real-device: 1. [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. 2. Make sure latest version of Chrome browser is installed on your Android device. If not, install from Google Play Store. 3. Make sure latest version of `chromedriver` NPM package is installed in your project. If not, install by running: + ```sh npm i chromedriver@latest --save-dev ``` + 7. 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: + ```sh npx @nightwatch/mobile-helper android --appium ``` + 8. Run your Nightwatch tests on Android emulator/real device: + ```sh # test on emulator (assuming test saved as `test/wikipedia-android.js`) npx nightwatch test/wikipedia-android.js --env app.android.emulator @@ -165,14 +192,16 @@ npx nightwatch test/wikipedia-android.js --env app.android.real ``` -### Mobile app testing - iOS +## iOS -#### Setup iOS SDK requirements +### Setup iOS SDK requirements 1. From your [Nightwatch](https://nightwatchjs.org) project's root dir, run: + ```sh npx @nightwatch/mobile-helper ios --setup ``` + 2. Answer a device related question: image @@ -184,18 +213,23 @@ 5. And done! :tada: Your setup is now complete. (Re-run the command in the first step to verify.) -#### Setup mobile app testing and run first sample test +### Setup mobile app testing and run first sample test 1. In your [Nightwatch](https://nightwatchjs.org) project, install Appium v2 as a dev-dependency: + ```sh npm i appium@next --save-dev ``` + 2. Install Appium XCUITest driver for iOS: + ```sh npx appium driver install xcuitest ``` + 3. Download the [sample wikipedia app](https://raw.githubusercontent.com/priyansh3133/wikipedia/main/wikipedia.zip) and save it in your project's root directory (alongside `nightwatch.conf.js` file). 4. Add the following env configuration to your `nightwatch.conf.js` file (skip 'app' env if already followed Android setup above): + ```js "test_settings": { // other envs above this line @@ -206,14 +240,15 @@ use_appium: true, host: 'localhost', port: 4723, - server_path: '', // args to pass when starting the Appium server cli_args: [ // automatically download the required chromedriver // '--allow-insecure=chromedriver_autodownload' ], // Remove below line if using Appium v1 - default_path_prefix: '' + default_path_prefix: '', + // Uncomment below line if Appium is installed globally + // server_path: 'appium' }, webdriver: { timeout_options: { @@ -271,7 +306,9 @@ }, } ``` + 5. Add the following sample test to your test-suite (`test/wikipedia-ios.js`): + ```js describe('Wikipedia iOS app test', function() { before(function(app) { @@ -301,7 +338,9 @@ }); }); ``` + 6. (**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}' ``` @@ -313,18 +352,21 @@ In your Nightwatch configuration, set `udid` property of `appium:options` capability inside `app.ios.real` environment to *UDID* from the previous step. **Simulators** - + Run the following command to get a list of simulators: + ```sh xcrun simctl list devices ``` + And then update `deviceName` (eg: 'iPhone 13') and `platformVersion` (eg: '15.0') properties of `appium:options` capability, defined for `app.ios.simulator` environment in your Nightwatch configuration, according to your preference. 8. Run your Nightwatch tests on iOS simulator/real device: + ```sh # test on simulator (assuming test saved as `test/wikipedia-ios.js`) npx nightwatch test/wikipedia-ios.js --env app.ios.simulator # test on real-device (assuming test saved as `test/wikipedia-ios.js`) npx nightwatch test/wikipedia-ios.js --env app.ios.real - ``` \ No newline at end of file + ``` From 51322fdea76699be20f2fffb055688043d96c69b Mon Sep 17 00:00:00 2001 From: Priyansh Garg Date: Thu, 12 Sep 2024 23:22:53 +0530 Subject: [PATCH 08/11] mobile-app-testing.md updates. --- docs/mobile-app-testing.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/mobile-app-testing.md b/docs/mobile-app-testing.md index e22677f..cb612d0 100644 --- a/docs/mobile-app-testing.md +++ b/docs/mobile-app-testing.md @@ -2,12 +2,14 @@ Nightwatch.js now supports testing of native mobile applications via Appium, on both Android and iOS devices. For more details, follow this [guide](https://nightwatchjs.org/guide/mobile-app-testing/introduction.html). -If you're setting up Nightwatch.js for the first time in your project, the setup is pretty straightforward. To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box, go to your project root directory, run the Nightwatch init command and answer the questions that follow. +If you're setting up Nightwatch.js for the first time in your project, the setup is pretty straightforward. -```sh -cd path/to/project/root -npm init nightwatch@latest . -``` +To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box: + +* Go to your project root directory: `cd path/to/project/root` +* Run the Nightwatch init command: `npm init nightwatch@latest` + +and answer the questions that follow. That's it! For existing Nightwatch.js project, the setup for mobile app testing can be done by following the steps below: From 580127b3f4f657c5943e427798ca362dd387eca9 Mon Sep 17 00:00:00 2001 From: Priyansh Garg Date: Thu, 12 Sep 2024 23:25:01 +0530 Subject: [PATCH 09/11] More usage updates. --- docs/mobile-app-testing.md | 4 +--- docs/mobile-web-testing.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/mobile-app-testing.md b/docs/mobile-app-testing.md index cb612d0..7444444 100644 --- a/docs/mobile-app-testing.md +++ b/docs/mobile-app-testing.md @@ -2,9 +2,7 @@ Nightwatch.js now supports testing of native mobile applications via Appium, on both Android and iOS devices. For more details, follow this [guide](https://nightwatchjs.org/guide/mobile-app-testing/introduction.html). -If you're setting up Nightwatch.js for the first time in your project, the setup is pretty straightforward. - -To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box: +If you're setting up Nightwatch.js for the first time in your project, the setup is pretty straightforward. To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box: * Go to your project root directory: `cd path/to/project/root` * Run the Nightwatch init command: `npm init nightwatch@latest` diff --git a/docs/mobile-web-testing.md b/docs/mobile-web-testing.md index e4c0a35..ee0977b 100644 --- a/docs/mobile-web-testing.md +++ b/docs/mobile-web-testing.md @@ -122,7 +122,7 @@ For existing Nightwatch.js users, the setup for mobile-web testing can be done b npx nightwatch --env android.chrome ``` -### iOS +## iOS 1. In your [Nightwatch](https://nightwatchjs.org) project, install `@nightwatch/mobile-helper` as a dev-dependency: From 2ec901f75471cd00036e0e08eec81fc895b58820 Mon Sep 17 00:00:00 2001 From: Priyansh Garg Date: Thu, 12 Sep 2024 23:26:59 +0530 Subject: [PATCH 10/11] More updates to mobile-app usage. --- docs/mobile-app-testing.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/mobile-app-testing.md b/docs/mobile-app-testing.md index 7444444..1865e84 100644 --- a/docs/mobile-app-testing.md +++ b/docs/mobile-app-testing.md @@ -2,10 +2,15 @@ Nightwatch.js now supports testing of native mobile applications via Appium, on both Android and iOS devices. For more details, follow this [guide](https://nightwatchjs.org/guide/mobile-app-testing/introduction.html). -If you're setting up Nightwatch.js for the first time in your project, the setup is pretty straightforward. To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box: +If you're setting up Nightwatch.js for the first time in your project, the process is pretty straightforward. To setup Nightwatch.js in your new/existing project with support for mobile app testing out-of-the-box, run: -* Go to your project root directory: `cd path/to/project/root` -* Run the Nightwatch init command: `npm init nightwatch@latest` +```sh +# go to your project root directory +cd path/to/project/root + +# run the init command +npm init nightwatch@latest . +``` and answer the questions that follow. That's it! From 70d791baed526c8f59bea022b9bc72248eed8128 Mon Sep 17 00:00:00 2001 From: Priyansh Garg Date: Thu, 12 Sep 2024 23:55:35 +0530 Subject: [PATCH 11/11] Update README.md --- README.md | 86 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 57 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 75e1ce9..97f7328 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,52 @@ # @nightwatch/mobile-helper -Official Nightwatch helper-tool to easily setup all the requirements needed to get started with mobile testing using Nightwatch.js. +Official Nightwatch tool to help easily setup all the requirements needed to get started with mobile testing in [Nightwatch.js](https://nightwatchjs.org). Nightwatch.js supports web and native app testing in both Android and iOS devices. + +**BONUS:** For Android folks, there's much more this tool has to offer now apart for setting up requirements for testing: + +* Setup fully functional Android Emulator environment in a matter of minutes (without downloading Android Studio). +* Alternatively, setup just `adb` to only connect to real devices. +* Easy-to-use CLI flows for common use-cases like connecting to emulator/real devices, downloading new system-images, creating/deleting AVDs, installing/uninstalling apps, and much more. +* For use-cases not covered above, run commands with major Android SDK tools like `adb`, `emualator`, `sdkmanager`, `avdmanager` directly from a single CLI. +* Update your SDK tools automatically and seamlessly (WIP). ## Usage -- [Mobile web testing](./docs/mobile-web-testing.md) -- [Mobile app testing](./docs/mobile-app-testing.md) -- [Setup Android SDK]() -- [Do more with Android SDK](#do-more-with-android-sdk) -- [Run Android SDK binaries](#run-android-sdk-binaries) +* [Setup for mobile-web testing](docs/mobile-web-testing.md) +* [Setup for mobile-app testing](docs/mobile-app-testing.md) +* [Do more with Android](#do-more-with-android) + * [Setup Android SDKs for standalone usage](#setup-android-sdks) + * [Simple CLI flows for common use-cases](#cli-flows-for-common-use-cases) + * [Connect to real devices or start an emulator](#1-connect) + * [List connected devices and installed AVDs](#2-list) + * [Install system images, AVDs and Android apps](#3-install) + * [Uninstall system images, AVDs and Android apps](#4-uninstall) + * [Run commands with Android SDK tools](#run-android-sdk-binaries) -### Setup Android SDK +## Do more with Android -Run the below command to download all the required Android SDKs needed to get the Android Emulator setup and running with Android v11: +### Setup Android SDKs +You can now setup a fully functional Android Emulator environment, or just `adb` for connecting to real device, without the need to download the whole Android Studio IDE. + +Run the below command to download all the required Android SDKs needed to get the Android Emulator setup and running with Android v11: ```sh npx @nightwatch/mobile-helper android --standalone ``` -### Do more with Android SDK +The above command makes sure that you have everything you need to use Android Emulator as well as connect your computer to real Android devices. + +### CLI Flows for common use-cases -The tool supports various Android SDK workflows, accessible through the following subcommands: +This tool allows you to do a lot of things with simple and tailored flows, accessible through the following subcommands: 1. [connect](./docs/subcommands/connect.md) 2. [list](./docs/subcommands/list.md) 3. [install](./docs/subcommands/install.md) 4. [uninstall](./docs/subcommands/uninstall.md) -#### Syntax +**Syntax** The following syntax is used for executing subcommands: @@ -36,18 +54,22 @@ The following syntax is used for executing subcommands: npx @nightwatch/mobile-helper android [flags|cliConfigs] ``` -#### 1. Connect a real device or launch an AVD +#### 1. connect + +This subcommand allows you to connect to a real device using `adb` or launch an AVD (Android Virtual Device) inside Android Emulator. ```sh npx @nightwatch/mobile-helper android connect [flags] ``` - | Flag | Description | | ---------- | ------------------------------------- | | --wireless | Connect a real device wirelessly | +| --emulator | Launch an AVD inside Android Emulator.| -#### 2. List all the connected devices and installed AVDs +#### 2. list + +This subcommand allows you to list all connected devices and installed AVDs. ```sh npx @nightwatch/mobile-helper android list [flags] @@ -58,33 +80,37 @@ npx @nightwatch/mobile-helper android list [flags] | --device | Show a list of all the connected real devices and AVDs | | --avd | Show a list of all the currently installed AVDs | +#### 3. install -#### 3. Install an APK or create a new AVD +This subcommand allows you to install a new system-image, create a new AVD or install an app to a target AVD/device. ```sh npx @nightwatch/mobile-helper android install [flags] ``` -| Flag | Description | -| ----- | ------------------------------------------ | -| --app | Install an APK on a real device or an AVD | -| --avd | Create a new AVD | +| Flag | Description | +| -------------- | ------------------------------------------ | +| --app | Install an APK on a real device or an AVD | +| --avd | Create a new AVD | +| --system-image | Install a new system-image | +#### 4. uninstall -#### 4. Uninstall an app or delete an AVD +This subcommand allows you to uninstall a system-image, delete an AVD, or uninstall an app from a target device. ```sh npx @nightwatch/mobile-helper android uninstall [flags] ``` -| Flag | Description | -| ----- | ---------------------------------------------- | -| --app | Uninstall an app from a real device or an AVD | -| --avd | Delete an AVD | +| Flag | Description | +| -------------- | ---------------------------------------------- | +| --app | Uninstall an app from a real device or an AVD | +| --avd | Delete an AVD | +| --system-image | Uninstall a system-image | -### Run Android SDK binaries +### Run Android SDK tool commands -Easily run Android SDK binaries without needing to locate them manually by using the `mobile-helper` CLI. +Run commands with major Android SDK tools/binaries directly from a single CLI without the need to locate and then run the binaries manually. **Syntax** @@ -92,7 +118,9 @@ Easily run Android SDK binaries without needing to locate them manually by using npx @nightwatch/mobile-helper android. [args] ``` -Currenty supported binaries: `adb`, `avdmanager`, `sdkmanager` and `emulator`. +Currently supported binaries: `adb`, `avdmanager`, `sdkmanager` and `emulator`. + +Check the following docs to know more about the usage of the above mentioned binaries: -Check the following docs to know more about the usage of the above mentioned binaries: -- [Using emulator from CLI](./docs/use-emulator-from-command-line.md) +* [Installing Android application](./docs/install-android-application-from-apk.md) +* [Using emulator from CLI](./docs/use-emulator-from-command-line.md)