{"id":13752776,"url":"https://github.com/webdriverio/appium-boilerplate","last_synced_at":"2025-04-13T06:23:19.783Z","repository":{"id":40212708,"uuid":"147927317","full_name":"webdriverio/appium-boilerplate","owner":"webdriverio","description":"Boilerplate project to run WebdriverIO tests with Appium to test native applications on iOS and Android","archived":false,"fork":false,"pushed_at":"2025-03-28T22:14:11.000Z","size":15641,"stargazers_count":474,"open_issues_count":7,"forks_count":270,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-04-10T16:46:23.940Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webdriverio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"tidelift":"npm/webdriverio","open_collective":"webdriverio"}},"created_at":"2018-09-08T11:25:15.000Z","updated_at":"2025-04-06T19:11:32.000Z","dependencies_parsed_at":"2024-04-14T02:44:49.679Z","dependency_job_id":null,"html_url":"https://github.com/webdriverio/appium-boilerplate","commit_stats":{"total_commits":231,"total_committers":21,"mean_commits":11.0,"dds":0.4415584415584416,"last_synced_commit":"a0bf48e5515bb96615c73887b2afd2f1ef2f8bb1"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fappium-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fappium-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fappium-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fappium-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webdriverio","download_url":"https://codeload.github.com/webdriverio/appium-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665752,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T09:01:10.863Z","updated_at":"2025-04-13T06:23:19.738Z","avatar_url":"https://github.com/webdriverio.png","language":"TypeScript","funding_links":["https://tidelift.com/funding/github/npm/webdriverio","https://opencollective.com/webdriverio"],"categories":["Don't forget to give a :star: to make the project popular"],"sub_categories":[],"readme":"# Appium Boilerplate\n\n**NOTE:** This boilerplate is for Webdriver V8 where the tests are written with `async`/`await` and TypeScript. If you need a boilerplate for older versions, check the following:\n\n- V7 (JavaScript) please click [here](https://github.com/webdriverio/appium-boilerplate/tree/v7)\n- V7 (TypeScript, sync mode) please click [here](https://github.com/webdriverio/appium-boilerplate/tree/sync-mode)\n\nBoilerplate project to run Appium tests together with WebdriverIO for:\n\n- iOS/Android Native Apps\n- iOS/Android Hybrid Apps\n- Android Chrome and iOS Safari browser ([check here](./README.md#automating-chrome-or-safari))\n\n\u003e [!IMPORTANT]\n\u003e This boilerplate uses the WebdriverIO native demo app which can be found [here](https://github.com/webdriverio/native-demo-app).\n\n\u003e [!NOTE]\n\u003e This boilerplate only handles local execution on 1 em/simulator at a time, not parallel execution. For more info about that Google on setting up a grid with Appium.\n\n## Based on\n\nThis boilerplate is currently based on:\n\n- **WebdriverIO:** `9.x`\n- **Appium:** `2.x`\n\n## Installation\n\n1. Clone this project by running\n\n```sh\ngit clone https://github.com/webdriverio/appium-boilerplate.git\n```\n\n2. Install all dependencies\n\n```sh\nnpm install\n```\n\n\u003e [!TIP]\n\u003e Use the [appium-installer](https://github.com/AppiumTestDistribution/appium-installer) package to setup Appium on your local machine. This will also help you configure Android Emulators/ iOS Simulators.\n\n\u003e [!NOTE]\n\u003e You don't need Appium installed on you local machine When running test in a cloud\n\n3. Create a `./apps` directory at the root of this project. Download the app files (`.zip` / `.apk`) with version \u003e= `1.0.0`, which can be found [here](https://github.com/webdriverio/native-demo-app/releases), into the `./apps` folder.\n\n4. Adjust the configuration file(s) for [Android](./config/wdio.android.app.conf.ts) and [iOS](./config/wdio.ios.app.conf.ts) regarding the device configuration you've created on your local machine.\n\n5. Running tests locally\n    - **Android App:** `npm run android.app`\n    - **Android Browser:**  `npm run android.browser`\n    - **iOS App:** `npm run ios.app`\n    - **iOS Browser:**  `npm run ios.browser`\n    - **Android App with cucumber:** `npm run android.app.cucumber`\n\n## How to implement in your project\n\nChoose one of the following options:\n\n1. Clone the git repo — `git clone https://github.com/webdriverio/appium-boilerplate.git`\n1. Copy the files to your project directory (all files in `/tests` and the `wdio.conf` files in the `config` folder)\n1. Merge project dev dependencies with your project dev dependencies in your `package.json`\n1. Merge the scripts to your `package.json` scripts\n1. Run the tests, see [Native App Tests](#native-app-tests) or [Automating Chrome of Safari](#automating-chrome-or-safari).\n\n## Configuration files\n\nThis boilerplate uses a specific config for iOS and Android, see [configs](./config). The configs are based on a shared config\n[`wdio.shared.conf.ts`](./config/wdio.shared.conf.ts).\nThis shared config holds **all the defaults** so the iOS and Android configs only need to hold the capabilities and specs that are needed for running on iOS and or Android (app or browser).\n\nPlease check the [`wdio.shared.conf.ts`](./config/wdio.shared.conf.ts)-file for the minimal configuration options. Notes are added for why a different value has been selected in comparison to the default values WebdriverIO provides.\n\nSince we do not have Appium installed as part of this package we are going to use the globally installed version of Appium. This is configured in [`wdio.shared.local.appium.conf.ts`](./config/wdio.shared.local.appium.conf.ts).\n\n## Locator strategy for native apps\n\nThe locator strategy for this boilerplate is to use `accessibilityID`s, see also the\n[WebdriverIO docs](https://webdriver.io/docs/selectors#accessibility-id) or this newsletter on [AppiumPro](https://appiumpro.com/editions/20).\n`accessibilityID`s makes it easy to script once and run on iOS and Android because most of the apps already have some `accessibilityID`s.\n\nIf `accessibilityID`'s can't be used, and for example only XPATH is available, then the following setup could be used to make cross-platform selectors\n\n```js\nconst SELECTORS = {\n    WEB_VIEW_SCREEN: browser.isAndroid\n        ? '*//android.webkit.WebView'\n        : '*//XCUIElementTypeWebView',\n};\n```\n\n\u003e [!NOTE]\n\u003e If you look into the screen/page-objects you might see that a lot of selectors are made private, meaning you can't use the elements in the spec-file itself. This has been done on purpose because one of the *best practices* is to remove all interactions from your spec files and implement the interactions in the page objects. This will make it easier to maintain for the future and easier to refactor if new interaction methods will be added or names will be adjusted.\n\n## Native App Tests\n\nAll tests can be executed on the devices as configured in [`wdio.android.app.conf.ts`](./config/wdio.android.app.conf.ts) or [`wdio.ios.app.conf.ts`](./config/wdio.ios.app.conf.ts). Please check the below tests on what they do or how to run them separately.\n\n```sh\n# For Android local execution\nnpm run android.app\n\n# For iOS local execution\nnpm run ios.app\n```\n\n### Drag And Drop\n\nDrag-and-drop an element can be a complex gesture to automate with Appium. The demo app has a simple puzzle that hopefully makes it easier and fun to understand how to implement a drag-and-drop in WebdriverIO. The test can be found [here](./tests/specs/app.drag.and.drop.spec.ts). As you can see this boilerplate uses the enhanced [`driver.dragAndDrop()`](https://webdriver.io/docs/api/mobile/dragAndDrop)-method which makes it really easy for you to drag elements in native apps.\n\n```sh\n# For Android local execution\nnpm run android.app -- --spec=tests/specs/app.drag.and.drop.spec.ts\n\n# For iOS local execution\nnpm run ios.app -- --spec=tests/specs/app.drag.and.drop.spec.ts\n```\n\n### Form components\n\nThe forms tab holds some components that might be a challenge during automation:\n\n- Input fields\n- Switches\n- Dropdowns / Pickers\n- Native alerts\n\nThe tests and used page objects hopefully explain what you need to do to make this work and can be found [here](./tests/specs/app.forms.spec.ts).\n\nYou can run the single test with the following commands\n\n```sh\n# For Android local execution\nnpm run android.app -- --spec=tests/specs/app.forms.spec.ts\n\n# For iOS local execution\nnpm run ios.app -- --spec=tests/specs/app.forms.spec.ts\n```\n\n### Login with Biometric support\n\nThe Login screen holds a simple implementation of a Login and SignUp form. This boilerplate holds 2 different test files for the Login screen.\n\n- [Default Login/Sign Up](./tests/specs/app.login.spec.ts)\n- [Login through Touch-/FaceID or FingerPrint (Biometric Support)](./tests/specs/app.biometric.login.spec.ts)\n\nThe last one can be very interesting because it will give you an idea of what you need to do when you need to log in with Touch-/FaceID or FingerPrint. The [`app.biometric.login.spec.ts`](./tests/specs/app.biometric.login.spec.ts) will also enable Touch-/FaceID if needed automatically for you for **Android Emulators** or **iOS Simulators**. It covers almost all platform versions.\n\n\u003e ![NOTE]\n\u003e The methods rely on the fact that the Android Emulator or iOS Simulator have English as the default language. If you have set up your test devices with a different language you might need to change certain selectors and or texts for the selectors.\n\nYou can run the single test with the following commands\n\n```sh\n# For Android local execution\nnpm run android.app -- --spec=tests/specs/app.login.spec.ts\nnpm run android.app -- --spec=tests/specs/app.biometric.login.spec.ts\n\n# For iOS local execution\nnpm run ios.app -- --spec=tests/specs/app.login.spec.ts\nnpm run ios.app -- --spec=tests/specs/app.biometric.login.spec.ts\n```\n\n### Navigation\n\nThere are 2 types of navigation tests explained in this boilerplate.\n\n1. [Tab Bar](./tests/specs/app.tab.bar.navigation.spec.ts)\n1. [Deep Links](./tests/specs/app.deep.link.navigation.spec.ts)\n\nThe most interesting test here will be the [Deep Links](./tests/specs/app.deep.link.navigation.spec.ts) because this might speed up your tests if your app supports Deep Links. Check the code and the `openDeepLinkUrl()` method in the [`Utils.ts`](./tests/helpers/Utils.ts) file to see how this works.\n\n\u003e [!TIP]\n\u003e If you are automating iOS apps and you can use Deep Links, then you might want to try adding the capability `autoAcceptAlerts:true` when you start the iOS device. This capability will automatically accept all alerts, also the alert that will appear when you want to open your deep link in Safari.\n\u003e\n\u003e If you were going to use this capability, then don't forget to remove the last few lines in the [`openDeepLinkUrl()`](./tests/helpers/Utils.ts)-method, see the comments in the method\n\nYou can run the single test with the following commands\n\n```sh\n# For Android local execution\nnpm run android.app -- --spec=tests/specs/app.tab.bar.navigation.spec.ts\nnpm run android.app -- --spec=tests/specs/app.deep.link.navigation.spec.ts\n\n# For iOS local execution\nnpm run ios.app -- --spec=tests/specs/app.tab.bar.navigation.spec.ts\nnpm run ios.app -- --spec=tests/specs/app.deep.link.navigation.spec.ts\n```\n\n### Swiping\n\nSwiping is a movement with your finger on the screen that has a starting position on the screen, an x-, and y-coordinate and an end position, also an x-, and y-coordinate. The starting position can be seen as the first time you touch the screen, the initial *press*. The end position can be seen as the time you release the screen. If you translate this into steps you will get:\n\n1. Press your finger on the screen in the starting position\n1. Move your finger to the end position\n1. Release your finger when you are in the end position\n\nThe [Swipe](./tests/specs/app.swipe.spec.ts) test will be an example of how to do that. It uses the newly added [`driver.swipe()`](https://webdriver.io/docs/api/mobile/swipe) command which reduces complex logic for you.\n\nIf you want to know more about custom Gestures and how to automate them, then we would advise you to watch [this presentation \"Swiping your way through Appium by Wim Selles\"](https://youtu.be/oAJ7jwMNFVU).\n\nYou can run the single test with the following commands\n\n```sh\n# For Android local execution\nnpm run android.app -- --spec=tests/specs/app.swipe.spec.ts\n\n# For iOS local execution\nnpm run ios.app -- --spec=tests/specs/app.swipe.spec.ts\n```\n\n### WebViews\n\nThe app has a WebView that will automatically load the WebdriverIO documentation page. This boilerplate holds 2 test files:\n\n1. [Interact within a WebView with CSS Selectors](./tests/specs/app.webview.spec.ts).\n   *You will also find a test that interacts between a WebView and the Native part of the app.*\n1. [Automate a WebView based on Native Selectors](./tests/specs/app.webview.xpath.spec.ts). This test will compare the execution time of:\n\n    - automating the WebView by **NOT** switching to the WebView (by using native selectors).\n    - automating the WebView by **SWITCHING** to the WebView.\n\n    Check the console for load time differences. An example time could look like this\n\n    ```log\n    // Android\n    [0-0] RUNNING in Android - /tests/specs/app.webview.xpath.spec.ts\n    [0-0] Test time for using XPATH It took 0.799 seconds.\n    [0-0] Test time for switching to the WebView It took 0.238 seconds.\n    [0-0] PASSED in Android - /tests/specs/app.webview.xpath.spec.ts\n\n    // iOS\n    [0-0] RUNNING in iOS - /tests/specs/app.webview.xpath.spec.ts\n    [0-0] Test time for using XPATH It took 3.125 seconds.\n    [0-0] Test time for switching to the WebView It took 1.443 seconds.\n    [0-0] PASSED in iOS - /tests/specs/app.webview.xpath.spec.ts\n    ```\n\nYou will also find a [WebView](./tests/helpers/WebView.ts) helper with hopefully useful methods that can help you automate a Hybrid App.\nKeep in the back of your mind that for the _simplicity_ of the Demo app, only one WebView is used. This is also used in the WebView-helper.\n\nMore information about **Automating Hybrid Applications with Appium** and more complex WebViews can be found in [this webinar](https://youtu.be/_mPCRxplBfo) recording.\n\nYou can run the single test with the following commands\n\n```sh\n# For Android local execution\nnpm run android.app -- --spec=tests/specs/app.webview.spec.ts\nnpm run android.app -- --spec=tests/specs/app.webview.xpath.spec.ts\n\n# For iOS local execution\nnpm run ios.app -- --spec=tests/specs/app.webview.spec.ts\nnpm run ios.app -- --spec=tests/specs/app.webview.xpath.spec.ts\n```\n\n## Automating Chrome or Safari\n\nMobile web automation is almost the same as writing tests for desktop browsers. The only difference can be found in the configuration that needs to be used. Click [here](config/wdio.ios.browser.conf.ts) to find the config for iOS Safari and [here](config/wdio.android.browser.conf.ts) for Android Chrome.\nFor Android be sure that the latest version of Chrome is installed, see also\n[here](./docs/FAQ.md#i-get-the-error-no-chromedriver-found-that-can-automate-chrome-). Our [`wdio.shared.local.appium.conf.ts`](./config/wdio.shared.local.appium.conf.ts) uses the `relaxedSecurity: true` argument from Appium which will allow Appium to automatically download the latest ChromeDriver.\n\nFor this boilerplate, the test cases from the Jasmine boilerplate, created by [Christian Bromann](https://github.com/christian-bromann), are used.\n\n## Cloud vendors\n\n### Sauce Labs\n\nIf you want to run the Native App tests on Sauce Labs you need to do 2 things:\n\n- Add the [Sauce Service](#add-sauce-service) to your project\n- Upload the apps to the [Sauce Labs Storage](#upload-apps-to-sauce-storage)\n\nWhen the above has been executed you can follow the steps:\n\n- [Run app tests on the Sauce Labs Real Device Cloud](#run-app-tests-on-the-sauce-labs-real-device-cloud)\n- [Run app tests on the Sauce Labs Emulators and Simulators](#run-app-tests-on-the-sauce-labs-emulators-and-simulators)\n\n#### Add Sauce Service\n\nMake sure you install the latest version of the `@wdio/sauce-service` with\n\n```shell\nnpm install --save-dev @wdio/sauce-service\n```\n\nand add `services: ['sauce'],` to the config. If no `region` is provided it will automatically default to the US-Virtual/RDC cloud.\nIf you provide `region: 'us'` or `region: 'eu'` it will connect to the US or the EU Virtual/RDC cloud.\n\n#### Upload apps to Sauce Storage\n\nIf you want to use Android emulators, iOS simulators or Android real devices in the Sauce Labs UI you need to upload the apps to the Sauce Storage. You can find a script to upload them to, and the US, and EU DC in [this](./scripts) folder. You can push the files to the storage by executing the following steps in a terminal from the root of this project:\n\n```sh\ncd scripts\n./push_apps_to_sauce_storage.sh\n```\n\nWhen you've done that you will see a lot of successful logs in your terminal.\n\n#### Run app tests on the Sauce Labs Real Device Cloud\n\n\u003e ![NOTE]\n\u003e Due to the lack of signing iOS apps, this boilerplate doesn't support Real Devices.  Only Android Real Devices are supported. If you want to use iOS Real Devices then you need to provide your own app that has been signed properly.\n\nPlease check the [Android Real Devices](./config/wdio.android.app.conf.ts)-config to see the setup for Android real devices.\n\nYou can use the following scripts, see the [`package.json`](./package.json), to execute the tests in the cloud:\n\n```sh\n# For Android Real Devices\n# On EU DC\nnpm run android.sauce.rdc.app.eu\n# On US DC\nnpm run android.sauce.rdc.app.us\n```\n\n#### Run app tests on the Sauce Labs Emulators and Simulators\n\nPlease check the following configs to verify the configurations:\n\n- [Android Emulators](./config/saucelabs/wdio.android.emulators.app.conf.ts)\n- [iOS Simulators](./config/saucelabs/wdio.ios.simulators.app.conf.ts)\n\nThe following scripts can be used, see the [`package.json`](./package.json), to execute the tests in the cloud:\n\n```sh\n# For Android Emulators\n# On EU DC\nnpm run android.sauce.emulators.app.eu\n# On US DC\nnpm run android.sauce.emulators.app.us\n# For Android Real Devices\n# On EU DC\nnpm run android.sauce.rdc.app.eu\n# On US DC\nnpm run android.sauce.rdc.app.us\n\n# For iOS\n# On EU DC\nnpm run ios.sauce.simulator.app.eu\n# On US DC\nnpm run ios.sauce.simulator.app.us\n```\n\n### BrowserStack\n\nThis boilerplate provides a setup for testing with BrowserStack. Please check the [BrowserStack](./config/browserstack) folder to see the setup for iOS and Android.\n\nMake sure you install the latest version of the `@wdio/browserstack-service` with:\n\n```shell\nnpm install --save-dev @wdio/browserstack-service\n```\n\nThere are 2 scripts that can be used. See the [`package.json`](./package.json) to execute the tests in the cloud:\n\n```sh\n# For iOS\n$ npm run ios.browserstack.app\n\n# For Android\n$ npm run android.browserstack.app\n```\n\n### TestingBot\n\nThis boilerplate provides a setup for testing with TestingBot. Please check the [TestingBot](./config/testingbot)-folder to see the setup for Android.\n\nMake sure you install the latest version of the `@wdio/testingbot-service` with\n\n```shell\nnpm install --save-dev @wdio/testingbot-service\n```\n\nYou can use the script from [`package.json`](./package.json), to execute the tests in the TestingBot cloud:\n\n```sh\n$ npm run android.testingbot.app\n```\n\n### LambdaTest\n\nThis boilerplate provides a setup for testing with LambdaTest.\nPlease check the [LambdaTest](./config/lambdatest) folder to see the setup for iOS and Android.\n\nMake sure you install the latest version of the `wdio-lambdatest-service` with:\n\n```shell\nnpm i wdio-lambdatest-service --save-dev\n```\n\nThere are 4 scripts that can be used.\nSee the [`package.json`](./package.json), to execute the tests in the cloud:\n\n```sh\n# To run browser tests in iOS Simulator\nnpm run ios.lt.browser.simulator\n```\n```sh\n# To run browser tests in iOS Real Device\nnpm run ios.lt.browser.realdevice\n```\n```sh\n# To run browser tests in Android Emulator\nnpm run android.lt.browser.emulator\n```\n```sh\n# To run browser tests in Android Real Device\nnpm run android.lt.browser.realdevice\n```\n\n## FAQ\n\nSee [FAQ](./docs/FAQ.md)\n\n## Tips and Tricks\n\nSee [Tips and Tricks](./docs/TIPS_TRICKS.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdriverio%2Fappium-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebdriverio%2Fappium-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdriverio%2Fappium-boilerplate/lists"}