diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad0d0c724..a8c2d77ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,15 @@ -# Contributing to WebDriverAgent +# Contributing to WebDriverAgent We want to make contributing to this project as easy and transparent as possible. ## Pull Requests We actively welcome your pull requests. -1. Fork the repo and create your branch from `master`. +1. Fork the repo and create your branch from `master`. 2. If you've added code that should be tested, add tests -3. If you've changed APIs, update the documentation. -4. Ensure the test suite passes. -5. Make sure your code lints. +3. If you've changed APIs, update the documentation. +4. Ensure the test suite passes. +5. Make sure your code lints. 6. If you haven't already, complete the Contributor License Agreement ("CLA"). ## Contributor License Agreement ("CLA") @@ -32,4 +32,4 @@ outlined on that page and do not file a public issue. ## License By contributing to WebDriverAgent, you agree that your contributions will be licensed -under its BSD license. +under its [BSD license](LICENSE). diff --git a/README.md b/README.md index 21fff3eaf..cc64da07e 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,39 @@ # WebDriverAgent [![GitHub license](https://img.shields.io/badge/license-BSD-lightgrey.svg)](LICENSE) [![Build Status](https://travis-ci.org/facebook/WebDriverAgent.svg?branch=master)](https://travis-ci.org/facebook/WebDriverAgent) [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) -WebDriverAgent is a WebDriver server for iOS that runs inside the Simulator and is written entirely in Objective-C. It works by linking `XCTest.framework` and calling Apple's API to execute commands directly on device / simulator. -If you are looking for WebDriverAgent that uses `UIAutomation.framework` check [here](https://github.com/facebook/WebDriverAgent/tree/master/UIAWebDriverAgent)). +WebDriverAgent is a [WebDriver server](https://w3c.github.io/webdriver/webdriver-spec.html) implementation for iOS that can be used to remote control iOS devices. It allows you to launch & kill applications, tap & scroll views or confirm view presence on a screen. This makes it a perfect tool for application end-to-end testing or general purpose device automation. It works by linking `XCTest.framework` and calling Apple's API to execute commands directly on a device. WebDriverAgent was developed at Facebook and is currently maintained by [Marek Cirkos](https://github.com/marekcirkos) and [Mehdi Mulani](https://github.com/mmmulani). -## Building +## Features + * Works with device & simulator + * Implements most of [WebDriver spec](https://w3c.github.io/webdriver/webdriver-spec.html) + * [USB support](https://github.com/marekcirkos/WebDriverAgent/wiki/USB-support) for devices + * Inspector [endpoint](http://localhost:8100/inspector) with friendly user interface to inspect current device state + * Easy development cycle as it can be launched & debugged directly via Xcode + * Unsupported yet, but works with tvOS & OSX -Our dependencies are tracked with Carthage. First run - -`` -carthage bootstrap --platform ios -`` - -and then open `WebDriverAgent.xcodeproj`. - -## Running - -Enable developer mode: +[![Demo Video](https://j.gifs.com/mZkvqR.gif)](https://youtu.be/EatiYGFxBxY) +## Getting Started +To get the project set up just run bootstrap script: ``` -$ DevToolsSecurity --enable -Developer mode is now enabled. +./Scripts/bootstrap.sh ``` +It will: +* fetch all dependencies with [Carthage](https://github.com/Carthage/Carthage) +* build Inspector bundle using [npm](https://www.npmjs.com) -If developer mode isn't enabled then you'll see this message: -> DTServiceHub: Instruments wants permission to analyze other processes. Please enter an administrator username and password to allow this. -> Failed to authorize rights (0x1) with status: -60007. +After it is finished you can simply open `WebDriverAgent.xcodeproj` and start `WebDriverAgentRunner` test +and start sending [requests](https://github.com/marekcirkos/WebDriverAgent/wiki/Queries). -To play around with WebDriverAgent you can simply start WebDriverAgentRunner tests via Xcode or xcodebuild: -``` -xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'platform=iOS Simulator,name=iPhone 6' test -``` - -When simulator/device launches it should be ready for receiving requests. To get ip address under with device is available you can check device logs for line "ServerURLHere->[DEVICE_URL]<-ServerURLHere" +More about how to start WebDriverAgent [here](https://github.com/marekcirkos/WebDriverAgent/wiki/Starting-WebDriverAgent). -Use curl to start testing the app: -``` -curl -X POST -H "Content-Type: application/json" -d "{\"desiredCapabilities\":{\"bundleId\":\"$BUNDLE_ID\", \"app\":\"/path/to/app/on/local/machine/magicapp.app\"}}" http://[DEVICE_URL]/session/ -``` - -After application launches you can inspect it by opening web browser on [/inspector](https://localhost:8100/inspector) endpoint -or query elements with curl request: -``` -curl -X POST -H "Content-Type: application/json" -d "{\"using\":\"xpath\",\"value\":\"//XCUIElementTypeButton\"}" http://[DEVICE_URL]/session/[SESSION_ID]/elements -``` - -Have fun! +## Known Issues +If you are having some issues please checkout [wiki](https://github.com/marekcirkos/WebDriverAgent/wiki/Common-Issues) first. ## For Contributors - -Please make sure you’ve followed the guidelines in [CONTRIBUTING](CONTRIBUTING.md), if you want to help out. +If you want to help us out, you are more than welcome to. However please make sure you have followed the guidelines in [CONTRIBUTING](CONTRIBUTING.md). ## License [`WebDriverAgent` is BSD-licensed](LICENSE). We also provide an additional [patent grant](PATENTS). + +Have fun!