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

Commit af6afa6

Browse files
juliemrjuliemr
authored
docs(developers): add basic DEVELOPER.md and update README (#4026)
1 parent f1971b7 commit af6afa6

File tree

2 files changed

+158
-37
lines changed

2 files changed

+158
-37
lines changed

‎DEVELOPER.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Building and Testing Protractor
2+
3+
This document describes building, testing, and releasing Protractor, and provides an overview of
4+
the repository layout.
5+
6+
## Prerequisite software
7+
8+
The prerequisite software (Node.js, npm, git, jdk) are the same as for angular. See
9+
https://github.com/angular/angular/blob/master/DEVELOPER.md#prerequisite-software
10+
11+
## Getting the sources
12+
13+
Fork Protractor from github, then clone your fork with
14+
15+
```
16+
git clone [email protected]:<github username>/protractor.git
17+
18+
# Go to the Protractor directory:
19+
cd protractor
20+
21+
# Add the main protractor repository as an upstream remote to your repository:
22+
git remote add upstream https://github.com/angular/protractor.git
23+
```
24+
25+
## Installing and Building
26+
27+
All Protractor dependencies come from npm. Install with
28+
29+
```
30+
npm Install
31+
```
32+
33+
This will also trigger our build step. The build step runs the TypeScript compiler
34+
and copies necessary files into the output `built` directory. To run the build step
35+
independently, run:
36+
37+
```
38+
npm run prepublish
39+
```
40+
41+
You can see the other available npm scripts in `package.json`. Note that most of these
42+
scripts just call our `gulp` commands, which can be seen in `gulpfile.js`.
43+
44+
## Formatting
45+
46+
Protractor uses clang-format to format the source code. If the source code is not properly formatted,
47+
the CI will fail and the PR can not be merged.
48+
49+
You can automatically format your code by running:
50+
51+
```
52+
npm run format
53+
```
54+
55+
You can check that you will pass lint tests with:
56+
57+
```
58+
gulp lint
59+
60+
# or if you don't have gulp installed globally
61+
./node_modules/.bin/gulp lint
62+
```
63+
64+
## Code layout
65+
66+
`docs/` contains markdown documentation files.
67+
`lib/` contains the actual Protractor code.
68+
`scripts/` contains scripts used for CI setup and running tests.
69+
`spec/` contains e2e and unit tests and configuration files for tests.
70+
`testapp/` contains the code for the Angular applications that e2e tests run against.
71+
`website/` contains code for generating Protractor API documentation and the website at protractortest.org
72+
73+
Most of the code is written in TypeScript, with the exception of a few js files.
74+
75+
`lib/debugger` is for element explorer, `browser.pause`, and `browser.explore`
76+
`lib/driverProviders` controls how WebDriver instances are created
77+
`lib/frameworks` contains adapters for test frameworks such as Jasmine and Mocha
78+
`lib/selenium-webdriver` and `lib/webdriver-js-extender` are used ONLY for API documentation generation.
79+
80+
## Lightning Code Walkthrough
81+
82+
TBD.
83+
84+
## Testing
85+
86+
Run `npm test` to run the full test suite. This assumes that you have the testapp and a
87+
selenium server running. Start these as separate processes with:
88+
89+
```
90+
webdriver-manager update
91+
webdriver-manager start
92+
```
93+
94+
and
95+
96+
```
97+
npm start
98+
```
99+
100+
This suite is described in `scripts/test.js`. It uses some small helper functions to run commands
101+
as child processes and capture the results, so that we can run protractor commands which should
102+
result in failures and verify that we get the expected number and type of failures.
103+
104+
The suite contains unit tests, end to end tests using the built binary, and interactive tests.
105+
Interactive tests are for testing `browser.pause` and element explorer.
106+
107+
End to end tests all have configuration files which live in `spec/`. Many tests do not need
108+
an actual Selenium server backing them, and use the `mockSelenium` configuration, which saves
109+
time by not connecting to a real selenium server.
110+
111+
## Important dependencies
112+
113+
Protractor has very close dependencies with several other projects under the Angular umbrella:
114+
115+
`jasminewd2` is an extension of the Jasmine test framework that adds utilities for
116+
working with selenium-webdriver. github.com/angular/jasminewd
117+
118+
`blocking-proxy` is a separate binary, which handles traffic between a test script and
119+
webdriver. It can be turned on via a protractor configuration file, and in the future
120+
all logic to wait for Angular will be handled through the blocking proxy.
121+
github.com/angular/blocking-proxy
122+
123+
`webdriver-manager` is a separate binary which manages installing and starting up
124+
the various binaries necessary for running webdriver tests. These binaries include
125+
specific drivers for various browsers (e.g. chromedriver) and the selenium standalone
126+
server.
127+
128+
`webdriver-js-extender` extends selenium-webdriver to add Appium commands.
129+
github.com/angular/webdriver-js-extender
130+
131+
## Continuous Integration
132+
133+
PRs or changes submitted to master will automatically trigger continuous integration on two
134+
different services - Travis, and Circle CI. We use Travis for tests run with SauceLabs because
135+
we have more vm time on Travis and their integration with SauceLabs is smooth. CircleCI gives us
136+
greater control over the vm, which allows us to run tests against local browsers and get better
137+
logs.
138+
139+
Travis runs e2e tests via SauceLabs against a variety of browsers. The essential browsers run a
140+
more complete test suite, `specified by spec/ciFullConf.js`. We also run a set of smoke tests
141+
against a larger set of browsers, which is allowed to fail - this is configured in
142+
`spec/ciSmokeConf.js`. This is due to flakiness in IE, Safari and older browser versions.
143+
We also run a small set of tests using BrowserStack to verify that our integration with their
144+
Selenium farm works.
145+
146+
Circle CI runs a slightly modified version of `npm test` in a single VM. It installs
147+
the browsers it needs locally. Circle CI runs unit tests and a set of e2e tests against Chrome.
148+
149+
## Releasing
150+
151+
See `release.md` for full instructions.

‎README.md

Lines changed: 7 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,23 @@
11
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)
22
==========
33

