Skip to content
This repository was archived by the owner on Feb 22, 2018. It is now read-only.

Commit eaaa337

Browse files
chalinmhevery
chalin
authored and
mhevery
committed
docs(contributing): add developer docs explaining how to setup and run tests
- Create a first version of developer documentation explaining how to setup and run AngularDart tests locally and on Travis. - Update `CONTRIBUTING.md` to refer to this new doc. Closes #322. Assumes #545. Closes #548
1 parent e2a00ab commit eaaa337

File tree

2 files changed

+143
-5
lines changed

2 files changed

+143
-5
lines changed

‎CONTRIBUTING.md

+2-5
Original file line numberDiff line numberDiff line change
@@ -90,11 +90,7 @@ Before you submit your pull request consider the following guidelines:
9090
git commit -a
9191
```
9292

93-
* Build your changes locally to ensure all the tests pass
94-
95-
```shell
96-
./run-test.sh
97-
```
93+
* Build your changes locally to ensure all the tests pass: see the [developer documentation][dev-doc].
9894

9995
* Push your branch to Github:
10096

@@ -226,3 +222,4 @@ changes to be accepted, the CLA must be signed. It's a quick process, we promise
226222
[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
227223
[communityMilestone]: https://github.com/angular/angular.dart/issues?milestone=13&state=open
228224
[coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md
225+
[dev-doc]: https://github.com/angular/angular.dart/blob/master/DEVELOPER.md

‎DEVELOPER.md

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Building and Testing AngularDart
2+
3+
This document describes how to set up your development environment to build and test AngularDart, and
4+
explains the basic mechanics of using `git`, `node`, and `npm`.
5+
6+
See the [contributing guidelines](https://github.com/angular/angular.dart/blob/master/CONTRIBUTING.md) for how to contribute your own code to
7+
8+
1. [Prerequisite Software](#prerequisite-software)
9+
2. [Getting the Sources](#getting-the-sources)
10+
3. [Environment Variable Setup](#environment-variable-setup)
11+
4. [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-packages)
12+
5. [Running Tests Locally](#running-tests-locally)
13+
6. [Continuous Integration using Travis](#continuous-integration-using-travis)
14+
15+
## Prerequisite Software
16+
17+
Before you can build and test AngularDart, you must install and configure the
18+
following products on your development machine:
19+
20+
* [Dart](https://www.dartlang.org/): as can be expected, AngularDart requires
21+
an installation of the Dart-SDK and Dartium (a version of
22+
[Chromium](http://www.chromium.org) with native support for Dart through the
23+
Dart VM). One of the **simplest** ways to get both is to install the **Dart
24+
Editor bundle**, which includes the editor, sdk and Dartium. See the [Dart
25+
tools download page for
26+
instructions](https://www.dartlang.org/tools/download.html).
27+
28+
* [Git](http://git-scm.com/) and/or the **Github app** (for
29+
[Mac](http://mac.github.com/) or [Windows](http://windows.github.com/)): the
30+
[Github Guide to Installing
31+
Git](https://help.github.com/articles/set-up-git) is a good source of
32+
information.
33+
34+
* [Node.js](http://nodejs.org): We use Node to run a development web server,
35+
run tests, and generate distributable files. We also use Node's Package
36+
Manager (`npm`). Depending on your system, you can install Node either from
37+
source or as a pre-packaged bundle.
38+
39+
## Getting the Sources
40+
41+
Forking and Cloning the AngularDart repository:
42+
43+
1. Login to your Github account or create one by following the instructions given [here](https://github.com/signup/free).
44+
Afterwards.
45+
2. [Fork](http://help.github.com/forking) the [main AngularDart repository](https://github.com/angular/angular.dart).
46+
3. Clone your fork of the AngularDart repository and define an `upstream` remote pointing back to the AngularDart repository that you forked in the first place:
47+
48+
```shell
49+
# Clone your Github repository:
50+
git clone [email protected]:<github username>/angular.dart.git
51+
52+
# Go to the AngularDart directory:
53+
cd angular.dart
54+
55+
# Add the main AngularDart repository as an upstream remote to your repository:
56+
git remote add upstream https://github.com/angular/angular.dart.git
57+
```
58+
59+
## Environment Variable Setup
60+
61+
62+
Define the environment variables listed below. These are mainly needed for the
63+
test scripts. The notation shown here is for
64+
[`bash`](http://www.gnu.org/software/bash/); adapt as appropriate for your
65+
favorite shell. (Examples given below of possible values for initializing the
66+
environment variables assume Mac OS X and that you have installed the Dart
67+
Editor in the directory named by `$DART_EDITOR_DIR`. This is only for
68+
illustrative purposes.)
69+
70+
```shell
71+
# CHROME_BIN: path to a Chrome browser executable; e.g.,
72+
export CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
73+
74+
# CHROME_CANARY_BIN: path to a Dartium browser executable; e.g.,
75+
export CHROME_CANARY_BIN="$DART_EDITOR_DIR/chromium/Chromium.app/Contents/MacOS/Chromium"
76+
```
77+
78+
You should also add the Dart SDK `bin` directory to your path and/or define `DART_SDK`; e.g.
79+
80+
```shell
81+
# DART_SDK: path to a Dart SDK directory; e.g.,
82+
export DART_SDK="$DART_EDITOR_DIR/dart-sdk"
83+
84+
# Update PATH to include the Dart SDK bin directory
85+
PATH+=":$DART_SDK/bin"
86+
```
87+
## Installing NPM Modules and Dart Packages
88+
89+
Next, install the modules and packages needed to run AngularDart tests:
90+
91+
```shell
92+
# Install node.js dependencies:
93+
npm install
94+
95+
# Install Dart packages
96+
pub install
97+
```
98+
99+
## Running Tests Locally
100+
101+
NOTE: scripts are being written to embody the following steps.
102+
103+
To run base tests:
104+
105+
```shell
106+
# Source a script to define yet more environment variables
107+
. ./scripts/env.sh
108+
109+
# Run io tests:
110+
$DART --checked test/io/all.dart
111+
112+
# Run expression extractor tests:
113+
scripts/test-expression-extractor.sh
114+
115+
Run the Dart Analyzer:
116+
./scripts/analyze.sh
117+
```
118+
119+
To run Karma tests over Dartium, execute the following shell commands (which
120+
will launch the Karma server):
121+
122+
```shell
123+
. ./scripts/env.sh
124+
node "node_modules/karma/bin/karma" start karma.conf \
125+
--reporters=junit,dots --port=8765 --runner-port=8766 \
126+
--browsers=Dartium
127+
```
128+
129+
In another shell window or tab, or from your favorite IDE, launch the Karma
130+
tests proper by executing:
131+
132+
```shell
133+
. ./scripts/env.sh
134+
karma_run.sh
135+
```
136+
137+
## Continuous Integration using Travis
138+
139+
See the instructions given [here](https://github.com/angular/angular.dart/blob/master/travis.md).
140+
141+
-----

0 commit comments

Comments
 (0)