This document describes building, testing, releasing Protractor and provides an overview of the repository layout.\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22612}{}\doxysection{Prerequisite software}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22612}
The prerequisite software (Node.\+js, npm, git, jdk) are the same as for angular. See \href{https://github.com/angular/angular/blob/master/docs/DEVELOPER.md\#prerequisite-software}{\texttt{ https\+://github.\+com/angular/angular/blob/master/docs/\+DEVELOPER.\+md\#prerequisite-\/software}}\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22613}{}\doxysection{Getting the sources}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22613}
Fork Protractor from github, then clone your fork with\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git clone git@github.com:<github username>/protractor.git}
\DoxyCodeLine{}
\DoxyCodeLine{\# Go to the Protractor directory:}
\DoxyCodeLine{cd protractor/}
\DoxyCodeLine{}
\DoxyCodeLine{\# Add the main protractor repository as an upstream remote to your repository:}
\DoxyCodeLine{git remote add upstream https://github.com/angular/protractor.git }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22614}{}\doxysection{Installing and Building}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22614}
All Protractor dependencies come from npm. Install with\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{npm install }

\end{DoxyCode}


This will also trigger our build step. The build step runs the Type\+Script compiler and copies necessary files into the output {\ttfamily built} directory. To run the build step independently, run\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{npm run prepublish }

\end{DoxyCode}


You can see the other available npm scripts in {\ttfamily package.\+json}. Note that most of these scripts just call our {\ttfamily gulp} commands, which can be seen in {\ttfamily gulpfile.\+js}.\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22615}{}\doxysection{Formatting}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22615}
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\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{npm run format }

\end{DoxyCode}


You can check that you will pass lint tests with\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{gulp lint}
\DoxyCodeLine{}
\DoxyCodeLine{\# or if you don't have gulp installed globally:}
\DoxyCodeLine{./node\_modules/.bin/gulp lint }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22616}{}\doxysection{Code layout}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22616}
{\ttfamily docs/} contains markdown documentation files. {\ttfamily lib/} contains the actual Protractor code. {\ttfamily scripts/} contains scripts used for CI setup and running tests. {\ttfamily spec/} contains e2e and unit tests and configuration files for tests. {\ttfamily testapp/} contains the code for the Angular applications that e2e tests run against. {\ttfamily website/} contains code for generating Protractor API documentation and the website at protractortest.\+org.

Most of the code is written in Type\+Script, with the exception of a few js files.

{\ttfamily lib/debugger} is for element explorer, {\ttfamily browser.\+pause} and {\ttfamily browser.\+explore}. {\ttfamily lib/driver\+Providers} controls how Web\+Driver instances are created. {\ttfamily lib/frameworks} contains adapters for test frameworks such as Jasmine and Mocha. {\ttfamily lib/selenium-\/webdriver} and {\ttfamily lib/webdriver-\/js-\/extender} are used ONLY for API documentation generation.\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22617}{}\doxysection{Lightning Code Walkthrough}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22617}
TBD.\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22618}{}\doxysection{Testing}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22618}
Run {\ttfamily 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\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{webdriver-\/manager update}
\DoxyCodeLine{webdriver-\/manager start }

\end{DoxyCode}


and


\begin{DoxyCode}{0}
\DoxyCodeLine{npm start }

\end{DoxyCode}


This suite is described in {\ttfamily 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 {\ttfamily browser.\+pause} and element explorer.

End to end tests all have configuration files which live in {\ttfamily spec/}. Many tests do not need an actual Selenium server backing them and use the {\ttfamily mock\+Selenium} configuration, which saves time by not connecting to a real selenium server.\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22619}{}\doxysection{Important dependencies}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22619}
Protractor has very close dependencies with several other projects under the Angular umbrella\+:

{\ttfamily jasminewd2} is an extension of the Jasmine test framework that adds utilities for working with selenium-\/webdriver. \href{https://github.com/angular/jasminewd}{\texttt{ jasminewd}}

{\ttfamily 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. \href{https://github.com/angular/blocking-proxy}{\texttt{ blocking-\/proxy}}

{\ttfamily 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. \href{https://github.com/angular/webdriver-manager}{\texttt{ webdriver-\/manager}}

{\ttfamily webdriver-\/js-\/extender} extends selenium-\/webdriver to add Appium commands. \href{https://github.com/angular/webdriver-js-extender}{\texttt{ webdriver-\/js-\/extender}}\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22620}{}\doxysection{Continuous Integration}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22620}
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 Sauce\+Labs because we have more vm time on Travis and their integration with Sauce\+Labs is smooth. Circle\+CI 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 Sauce\+Labs against a variety of browsers. The essential browsers run a more complete test suite, {\ttfamily specified by spec/ci\+Full\+Conf.\+js}. We also run a set of smoke tests against a larger set of browsers, which is allowed to fail -\/ this is configured in {\ttfamily spec/ci\+Smoke\+Conf.\+js}. This is due to flakiness in IE, Safari and older browser versions. We also run a small set of tests using Browser\+Stack to verify that our integration with their Selenium farm works.

Circle CI runs a slightly modified version of {\ttfamily 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.\hypertarget{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22621}{}\doxysection{Releasing}\label{md_sfcode_node_modules_protractor_DEVELOPER_autotoc_md22621}
See \href{https://github.com/angular/protractor/blob/master/release.md}{\texttt{ release.\+md}} for full instructions. 