4-
[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.
4+
[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.
55

66
Compatibility
77
-------------
88

9-
Protractor 4 is compatible with nodejs v4 and newer. If you absolutely need to use nodejs at 0.12, use Protractor@2.
9+
Protractor 5 is compatible with nodejs v6 and newer.
1010

11-
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`.
11+
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`.
1212

1313

1414
Getting Started
1515
---------------
16-
17-
The Protractor documentation for users is located in the [protractor/docs](https://github.com/angular/protractor/tree/master/docs) folder.
16+
See the [Protractor Website](http://www.protractortest.org) for most documentation.
1817

1918
To get set up and running quickly:
20-
- The [Protractor Website](http://angular.github.io/protractor)
21-
- Work through the [Tutorial](http://angular.github.io/protractor/#/tutorial)
22-
- Take a look at the [Table of Contents](http://angular.github.io/protractor/#/toc)
19+
- Work through the [Tutorial](http://www.protractortest.org/#/tutorial)
20+
- See the [API](http://www.protractortest.org/#/api)
2321

2422
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.
2523

@@ -36,32 +34,4 @@ Please ask usage and debugging questions on [StackOverflow](http://stackoverflow
3634

3735
For Contributors
3836
----------------
39-
Clone the github repository:
40-
41-
git clone https://github.com/angular/protractor.git
42-
cd protractor
43-
npm install
44-
./bin/webdriver-manager update
45-
cd website
46-
npm install
47-
cd ..
48-
49-
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
50-
[bin/webdriver-manager](https://github.com/angular/protractor/blob/master/bin/webdriver-manager).
51-
52-
webdriver-manager update
53-
webdriver-manager start
54-
55-
Protractor's test suite runs against the included test application.
56-
57-
Install the test application dependencies with:
58-
59-
npm run install_testapp
60-
61-
Start that up with
62-
63-
npm start
64-
65-
Then run the tests with
66-
67-
npm test
37+
See DEVELOPER.md

0 commit comments

Comments
 (0)