From 4d436800de5017ae0a7246a939519644e72acafe Mon Sep 17 00:00:00 2001
From: Paul Gschwendtner <paulgschwendtner@gmail.com>
Date: Wed, 14 Aug 2019 18:20:39 +0200
Subject: [PATCH] docs: add guide to reproduce material-unit-test failures
 locally (#32138)

Adds a new guide that can be used to reproduce failures
reported in the `material-unit-tests` job locally.

The document should live in the framework repository as
the package building scripts are local to the framework
repository.

PR Close #32138
---
 docs/DEBUG_MATERIAL_IVY.md | 40 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/DEBUG_MATERIAL_IVY.md

diff --git a/docs/DEBUG_MATERIAL_IVY.md b/docs/DEBUG_MATERIAL_IVY.md
new file mode 100644
index 0000000000..b4bfbf4b5f
--- /dev/null
+++ b/docs/DEBUG_MATERIAL_IVY.md
@@ -0,0 +1,40 @@
+# Debugging the Material unit tests job
+
+Currently all changes to Ivy are validated against the test suite of the
+`angular/components` repository. In order to debug the `material-unit-tests` CI
+job, the following steps can be used:
+
+1\) Build the Ivy package output by running `./scripts/build-ivy-npm-packages.sh` in
+the `angular/angular` repo.
+
+2\) Clone the `angular/components` repository if not done yet ([quick link to repo](https://github.com/angular/components)).
+
+3\) Set up the package output in the `components` repository by running the following
+command in the `angular/angular` repo:
+
+```bash
+node ./scripts/ci/update-deps-to-dist-packages.js {COMPONENTS_REPO}/package.json ./dist/packages-dist-ivy-aot
+```
+
+4\) Switch into the `components` repository and run the tests by using the
+following command:
+
+```bash
+yarn test --deleted_packages=//src/dev-app --define=compile=aot
+```
+
+### Running tests for individual entry-points
+
+The `yarn test` script from the `components` repository runs all tests in the project.
+This is sometimes not desired because it involves building and testing of all packages
+and entry-points. Running tests for an individual entry-point is possible by explicitly
+selecting a given test target.
+
+Here is an example of commands that run individual test targets. Note that it is
+**important** to specify the `--define=compile=aot` flag in order to run tests with Ivy.
+  
+```bash
+yarn bazel test --define=compile=aot src/material/slider:unit_tests
+yarn bazel test --define=compile=aot src/cdk/a11y:unit_tests
+yarn bazel test --define=compile=aot src/material/toolbar:unit_tests
+``` 
\ No newline at end of file