From c211ef9b2de78c2580fe792ad2a5dca6411d59fd Mon Sep 17 00:00:00 2001
From: Alex Eagle <eagle@post.harvard.edu>
Date: Thu, 9 Feb 2017 09:06:19 -0800
Subject: [PATCH] docs: add documentation for integration test setup (#14368)

---
 integration/README.md    | 54 ++++++++++++++++++++++++++++++++++++++++
 integration/run_tests.sh |  9 ++++++-
 2 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 integration/README.md

diff --git a/integration/README.md b/integration/README.md
new file mode 100644
index 0000000000..2314f71738
--- /dev/null
+++ b/integration/README.md
@@ -0,0 +1,54 @@
+# Integration tests for Angular
+
+This directory contains end-to-end tests for Angular. Each directory is a self-contained
+application that exactly mimics how a user might expect Angular to work, so they allow
+high-fidelity reproductions of real-world issues.
+
+For this to work, we first build the Angular distribution just like we would publish
+it to npm, then install the distribution into each app.
+
+## Writing an integration test
+
+The API for each test is:
+
+- Each sub-directory here is an integration test
+- Each test should have a `package.json` file
+- The test runner will run `yarn` and `yarn test` on the package
+
+This means that the test should be started by test script, like
+```
+'scripts' { 'test': 'runProgramA && assertResultIsGood' }
+```
+
+Note that the `package.json` file uses a special `file://../../dist` scheme
+to reference the Angular packages, so that the locally-built Angular
+is installed into the test app.
+
+Also, beware of floating (non-shrinkwrapped) dependencies. If in doubt
+you can install the package directly from `file:../../node_modules`. For example,
+this is useful for protractor, which has a slow post-install step
+(`webdriver-manager update`) that can be skipped when the package from
+Angular's `node_modules` is installed.
+
+## Running integration tests
+
+The first time you run the tests, you'll need some setup:
+
+```shell
+$ EXPERIMENTAL_ES2015_DISTRO=1 ./build.sh
+$ ./integration/build_rxjs_es6.sh
+```
+
+Now you can iterate on the tests by keeping the dist folder up-to-date.
+See the `package.json` of the test(s) you're debugging, to see which dist/ folders they install from.
+Then run the right `tsc --watch` command to keep those dist folders up-to-date, for example:
+
+```
+$ ./node_modules/.bin/tsc -p modules/@angular/core/tsconfig-build.json --target es2015 --outDir dist/packages-dist-es2015/core --watch
+```
+
+Now you can run the integration test, it will re-install from the dist/ folder on each run.
+
+```
+$ ./integration/run_tests.sh
+```
diff --git a/integration/run_tests.sh b/integration/run_tests.sh
index dc54971ad8..f8236264f3 100755
--- a/integration/run_tests.sh
+++ b/integration/run_tests.sh
@@ -5,7 +5,14 @@ set -e -o pipefail
 cd `dirname $0`
 
 if [ ! -d "rxjs/dist/es6" ]; then
-  echo "You must run build_rxjs_es6.sh before running tests"
+  echo "You must run build the ES2015 version of RxJS for some tests:"
+  echo "./integration/build_rxjs_es6.sh"
+  exit 1
+fi
+
+if [ ! -d "../dist/packages-dist-es2015" ]; then
+  echo "You must build the ES2015 distro for some tests:"
+  echo "EXPERIMENTAL_ES2015_DISTRO=1 ./build.sh"
   exit 1
 fi