From bbb3f8fa60d5937f3a914a1a9fb498d9a5e970b2 Mon Sep 17 00:00:00 2001
From: Ben Lesh <ben@benlesh.com>
Date: Fri, 10 Aug 2018 12:49:21 -0700
Subject: [PATCH] docs(ivy): add better documentation around debugging ivy
 tests (#25432)

PR Close #25432
---
 docs/BAZEL.md                   | 22 +++++++++++++++++++++-
 packages/core/src/ivy_switch.ts | 23 ++---------------------
 2 files changed, 23 insertions(+), 22 deletions(-)

diff --git a/docs/BAZEL.md b/docs/BAZEL.md
index 4e129f28cb..b10552f6fa 100644
--- a/docs/BAZEL.md
+++ b/docs/BAZEL.md
@@ -68,7 +68,26 @@ new as of May 2017 and not very stable yet.
 You can use [ibazel] to get a "watch mode" that continuously
 keeps the outputs up-to-date as you save sources.
 
+### Various Flags Used For Tests
+
+If you're experiencing problems with seemingly unrelated tests failing, it may be because you're not using the proper flags with your Bazel test runs in Angular.
+
+See also: [`//tools/bazel.rc`](https://github.com/angular/angular/blob/master/tools/bazel.rc) where `--define=ivy=false` is defined as default.
+
+- `--config=debug`: build and launch in debug mode (see [debugging](#debugging) instructions below)
+- `--define=compile=<option>` Controls if ivy or legacy mode is enabled. This is done by generating the [`src/ivy_switch.ts`](https://github.com/angular/angular/blob/master/packages/core/src/ivy_switch.ts) file from [`ivy_switch_legacy.ts`](https://github.com/angular/angular/blob/master/packages/core/src/ivy_switch_legacy.ts) (default), [`ivy_switch_jit.ts`](https://github.com/angular/angular/blob/master/packages/core/src/ivy_switch_jit.ts), or [`ivy_switch_local.ts`](https://github.com/angular/angular/blob/master/packages/core/src/ivy_switch_local.ts).
+    - `legacy`: (default behavior) compile against View Engine, e.g. `--define=compile=legacy`
+    - `jit`: Compile in ivy JIT mode, e.g. `--define=compile=jit`
+    - `local`: Compile in ivy AOT move, e.g. `--define=compile=local`
+- `--test_tag_filters=<tag>`: filter tests down to tags defined in the `tag` config
+of your rules in any given `BUILD.bazel`.
+    - `ivy-jit`: This flag should be set for tests that should be excuted with ivy JIT, e.g. `--test_tag_filters=ivy-jit`. For this, you may have to include `--define=compile=jit`.
+    - `ivy-local`: Only run tests that have to do with ivy AOT. For this, you may have to include `--define=compile=local`, e.g. `--test_tag_filters=ivy-local`..
+    - `ivy-only`: Only run ivy related tests, e.g. `--test_tag_filters=ivy-only`.
+
+
 ### Debugging a Node Test
+<a id="debugging"></a>
 
 - Open chrome at: [chrome://inspect](chrome://inspect)
 - Click on  `Open dedicated DevTools for Node` to launch a debugger.
@@ -82,7 +101,7 @@ First time setup:
 - Go to Debug > Add configuration (in the menu bar) to open `launch.json`
 - Add the following to the `configurations` array:
 
-```
+```json
         {
             "name": "Attach (inspect)",
             "type": "node",
@@ -107,6 +126,7 @@ First time setup:
         },
 ```
 
+**Setting breakpoints directly in your code files may not work in VSCode**. This is because the files you're actually debugging are built files that exist in a `./private/...` folder.
 The easiest way to debug a test for now is to add a `debugger` statement in the code
 and launch the bazel corresponding test (`bazel test <target> --config=debug`).
 
diff --git a/packages/core/src/ivy_switch.ts b/packages/core/src/ivy_switch.ts
index 6a03ff8c7f..41abdbfddc 100644
--- a/packages/core/src/ivy_switch.ts
+++ b/packages/core/src/ivy_switch.ts
@@ -9,27 +9,8 @@
 /**
  * This file is used to control if the default rendering pipeline should be `ViewEngine` or `Ivy`.
  *
- * Reexport from:
- * - `./ivy_switch_false` => Use `ViewEngine`.
- * - `./ivy_switch_true` => Use `Ivy`.
- *
- * This file is here for your IDE as well as for `google3`. The `bazel` build system
- * specifically excludes this file and instead generates a new file which is controlled by
- * command line:
- *
- * - `bazel build packages/core` => Use `ViewEngine`
- * - `bazel build packages/core --define=ivy=true` => Use `Ivy`
- *
- * See: `bazel build packages/core:ivy_switch` for more details.
- *
- * ## How to use this
- *
- * Use this mechanism to have the same symbol be aliased to different implementation.
- * 1) Create two implementations of a symbol (most likely a `function` or a `class`).
- * 2) Export the two implementation under same name in `./ivy_switch_false` and `./ivy_switch_false`
- *    respectively.
- * 3) Import the symbol from `./ivy_switch`. The imported symbol will that point to either the
- *    symbol in `./ivy_switch_false` and `./ivy_switch_false` depending on the compilation mode.
+ * For more information on how to run and debug tests with either Ivy or View Engine (legacy),
+ * please see [BAZEL.md](./docs/BAZEL.md).
  */
 export * from './ivy_switch_legacy';