From 280b91598d5225adb268101e80f0d045128119da Mon Sep 17 00:00:00 2001 From: Julie Ralph Date: Mon, 30 Jan 2017 15:29:06 -0800 Subject: [PATCH] docs(developers): add basic DEVELOPER.md and update README (#4026) --- DEVELOPER.md | 151 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 44 +++------------ 2 files changed, 158 insertions(+), 37 deletions(-) create mode 100644 DEVELOPER.md diff --git a/DEVELOPER.md b/DEVELOPER.md new file mode 100644 index 000000000..cd3a8e9d4 --- /dev/null +++ b/DEVELOPER.md @@ -0,0 +1,151 @@ +# Building and Testing Protractor + +This document describes building, testing, and releasing Protractor, and provides an overview of +the repository layout. + +## Prerequisite software + +The prerequisite software (Node.js, npm, git, jdk) are the same as for angular. See +https://github.com/angular/angular/blob/master/DEVELOPER.md#prerequisite-software + +## Getting the sources + +Fork Protractor from github, then clone your fork with + +``` +git clone git@github.com:/protractor.git + +# Go to the Protractor directory: +cd protractor + +# Add the main protractor repository as an upstream remote to your repository: +git remote add upstream https://github.com/angular/protractor.git +``` + +## Installing and Building + +All Protractor dependencies come from npm. Install with + +``` +npm Install +``` + +This will also trigger our build step. The build step runs the TypeScript compiler +and copies necessary files into the output `built` directory. To run the build step +independently, run: + +``` +npm run prepublish +``` + +You can see the other available npm scripts in `package.json`. Note that most of these +scripts just call our `gulp` commands, which can be seen in `gulpfile.js`. + +## Formatting + +Protractor uses clang-format to format the source code. If the source code is not properly formatted, +the CI will fail and the PR can not be merged. + +You can automatically format your code by running: + +``` +npm run format +``` + +You can check that you will pass lint tests with: + +``` +gulp lint + +# or if you don't have gulp installed globally +./node_modules/.bin/gulp lint +``` + +## Code layout + +`docs/` contains markdown documentation files. +`lib/` contains the actual Protractor code. +`scripts/` contains scripts used for CI setup and running tests. +`spec/` contains e2e and unit tests and configuration files for tests. +`testapp/` contains the code for the Angular applications that e2e tests run against. +`website/` contains code for generating Protractor API documentation and the website at protractortest.org + +Most of the code is written in TypeScript, with the exception of a few js files. + +`lib/debugger` is for element explorer, `browser.pause`, and `browser.explore` +`lib/driverProviders` controls how WebDriver instances are created +`lib/frameworks` contains adapters for test frameworks such as Jasmine and Mocha +`lib/selenium-webdriver` and `lib/webdriver-js-extender` are used ONLY for API documentation generation. + +## Lightning Code Walkthrough + +TBD. + +## Testing + +Run `npm test` to run the full test suite. This assumes that you have the testapp and a +selenium server running. Start these as separate processes with: + +``` +webdriver-manager update +webdriver-manager start +``` + +and + +``` +npm start +``` + +This suite is described in `scripts/test.js`. It uses some small helper functions to run commands +as child processes and capture the results, so that we can run protractor commands which should +result in failures and verify that we get the expected number and type of failures. + +The suite contains unit tests, end to end tests using the built binary, and interactive tests. +Interactive tests are for testing `browser.pause` and element explorer. + +End to end tests all have configuration files which live in `spec/`. Many tests do not need +an actual Selenium server backing them, and use the `mockSelenium` configuration, which saves +time by not connecting to a real selenium server. + +## Important dependencies + +Protractor has very close dependencies with several other projects under the Angular umbrella: + +`jasminewd2` is an extension of the Jasmine test framework that adds utilities for +working with selenium-webdriver. github.com/angular/jasminewd + +`blocking-proxy` is a separate binary, which handles traffic between a test script and +webdriver. It can be turned on via a protractor configuration file, and in the future +all logic to wait for Angular will be handled through the blocking proxy. +github.com/angular/blocking-proxy + +`webdriver-manager` is a separate binary which manages installing and starting up +the various binaries necessary for running webdriver tests. These binaries include +specific drivers for various browsers (e.g. chromedriver) and the selenium standalone +server. + +`webdriver-js-extender` extends selenium-webdriver to add Appium commands. +github.com/angular/webdriver-js-extender + +## Continuous Integration + +PRs or changes submitted to master will automatically trigger continuous integration on two +different services - Travis, and Circle CI. We use Travis for tests run with SauceLabs because +we have more vm time on Travis and their integration with SauceLabs is smooth. CircleCI gives us +greater control over the vm, which allows us to run tests against local browsers and get better +logs. + +Travis runs e2e tests via SauceLabs against a variety of browsers. The essential browsers run a +more complete test suite, `specified by spec/ciFullConf.js`. We also run a set of smoke tests +against a larger set of browsers, which is allowed to fail - this is configured in +`spec/ciSmokeConf.js`. This is due to flakiness in IE, Safari and older browser versions. +We also run a small set of tests using BrowserStack to verify that our integration with their +Selenium farm works. + +Circle CI runs a slightly modified version of `npm test` in a single VM. It installs +the browsers it needs locally. Circle CI runs unit tests and a set of e2e tests against Chrome. + +## Releasing + +See `release.md` for full instructions. diff --git a/README.md b/README.md index c34e3f075..b83eee45e 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,23 @@ Protractor [![Build Status](https://travis-ci.org/angular/protractor.svg?branch=master)](https://travis-ci.org/angular/protractor) [![CircleCI Status](https://circleci.com/gh/angular/protractor.svg?style=shield)](https://circleci.com/gh/angular/protractor) [![Join the chat at https://gitter.im/angular/protractor](https://badges.gitter.im/angular/protractor.svg)](https://gitter.im/angular/protractor) ========== -[Protractor](http://angular.github.io/protractor) is an end-to-end test framework for [AngularJS](http://angularjs.org/) applications. Protractor is a [Node.js](http://nodejs.org/) program built on top of [WebDriverJS](https://github.com/SeleniumHQ/selenium/wiki/WebDriverJs). Protractor runs tests against your application running in a real browser, interacting with it as a user would. +[Protractor](http://angular.github.io/protractor) is an end-to-end test framework for [Angular](http://angular.io/) and [AngularJS](http://angularjs.org) applications. Protractor is a [Node.js](http://nodejs.org/) program built on top of [WebDriverJS](https://github.com/SeleniumHQ/selenium/wiki/WebDriverJs). Protractor runs tests against your application running in a real browser, interacting with it as a user would. Compatibility ------------- -Protractor 4 is compatible with nodejs v4 and newer. If you absolutely need to use nodejs at 0.12, use Protractor@2. +Protractor 5 is compatible with nodejs v6 and newer. -Protractor works with Angular versions greater than 1.0.6/1.1.4, and is compatible with Angular 2 applications. Note that for Angular 2 apps, the `binding` and `model` locators are not supported. We recommend using `by.css`. +Protractor works with AngularJS versions greater than 1.0.6/1.1.4, and is compatible with Angular applications. Note that for Angular apps, the `binding` and `model` locators are not supported. We recommend using `by.css`. Getting Started --------------- - -The Protractor documentation for users is located in the [protractor/docs](https://github.com/angular/protractor/tree/master/docs) folder. +See the [Protractor Website](http://www.protractortest.org) for most documentation. To get set up and running quickly: - - The [Protractor Website](http://angular.github.io/protractor) - - Work through the [Tutorial](http://angular.github.io/protractor/#/tutorial) - - Take a look at the [Table of Contents](http://angular.github.io/protractor/#/toc) + - Work through the [Tutorial](http://www.protractortest.org/#/tutorial) + - See the [API](http://www.protractortest.org/#/api) Once you are familiar with the tutorial, you’re ready to move on. To modify your environment, see the Protractor Setup docs. To start writing tests, see the Protractor Tests docs. @@ -36,32 +34,4 @@ Please ask usage and debugging questions on [StackOverflow](http://stackoverflow For Contributors ---------------- -Clone the github repository: - - git clone https://github.com/angular/protractor.git - cd protractor - npm install - ./bin/webdriver-manager update - cd website - npm install - cd .. - -Start up a selenium server. By default, the tests expect the selenium server to be running at `http://localhost:4444/wd/hub`. A selenium server can be started with [webdriver-manager](https://github.com/angular/webdriver-manager) which is included in -[bin/webdriver-manager](https://github.com/angular/protractor/blob/master/bin/webdriver-manager). - - webdriver-manager update - webdriver-manager start - -Protractor's test suite runs against the included test application. - -Install the test application dependencies with: - - npm run install_testapp - -Start that up with - - npm start - -Then run the tests with - - npm test +See DEVELOPER.md