{"id":20630215,"url":"https://github.com/macacajs/xctestwd","last_synced_at":"2025-04-05T05:10:04.800Z","repository":{"id":47034314,"uuid":"89126548","full_name":"macacajs/XCTestWD","owner":"macacajs","description":"A Swift implementation of WebDriver server for iOS that runs on Simulator/iOS devices.  ","archived":false,"fork":false,"pushed_at":"2023-01-24T19:17:09.000Z","size":806,"stargazers_count":230,"open_issues_count":14,"forks_count":62,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-04-16T20:16:29.195Z","etag":null,"topics":["automation","hacktoberfest","ios","macaca","swift","webdriver","xctest"],"latest_commit_sha":null,"homepage":"https://macacajs.github.io","language":"Swift","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/macacajs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-23T08:04:52.000Z","updated_at":"2024-04-14T11:46:46.000Z","dependencies_parsed_at":"2023-02-14T00:45:14.793Z","dependency_job_id":null,"html_url":"https://github.com/macacajs/XCTestWD","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macacajs%2FXCTestWD","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macacajs%2FXCTestWD/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macacajs%2FXCTestWD/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macacajs%2FXCTestWD/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macacajs","download_url":"https://codeload.github.com/macacajs/XCTestWD/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289429,"owners_count":20914464,"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":["automation","hacktoberfest","ios","macaca","swift","webdriver","xctest"],"created_at":"2024-11-16T14:07:13.696Z","updated_at":"2025-04-05T05:10:04.769Z","avatar_url":"https://github.com/macacajs.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XCTestWD\n\n---\n\n[![NPM version][npm-image]][npm-url]\n[![node version][node-image]][node-url]\n[![npm download][download-image]][download-url]\n[![CircleCI](https://circleci.com/gh/macacajs/XCTestWD.svg?style=svg)](https://circleci.com/gh/macacajs/XCTestWD)\n\n[npm-image]: https://img.shields.io/npm/v/xctestwd.svg\n[npm-url]: https://npmjs.org/package/xctestwd\n[node-image]: https://img.shields.io/badge/node.js-%3E=_8-green.svg\n[node-url]: http://nodejs.org/download/\n[download-image]: https://img.shields.io/npm/dm/xctestwd.svg\n[download-url]: https://npmjs.org/package/xctestwd\n\n\u003e Swift implementation of WebDriver server for iOS that runs on Simulator/iOS devices.\n\n\u003c!-- GITCONTRIBUTOR_START --\u003e\n\n## Contributors\n\n|[\u003cimg src=\"https://avatars0.githubusercontent.com/u/8198256?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eSamuelZhaoY\u003c/b\u003e\u003c/sub\u003e](https://github.com/SamuelZhaoY)\u003cbr/\u003e|[\u003cimg src=\"https://avatars1.githubusercontent.com/u/1011681?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003exudafeng\u003c/b\u003e\u003c/sub\u003e](https://github.com/xudafeng)\u003cbr/\u003e|[\u003cimg src=\"https://avatars3.githubusercontent.com/u/1209810?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eparadite\u003c/b\u003e\u003c/sub\u003e](https://github.com/paradite)\u003cbr/\u003e|[\u003cimg src=\"https://avatars2.githubusercontent.com/u/10086769?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eholy-lousie\u003c/b\u003e\u003c/sub\u003e](https://github.com/holy-lousie)\u003cbr/\u003e|[\u003cimg src=\"https://avatars2.githubusercontent.com/u/9434109?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eadudurant\u003c/b\u003e\u003c/sub\u003e](https://github.com/adudurant)\u003cbr/\u003e|[\u003cimg src=\"https://avatars1.githubusercontent.com/u/17233599?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eChan-Chun\u003c/b\u003e\u003c/sub\u003e](https://github.com/Chan-Chun)\u003cbr/\u003e|\n| :---: | :---: | :---: | :---: | :---: | :---: |\n[\u003cimg src=\"https://avatars1.githubusercontent.com/u/7436932?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003egurisxie\u003c/b\u003e\u003c/sub\u003e](https://github.com/gurisxie)\u003cbr/\u003e|[\u003cimg src=\"https://avatars3.githubusercontent.com/u/1265888?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003exqin\u003c/b\u003e\u003c/sub\u003e](https://github.com/xqin)\u003cbr/\u003e|[\u003cimg src=\"https://avatars1.githubusercontent.com/u/26514264?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003ebutterflyingdog\u003c/b\u003e\u003c/sub\u003e](https://github.com/butterflyingdog)\u003cbr/\u003e|[\u003cimg src=\"https://avatars1.githubusercontent.com/u/6138806?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003edonlinglok\u003c/b\u003e\u003c/sub\u003e](https://github.com/donlinglok)\u003cbr/\u003e|[\u003cimg src=\"https://avatars2.githubusercontent.com/u/31531639?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003eNicolasyy\u003c/b\u003e\u003c/sub\u003e](https://github.com/Nicolasyy)\u003cbr/\u003e|[\u003cimg src=\"https://avatars3.githubusercontent.com/u/32116360?v=4\" width=\"100px;\"/\u003e\u003cbr/\u003e\u003csub\u003e\u003cb\u003efengguochao\u003c/b\u003e\u003c/sub\u003e](https://github.com/fengguochao)\u003cbr/\u003e\n\nThis project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Wed Apr 15 2020 13:12:56 GMT+0800`.\n\n\u003c!-- GITCONTRIBUTOR_END --\u003e\n\n## 1. Requirements\n\n- XCode version \u003e 10.1\n- iOS version 11.0 and above. （there is significant change on XCUITest interfaces and system private headers, hence we decide to support newest OS version only）\n\n### 1.1. Carthage\n\nUsing Carthage with Xcode 12\n\n\u003e https://github.com/Carthage/Carthage/blob/master/Documentation/Xcode12Workaround.md\n\ncarthage.sh can be found at the root of the project\n\n```bash\n./carthage.sh bootstrap --platform iOS --cache-builds\n```\n\n## 2. Starting XCTestWD\n\nXCTestWD can be either started with XCode IDE or via simple xcodebuild command line. By default, the webdriver agent occupies port `8001`.  You can override the default port in XCode by searching `XCTESTWD_PORT` under project build settings. Alternatively, it can also be overrided when you execute command line method as specified in `2.2. Using Xcodebuild`\n\n### 2.1. Using Xcode\n\nDownload the project and open the XCode project, checkout the scheme `XCTestWDUITests` and run the test case `XCTextWDRunner`\n\n### 2.2. Using XcodeBuild\n\nOpen the terminal, go to the directory where contains `XCTestWD.xcodeproj` file and execute the following command:\n\n```bash\n#\n# Change the port number to override the default port\n#\nxcodebuild -project XCTestWD.xcodeproj \\\n  -scheme XCTestWDUITests \\\n  -destination 'platform=iOS Simulator,name=iPhone 6' \\\n  XCTESTWD_PORT=8001 \\\n  clean test\n```\n\nTo execute for iOS device, run the following command:\n\n```bash\n#\n# Change the port number to override the default port\n# Specify the device name\n#\nxcodebuild -project XCTestWD.xcodeproj \\\n  -scheme XCTestWDUITests \\\n  -destination 'platform=iOS,name=(your device name)' \\\n  XCTESTWD_PORT=8001 \\\n  clean test\n```\n**Note:** For versions above wxtestwd 2.0.0, please install ideviceinstaller for supporting real device testing\n\n\n## 3. Element Types\n\nIn the current protocol, element strings for each `XCUIElementType` are generated based on the existing mapping in [reference/xctest/xcuielementtype](https://developer.apple.com/reference/xctest/xcuielementtype)\n\n\n## 4. Common Issues\n\n### 4.1 Socket hangup error\n\nSocket Hangup Error happens in the following two scenarios: \u003cbr\u003e\n- **Case 1** \u003cbr\u003e\nIssue: \u003cbr\u003e\nWhen you have some existing XCTestWD instances running and creating new ones. \u003cbr\u003e\nSolution: \u003cbr\u003e\nverify whether ideviceinstaller and xcrun is properly working on your device and simulator. \u003cbr\u003e\nHint: \u003cbr\u003e\nhttps://github.com/libimobiledevice/ideviceinstaller/issues/48\n\n- **Case 2** \u003cbr\u003e\nIssue: \u003cbr\u003e\nWhen you have started the XCTestWD instance properly but fails in middle of a testing process. \u003cbr\u003e\nSolution: \u003cbr\u003e\nSee the Macaca Service log to checkout which command leads the error. With detailed and comprehensive log information, please submit an issue to us. \u003cbr\u003e\nOptional: \u003cbr\u003e\nIf you cannot get anything from macaca server log, open the XCTestWD in your node installation path and attatch for debugging on process 'XCTRunnerUITests-Runner'. \u003cbr\u003e\n\n**Additional Info**\u003cbr\u003e\n`The project path is at`\u003cbr\u003e\u003cbr\u003e\n```\ncd \"$(npm root -g)/macaca-ios/node_modules/xctestwd\"\n```\n\n`Set up the linebreak for swift error and exceptions:`\u003cbr\u003e\u003cbr\u003e\n\u003cimg width=\"267\" alt=\"2017-12-14 10 56 33\" src=\"https://user-images.githubusercontent.com/8198256/33973562-9153137a-e0be-11e7-9ef0-b2d06bbd32c8.png\"\u003e\n\n`Run your command regularly, once the driver has been initialized, attach the process:`\u003cbr\u003e\u003cbr\u003e\n\u003cimg width=\"843\" alt=\"2017-12-14 10 55 14\" src=\"https://user-images.githubusercontent.com/8198256/33973561-912c0dde-e0be-11e7-824c-bfa5df42e889.png\"\u003e\n\n### 4.2 Swift modules fails to compile\n\nCheck carthage installation\n\n### 4.3 Debug info\n\nNow XCTestWD supports gathering debug log into log files which is stored in \"Your-App-Sandbox-Root\"/Documents/Logs dir. For real devices, you can connect to itunes and choose backup for `XCTestWDUITests` and get the debug log. For iOS simulators, the log file is in your computer's simulator app directory like:\n\n```\n\"/Users/${user-name}/Library/Developer/CoreSimulator/Devices \\\n/${device-id}/data/Containers/Data/Application/${app-id}/Documents/Logs\"\n```\n\nYou can use `xcrun simctl list` to get the id of the booted device.\n\n### 4.4\n\nuser PATH variable MACACA_XCTESTWD_ROOT_PATH to override the default one.\n\n```bash\nMACACA_XCTESTWD_ROOT_PATH=/path/to/macaca_xctest app-inspector -u xxx --verbose\n```\n\n### 4.5\n\nWe update dependencies by using other npm packages, because the XCode upgrade swift syntax is often not backward compatible.\n\n| package | XCode version | notes |\n| --- | --- | --- |\n| [xctestwd-frameworks](https://github.com/macacajs/xctestwd-frameworks) | 11.2.1 | |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacacajs%2Fxctestwd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacacajs%2Fxctestwd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacacajs%2Fxctestwd/lists"}