| OLD | NEW |
| 1 # Building and Testing AngularDart | 1 # Building and Testing AngularDart |
| 2 | 2 |
| 3 This document describes how to set up your development environment to build and | 3 This document describes how to set up your development environment to build and
test AngularDart, and |
| 4 test AngularDart, and explains the basic mechanics of using `git`, `node`, and | 4 explains the basic mechanics of using `git`, `node`, and `npm`. |
| 5 `npm`. | |
| 6 | 5 |
| 7 See the [contributing guidelines](https://github.com/angular/angular.dart/blob/m
aster/CONTRIBUTING.md) | 6 See the [contributing guidelines](https://github.com/angular/angular.dart/blob/m
aster/CONTRIBUTING.md) for how to contribute your own code to |
| 8 for how to contribute your own code to | |
| 9 | 7 |
| 10 1. [Prerequisite Software](#prerequisite-software) | 8 1. [Prerequisite Software](#prerequisite-software) |
| 11 2. [Getting the Sources](#getting-the-sources) | 9 2. [Getting the Sources](#getting-the-sources) |
| 12 3. [Environment Variable Setup](#environment-variable-setup) | 10 3. [Environment Variable Setup](#environment-variable-setup) |
| 13 4. [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-p
ackages) | 11 4. [Installing NPM Modules and Dart Packages](#installing-npm-modules-and-dart-p
ackages) |
| 14 5. [Running Tests Locally](#running-tests-locally) | 12 5. [Running Tests Locally](#running-tests-locally) |
| 15 6. [Dart Editor configuration](#dart-editor-configuration) | 13 6. [Continuous Integration using Travis](#continuous-integration-using-travis) |
| 16 7. [WebStorm configuration](#webstorm-configuration) | |
| 17 8. [Continuous Integration using Travis](#travis-ci) | |
| 18 | 14 |
| 19 ## Prerequisite Software | 15 ## Prerequisite Software |
| 20 | 16 |
| 21 Before you can build and test AngularDart, you must install and configure the | 17 Before you can build and test AngularDart, you must install and configure the |
| 22 following products on your development machine: | 18 following products on your development machine: |
| 23 | 19 |
| 24 * [Dart](https://www.dartlang.org/): as can be expected, AngularDart requires | 20 * [Dart](https://www.dartlang.org/): as can be expected, AngularDart requires |
| 25 an installation of the Dart-SDK and Dartium (a version of | 21 an installation of the Dart-SDK and Dartium (a version of |
| 26 [Chromium](http://www.chromium.org) with native support for Dart through the | 22 [Chromium](http://www.chromium.org) with native support for Dart through the |
| 27 Dart VM). One of the **simplest** ways to get both is to install the **Dart | 23 Dart VM). One of the **simplest** ways to get both is to install the **Dart |
| 28 Editor bundle**, which includes the editor, sdk and Dartium. See the [Dart | 24 Editor bundle**, which includes the editor, sdk and Dartium. See the [Dart |
| 29 tools download page for | 25 tools download page for |
| 30 instructions](https://www.dartlang.org/tools/download.html). | 26 instructions](https://www.dartlang.org/tools/download.html). |
| 31 | 27 |
| 32 * [Git](http://git-scm.com/) and/or the **Github app** (for | 28 * [Git](http://git-scm.com/) and/or the **Github app** (for |
| 33 [Mac](http://mac.github.com/) or [Windows](http://windows.github.com/)): the | 29 [Mac](http://mac.github.com/) or [Windows](http://windows.github.com/)): the |
| 34 [Github Guide to Installing | 30 [Github Guide to Installing |
| 35 Git](https://help.github.com/articles/set-up-git) is a good source of | 31 Git](https://help.github.com/articles/set-up-git) is a good source of |
| 36 information. | 32 information. |
| 37 | 33 |
| 38 * [Node.js](http://nodejs.org): We use Node to run a development web server, | 34 * [Node.js](http://nodejs.org): We use Node to run a development web server, |
| 39 run tests, and generate distributable files. We also use Node's Package | 35 run tests, and generate distributable files. We also use Node's Package |
| 40 Manager (`npm`). Depending on your system, you can install Node either from | 36 Manager (`npm`). Depending on your system, you can install Node either from |
| 41 source or as a pre-packaged bundle. | 37 source or as a pre-packaged bundle. |
| 42 | 38 |
| 43 ## Getting the Sources | 39 ## Getting the Sources |
| 44 | 40 |
| 45 Forking and Cloning the AngularDart repository: | 41 Forking and Cloning the AngularDart repository: |
| 46 | 42 |
| 47 1. Login to your Github account or create one by following the instructions | 43 1. Login to your Github account or create one by following the instructions give
n [here](https://github.com/signup/free). |
| 48 given [here](https://github.com/signup/free). | |
| 49 Afterwards. | 44 Afterwards. |
| 50 2. [Fork](http://help.github.com/forking) the [main AngularDart repository] | 45 2. [Fork](http://help.github.com/forking) the [main AngularDart repository](http
s://github.com/angular/angular.dart). |
| 51 (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: |
| 52 3. Clone your fork of the AngularDart repository and define an `upstream` remote | |
| 53 pointing back to the AngularDart repository that you forked in the first place: | |
| 54 | 47 |
| 55 ```shell | 48 ```shell |
| 56 # Clone your Github repository: | 49 # Clone your Github repository: |
| 57 git clone git@github.com:<github username>/angular.dart.git | 50 git clone git@github.com:<github username>/angular.dart.git |
| 58 | 51 |
| 59 # Go to the AngularDart directory: | 52 # Go to the AngularDart directory: |
| 60 cd angular.dart | 53 cd angular.dart |
| 61 | 54 |
| 62 # Add the main AngularDart repository as an upstream remote to your repository: | 55 # Add the main AngularDart repository as an upstream remote to your repository: |
| 63 git remote add upstream https://github.com/angular/angular.dart.git | 56 git remote add upstream https://github.com/angular/angular.dart.git |
| 64 ``` | 57 ``` |
| 65 | 58 |
| 66 ## Environment Variable Setup | 59 ## Environment Variable Setup |
| 67 | 60 |
| 68 | 61 |
| 69 Define the environment variables listed below. These are mainly needed for the | 62 Define the environment variables listed below. These are mainly needed for the |
| 70 test scripts. The notation shown here is for | 63 test scripts. The notation shown here is for |
| 71 [`bash`](http://www.gnu.org/software/bash/); adapt as appropriate for your | 64 [`bash`](http://www.gnu.org/software/bash/); adapt as appropriate for your |
| 72 favorite shell. (Examples given below of possible values for initializing the | 65 favorite shell. (Examples given below of possible values for initializing the |
| 73 environment variables assume Mac OS X and that you have installed the Dart | 66 environment variables assume Mac OS X and that you have installed the Dart |
| 74 Editor in the directory named by `$DART_EDITOR_DIR`. This is only for | 67 Editor in the directory named by `$DART_EDITOR_DIR`. This is only for |
| 75 illustrative purposes.) | 68 illustrative purposes.) |
| 76 | 69 |
| 77 ```shell | 70 ```shell |
| 78 # CHROME_BIN: path to a Chrome browser executable; e.g., | 71 # CHROME_BIN: path to a Chrome browser executable; e.g., |
| 79 export CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" | 72 export CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" |
| 80 | 73 |
| 81 # DARTIUM_BIN: path to a Dartium browser executable; e.g., | 74 # CHROME_CANARY_BIN: path to a Dartium browser executable; e.g., |
| 82 export DARTIUM_BIN="$DART_EDITOR_DIR/chromium/Chromium.app/Contents/MacOS/Chromi
um" | 75 export CHROME_CANARY_BIN="$DART_EDITOR_DIR/chromium/Chromium.app/Contents/MacOS/
Chromium" |
| 83 ``` | 76 ``` |
| 84 **Note**: the `$DARTIUM_BIN` environment variable is used by karma to run | 77 **Note**: the `$CHROME_CANARY_BIN` environment variable is used by karma to run
your tests |
| 85 your tests in dartium instead of chromium. If you don't do this, the dart2js | 78 in dartium instead of chromium. If you don't do this, the dart2js compile will m
ake the tests |
| 86 compile will make the tests run extremely slow since it has to wait for a full | 79 run extremely slow since it has to wait for a full js compile each time. |
| 87 js compile each time. | |
| 88 | 80 |
| 89 You should also add the Dart SDK `bin` directory to your path and/or define | 81 You should also add the Dart SDK `bin` directory to your path and/or define `DAR
T_SDK`; e.g. |
| 90 `DART_SDK`; e.g. | |
| 91 | 82 |
| 92 ```shell | 83 ```shell |
| 93 # DART_SDK: path to a Dart SDK directory; e.g., | 84 # DART_SDK: path to a Dart SDK directory; e.g., |
| 94 export DART_SDK="$DART_EDITOR_DIR/dart-sdk" | 85 export DART_SDK="$DART_EDITOR_DIR/dart-sdk" |
| 95 | 86 |
| 96 # Update PATH to include the Dart SDK bin directory | 87 # Update PATH to include the Dart SDK bin directory |
| 97 PATH+=":$DART_SDK/bin" | 88 PATH+=":$DART_SDK/bin" |
| 98 ``` | 89 ``` |
| 99 ## Installing NPM Modules and Dart Packages | 90 ## Installing NPM Modules and Dart Packages |
| 100 | 91 |
| (...skipping 17 matching lines...) Expand all Loading... |
| 118 To run base tests: | 109 To run base tests: |
| 119 | 110 |
| 120 ```shell | 111 ```shell |
| 121 # Source a script to define yet more environment variables | 112 # Source a script to define yet more environment variables |
| 122 . ./scripts/env.sh | 113 . ./scripts/env.sh |
| 123 | 114 |
| 124 # Run io tests: | 115 # Run io tests: |
| 125 dart --checked test/io/all.dart | 116 dart --checked test/io/all.dart |
| 126 | 117 |
| 127 # Run expression extractor tests: | 118 # Run expression extractor tests: |
| 128 ./scripts/test-expression-extractor.sh | 119 scripts/test-expression-extractor.sh |
| 129 | 120 |
| 130 # Run the Dart Analyzer: | 121 Run the Dart Analyzer: |
| 131 ./scripts/analyze.sh | 122 ./scripts/analyze.sh |
| 132 ``` | 123 ``` |
| 133 | 124 |
| 134 To run Karma tests over Dartium, execute the following shell commands (which | 125 To run Karma tests over Dartium, execute the following shell commands (which |
| 135 will launch the Karma server): | 126 will launch the Karma server): |
| 136 | 127 |
| 137 ```shell | 128 ```shell |
| 138 . ./scripts/env.sh | 129 . ./scripts/env.sh |
| 139 node "node_modules/karma/bin/karma" start karma.conf \ | 130 node "node_modules/karma/bin/karma" start karma.conf \ |
| 140 --reporters=junit,dots --port=8765 --runner-port=8766 \ | 131 --reporters=junit,dots --port=8765 --runner-port=8766 \ |
| 141 --browsers=Dartium | 132 --browsers=Dartium |
| 142 ``` | 133 ``` |
| 143 | 134 |
| 144 In another shell window or tab, or from your favorite IDE, launch the Karma | 135 In another shell window or tab, or from your favorite IDE, launch the Karma |
| 145 tests proper by executing: | 136 tests proper by executing: |
| 146 | 137 |
| 147 ```shell | 138 ```shell |
| 148 . ./scripts/env.sh | 139 . ./scripts/env.sh |
| 149 ./scripts/karma_run.sh | 140 karma_run.sh |
| 150 ``` | 141 ``` |
| 151 | 142 |
| 152 **Note:**: If the dart analyzer fails with warnings, the tests will not run. | 143 **Note:**: If the dart analyzer fails with warnings, the tests will not run. |
| 153 You can manually run the tests if this happens: | 144 You can manually run the tests if this happens: |
| 154 | 145 |
| 155 ```shell | 146 ```shell |
| 156 karma run --port=8765 | 147 karma run --port=8765 |
| 157 ``` | 148 ``` |
| 158 | 149 |
| 159 **Note**: If you want to only run a single test you can alter the test you wish | 150 ## Debugging |
| 160 to run by changing `it` to `iit` or `describe` to `ddescribe`. This will only | |
| 161 run that individual test and make it much easier to debug. `xit` and `xdescribe` | |
| 162 can also be useful to exclude a test and a group of tests respectively. | |
| 163 | 151 |
| 164 ## Dart Editor configuration | 152 In the dart editor you can configure a dartium launch target for the karma test
runner debug page. |
| 165 | 153 The menu option is under Run > Manage Launches > Create new Dartium Launch. |
| 166 In the dart editor you can configure a dartium launch target for the karma test | |
| 167 runner debug page. The menu option is under "Run > Manage Launches > Create new | |
| 168 Dartium Launch". | |
| 169 | 154 |
| 170 ``` | 155 ``` |
| 171 http://localhost:8765/debug.html | 156 http://localhost:8765/debug.html |
| 172 ``` | 157 ``` |
| 173 | 158 |
| 174 ## WebStorm configuration | 159 If you want to only run a single test you can alter the test you wish to run by
changing `it` to `iit` |
| 160 or `describe` to `ddescribe`. This will only run that individual test and make i
t much easier to debug. |
| 175 | 161 |
| 176 ### Recent releases | |
| 177 | 162 |
| 178 With the recent releases of WebStorm and the karma plugin, you could run the | |
| 179 test suite by only adding a karma run configuration. | |
| 180 | |
| 181 Right-click on the `karma.conf.js` at the root of the project and select | |
| 182 "create 'karma.conf.js'...". | |
| 183 | |
| 184 Set the parameters as follow: | |
| 185 - **Node interpreter**: `/path/to/node` | |
| 186 - **Karma node package**: `/path/to/node_modules/karma` | |
| 187 - **Configuration file (usually *.conf.js)**: `path/to/angular.dart/karma.conf.j
s` | |
| 188 - **Environment variables**: | |
| 189 - **DARTIUM_BIN**: `/path/to/dartium` | |
| 190 - **PATH**: `/path/to/dart-sdk/bin` | |
| 191 - **DART_FLAGS**: `--checked` | |
| 192 | |
| 193 Now just hit the run button next to the configuration name in the Toolbar and | |
| 194 you should see the test running. The test suite is automatically executed each | |
| 195 time a source file is modified. | |
| 196 | |
| 197 If you encounter troubles with this configuration, try using the one from the | |
| 198 following section. | |
| 199 | |
| 200 ### Former releases | |
| 201 | |
| 202 Start by creating a run configuration to launch the Karma server. Go to the menu | |
| 203 "Run > Edit Configuration Menu" add create a `Node.js` configuration named | |
| 204 "Karma server". | |
| 205 | |
| 206 Set the parameters as follow: | |
| 207 - **Node interpreter**: `/path/to/node` | |
| 208 - **Working directory**: `/path/to/angular.dart` | |
| 209 - **JavaScript file**: `node_modules/karma/bin/karma` | |
| 210 - **Application parameters**: `start karma.conf --reporters dots --port 8765 --b
rowsers=Dartium` | |
| 211 - **Environment variables**: | |
| 212 - **DARTIUM_BIN**: `/path/to/dartium` | |
| 213 - **PATH**: `/path/to/dart-sdk/bin` | |
| 214 - **DART_FLAGS**: `--checked` | |
| 215 | |
| 216 Launch the server by selecting the "Karmer server" configuration in the toolbar | |
| 217 and pressing the play icon. You should see the following message at the bottom | |
| 218 of the run window: | |
| 219 `INFO [Chrome 34.0.1847 (Linux)]: Connected on socket 97GpzQz-MfHFPHgHOVkc with
id 10199707` | |
| 220 | |
| 221 #### Running the tests | |
| 222 | |
| 223 You need to create a "Karma tests" run configuration. Start by copying the | |
| 224 "Karma server" run configuration and xhange the **Application parameters** to | |
| 225 `run --port=8765`. | |
| 226 | |
| 227 To execute the test suite, you just need to run this "Karma tests" | |
| 228 configuration. You should make sure to execute "Karma server" first _(You do not | |
| 229 need to restart the server once it has been started once)_. | |
| 230 | |
| 231 #### Debugging | |
| 232 | |
| 233 You need to create a "JavaScript Debug" configuration named "Karma debug". Set | |
| 234 the parameters as follow: | |
| 235 - **URL**: `http://localhost:8765/debug.html` | |
| 236 - **Browser**: Dartium, | |
| 237 - **Remote URLs of local files (optional)**: | |
| 238 - `path/to/angular.dart`: `http://localhost:8765/base` | |
| 239 - `path/to/angular.dart/lib`: `http://localhost:8765/package:angular` | |
| 240 | |
| 241 You can now put breakpoint in your karma tests, run this configuration and debug | |
| 242 your tests step by step. | |
| 243 | |
| 244 You might be asked to install the "JetBrains IDE Support" in Dartium, if not you | |
| 245 can install it [manually](https://chrome.google.com/webstore/detail/jetbrains-id
e-support/hmhgeddbohgjknpmjagkdomcpobmllji). | |
| 246 | |
| 247 <a name="travis-ci"></a> | |
| 248 ## Continuous Integration using Travis | 163 ## Continuous Integration using Travis |
| 249 | 164 |
| 250 See the instructions given [here](https://github.com/angular/angular.dart/blob/m
aster/travis.md). | 165 See the instructions given [here](https://github.com/angular/angular.dart/blob/m
aster/travis.md). |
| 251 | 166 |
| 252 | 167 ----- |
| OLD | NEW |