Skip to content
This repository has been archived by the owner on Jul 29, 2024. It is now read-only.

docs(developers): add basic DEVELOPER.md and update README #4026

Merged
merged 1 commit into from
Jan 30, 2017
Merged

docs(developers): add basic DEVELOPER.md and update README #4026

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions DEVELOPER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:<github username>/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
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can also run linting with $(npm bin)/gulp lint

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done


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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no webdriver-manager?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doh. Added.

## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention why we have two systems? Circle limits you by running instance time, so it's better to keep the Saucelabs tests running on Travis. Also, stdout and stderr logs of all processes as well as a tcpdump of webdriver traffic are all available in the CircleCI artifacts for each build.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


## Releasing

See `release.md` for full instructions.
44 changes: 7 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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