{"id":20839170,"url":"https://github.com/timoa/cdkit.ui.automation","last_synced_at":"2025-05-08T21:41:11.959Z","repository":{"id":37915377,"uuid":"137520732","full_name":"timoa/cdkit.ui.automation","owner":"timoa","description":"This tool is a set of scripts to launch an Appium Server instance and run UI tests on iOS simulators and Genymotion Android emulators","archived":false,"fork":false,"pushed_at":"2024-10-30T03:56:05.000Z","size":3492,"stargazers_count":7,"open_issues_count":36,"forks_count":1,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2024-10-30T06:26:47.721Z","etag":null,"topics":["appcelerator","appium","appium-server","axway","genymotion","managed-by-terraform","mobile","titanium","ui-testing"],"latest_commit_sha":null,"homepage":"https://cdkit.org","language":"JavaScript","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/timoa.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":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-15T18:37:03.000Z","updated_at":"2024-08-14T22:01:29.000Z","dependencies_parsed_at":"2024-02-25T11:36:13.288Z","dependency_job_id":"0c50164a-fc59-4495-9d5f-cb41c7e51b8c","html_url":"https://github.com/timoa/cdkit.ui.automation","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoa%2Fcdkit.ui.automation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoa%2Fcdkit.ui.automation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoa%2Fcdkit.ui.automation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timoa%2Fcdkit.ui.automation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timoa","download_url":"https://codeload.github.com/timoa/cdkit.ui.automation/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225110511,"owners_count":17422412,"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":["appcelerator","appium","appium-server","axway","genymotion","managed-by-terraform","mobile","titanium","ui-testing"],"created_at":"2024-11-18T01:12:34.177Z","updated_at":"2024-11-18T01:12:34.816Z","avatar_url":"https://github.com/timoa.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [CDKit][cdkit-github]: UI Tests Automation\n\n[![Latest Release][release-badge]][release-url]\n[![Build Status][github-badge]][github-url]\n\n[![Quality Gate Status][sonarcloud-status-badge]][sonarcloud-url]\n[![Security Rating][sonarcloud-security-badge]][sonarcloud-url]\n[![Maintainability Rating][sonarcloud-maintainability-badge]][sonarcloud-url]\n\n[![Bugs][sonarcloud-bugs-badge]][sonarcloud-url]\n[![Code Smells][sonarcloud-codesmells-badge]][sonarcloud-url]\n[![Coverage][sonarcloud-coverage-badge]][sonarcloud-url]\n[![Duplicated Lines (%)][sonarcloud-duplicated-badge]][sonarcloud-url]\n\n*[CDKit][cdkit-github] is a DevOps framework that helps to deploy mobile apps (iOS and Android) to the app stores (iTunes and Google Play).*\n\nThis tool is a set of scripts to launch an Appium Server instance and run UI tests on iOS simulators and Genymotion Android emulators.\n\nThis project is based on the [Appcelerator Appium tests repository][appcelerator-appium-tests-github] that is not maintained since 2017.\n\nI still have a [PR to fix the launch of Genymotion][appcelerator-appium-tests-pr] :)\n\n## Caveats\n\n- This has been tested on macOS only (for now)\n- Windows 10 Mobile is experimental\n- Install VirtualBox and Genymotion with **default** settings for macOS and Windows\n- Xcode should be installed on macOS\n- Appc CLI should be installed\n\n## Setup\n\n1. Make sure you have node \u003e= 10 and npm \u003e= 6.\n2. In this directory, run `npm install`.\n3. Next, install `appium-doctor`: `[sudo] npm install -g appium-doctor`.\n4. Run `appium-doctor` to ensure your machine is properly setup for appium testing.\n\n## Flag Usage\n\n- `node cli.js --app com.company.app`\n  - Run all tests in the `ui-tests/com.company.app` directory.\n- `node cli.js --app com.company.app --suites \u003csuites\u003e`\n  - Run only the specified test suites e.g.\n\n  ```bash\n  node cli.js --app com.company.app --suites screenshots/ios.js -\u003e run only the iOS `screenshots` test suite\n\n  node cli.js --app com.company.app --suites screenshots/ios.js,screenshots/android.js -\u003e run both the iOS and Android `screenshots` test suites.\n  ```\n\n- `node cli.js --app com.company.app --suites \u003csuites\u003e --use-sdk \u003cti_sdk\u003e`\n  - Before running the specified test suites, rebuild the test app with the specified `ti_sdk`.\n  - This probably won't be useful if you are running this on your local machine. But, will be useful in a CI/CD build.\n- `node cli.js --app com.company.app --suites \u003csuites\u003e --more-logs`\n  - Run the specified test suites with logs enabled; this can become very noisy.\n- Below is the complete list of flags:\n\n  ```bash\n  Options:\n\n    -h, --help             output usage information\n    --app \u003cbundleID\u003e       app bundleId (needs to be present in the /ui-tests/\u003cbundleId\u003e folder)\n    --platform \u003cplatform\u003e  run all tests with the specified platform (ios or android)\n    --suites \u003csuites\u003e      comma-delimited string of valid test suites; otherwise, run all tests\n    --use-sdk \u003cti_sdk\u003e     build all test apps with the specified Titanium SDK\n    --more-logs            enables more logging; this becomes very noisy\n  ```\n\n## How to Write Tests\n\n### 1. Test Suite Structure\n\nAll test suites live in the `ui-tests` directory and should have the following folder structure:\n\n```bash\nui-tests/\n|--- app/\n  |--- suite_name/\n    |--- test_app/\n    |--- platform.js\n    |--- platform2.js\n...\n```\n\n**Info:**\n\n- `app` should be the bundle ID/app ID of your app e.g. `com.company.app`.\n- `suite_name` should be an API supported by Titanium SDK or Hyperloop e.g. `screenshots`.\n- `test_app` should be a Titanium Classic, Alloy, or Hyperloop enabled project.\n- `platform.js` is a mocha file that will execute test cases (via Appium) in the `test_app` on the designated mobile platform.\n- It's important that the `platform.js` file name is a valid platform (`ios.js` or `android.js`), since it tells this tool which mobile platform to use when: installing the `test_app` and running the tests.\n\n### 2. config.js\n\nThe `config.js` file (which lives at the root of your app project) contains information about all the test suites and which Appium server to connect to.\n\nHigh-level notes:\n\n```javascript\nmodule.exports = {\n  ios: {\n\n    // these are properties straight from appium and more are defined here:\n    // https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/default-capabilities-arg.md\n    desiredCapabilities: {\n      automationName: 'XCUITest' // leave as-is for ios\n    },\n\n      // the suite_name folder should exist in the 'ui-tests/com.company.app' directory\n      suite_name: {\n        proj: 'SAMPLE', // name of the 'test_app'\n\n      // list of simulators you want the test app to run against\n      testDevices: [\n        {\n          deviceName: 'iPhone Xr', // the simulator created in xcode\n          platformVersion: '13.0' // the platform version associated with the simulator\n        },\n        ...\n      ]\n    },\n\n    suite_name2: { ... }\n    ...\n  },\n\n  android: {\n    desiredCapabilities: {\n      automationName: 'Appium' // leave as-is for android\n    },\n    suite_name: {\n      proj: 'SAMPLE',\n\n      // these two properties are needed when testing against android\n      appPackage: 'com.company.app',\n      appActivity: '.SomeActivity',\n\n      // list of genymotion emulators you want the test app to run against\n      testDevices: [\n      {\n          deviceName: 'Google Pixel 3', // the genymotion emulator created in the genymotion app\n          platformVersion: '9.0' // the platform version associated with the emulator\n      },\n        ...\n      ]\n    }\n  }\n\n  // other platforms can be added in the future\n};\n```\n\n### 3. Mocha Files\n\nTo write the Appium test cases, you will need to be familiar with mocha and Promises. Look [here][qe-appium-master] for examples.\n\nCouple notes about those examples vs these test suites:\n\n- The `driver` and `webdriver` property is exposed to the test suite through the `global` variable.\n- The `global` variable contains `curDevice` property. This has information about the current running device (`name`) and which version (`ver`).\n- You don't need a setup or teardown phase like [here][qe-appium-master-ios-test].\n\n## Main Loop\n\n`cli.js` is the entry point file and contains the main loop, which does the following:\n\n1. `runAppium()` - launches the local Appium server.\n2. `buildTestApps()` - if `--use-sdk` flag is passed, then build all the test apps before moving onto the next task.\n3. `createTests()` - create a data structure from `--suites` and loop through the data structure. While looping:\n4. `launchGeny()` - if the test app needs to be tested on an Android platform, launch the designated Genymotion emulator first. iOS simulators will be launched in the next step by Appium.\n5. `startClient()` - after the simulator/genymotion is launched, install the test app to the device and connect to the Appium local server.\n6. `new Mocha().addFile().run()` - run the associated mocha test suite.\n7. `stopClient()` - after a mocha test suite is finished running, disconnect the mobile device from the Appium local server. Depending on the `desiredCapabilities`, iOS simulators can be left running or killed.\n8. `quitGeny()` - if a Genymotion emulator is launched, gracefully kill the process.\n9. `killAppium()` - after all the test suites are executed, kill the Appium local server.\n\n[cdkit-github]: https://github.com/timoa/cdkit\n[sonarcloud]: https://sonarcloud.io/about\n[release-badge]: https://img.shields.io/github/v/release/timoa/cdkit.ui.automation?logoColor=orange\n[release-url]: https://github.com/timoa/cdkit.ui.automation/releases\n[github-badge]: https://github.com/timoa/cdkit.ui.automation/workflows/Build/badge.svg\n[github-url]: https://github.com/timoa/cdkit.ui.automation/actions?query=workflow%3ABuild\n[sonarcloud-url]: https://sonarcloud.io/dashboard?id=timoa_cdkit.ui.automation\n[sonarcloud-status-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=alert_status\n[sonarcloud-security-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=security_rating\n[sonarcloud-maintainability-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=sqale_rating\n[sonarcloud-bugs-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=bugs\n[sonarcloud-codesmells-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=code_smells\n[sonarcloud-coverage-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=coverage\n[sonarcloud-duplicated-badge]: https://sonarcloud.io/api/project_badges/measure?project=timoa_cdkit.ui.automation\u0026metric=duplicated_lines_density\n[appcelerator-appium-tests-github]: https://github.com/appcelerator/appium-tests\n[appcelerator-appium-tests-pr]: https://github.com/appcelerator/appium-tests/pull/4\n[qe-appium-master]: https://github.com/appcelerator/qe-appium/tree/master/test\n[qe-appium-master-ios-test]: https://github.com/appcelerator/qe-appium/blob/master/test/ks_ios_test.js#L9-L39\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimoa%2Fcdkit.ui.automation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimoa%2Fcdkit.ui.automation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimoa%2Fcdkit.ui.automation/lists"}