From 6299cefa0365e84822a53425b1a9af1e5d70917a Mon Sep 17 00:00:00 2001
From: Kenneth Pouncey <kjpou@pt.lu>
Date: Fri, 8 Jan 2021 10:49:38 +0100
Subject: [PATCH] [browser][docs] Add docs for running outerloop and browser
 instance (#46737)

* [browser][docs] Add testing docs for running outerloop and browser instance

* Add information for GitHub interface.
---
 docs/workflow/testing/libraries/testing-wasm.md | 60 ++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/docs/workflow/testing/libraries/testing-wasm.md b/docs/workflow/testing/libraries/testing-wasm.md
index 7e53085..22c2676 100644
--- a/docs/workflow/testing/libraries/testing-wasm.md
+++ b/docs/workflow/testing/libraries/testing-wasm.md
@@ -1,5 +1,9 @@
 # Testing Libraries on WebAssembly
 
+## Prerequisites
+
+### Using JavaScript engines
+
 In order to be able to run tests, the following JavaScript engines should be installed:
 - V8
 - JavaScriptCore
@@ -21,6 +25,16 @@ e.g. for V8
 PATH=/Users/<your_user>/.jsvu/:$PATH V8
 ```
 
+### Using Browser Instance
+It's possible to run tests in a browser instance:
+
+- An installation of [ChromeDriver - WebDriver for Chrome](https://chromedriver.chromium.org) is required.  Make sure to read [Downloads/Version Selection](https://chromedriver.chromium.org/downloads/version-selection) to setup a working installation of ChromeDriver.
+- Include the [ChromeDriver - WebDriver for Chrome](https://chromedriver.chromium.org) location in your PATH environment.  Default is `/Users/<your_user>/.chromedriver`
+
+```bash
+PATH=/Users/<your_user>/.chromedriver:$PATH
+```
+
 ## Building Libs and Tests for WebAssembly
 
 Now we're ready to build everything for WebAssembly (for more details, please read [this document](../../building/libraries/webassembly-instructions.md#building-everything)):
@@ -32,12 +46,19 @@ and even run tests one by one for each library:
 ./build.sh libs.tests -test -os Browser -c Release
 ```
 
-### Running individual test suites
+### Running individual test suites using JavaScript engine
 The following shows how to run tests for a specific library
 ```
 ./dotnet.sh build /t:Test src/libraries/System.AppContext/tests /p:TargetOS=Browser /p:TargetArchitecture=wasm /p:Configuration=Release
 ```
 
+### Running outer loop tests using JavaScript engine
+
+To run all tests, including "outer loop" tests (which are typically slower and in some test suites less reliable, but which are more comprehensive):
+```
+./dotnet.sh build /t:Test src/libraries/System.AppContext/tests /p:TargetOS=Browser /p:TargetArchitecture=wasm /p:Configuration=Release /p:Outerloop=true
+```
+
 ### Running tests using different JavaScript engines
 It's possible to set a JavaScript engine explicitly by adding `/p:JSEngine` property:
 
@@ -52,6 +73,43 @@ At the moment supported values are:
 
 By default, `V8` engine is used.
 
+### Running individual test suites using Browser instance
+
+The following shows how to run tests for a specific library
+
+- CLI
+    ```
+    XHARNESS_COMMAND=test-browser ./dotnet.sh build /t:Test src/libraries/System.AppContext/tests /p:TargetOS=Browser /p:TargetArchitecture=wasm /p:Configuration=Release
+    ```
+- Makefile target `run-browser-tests-<test>`
+    ```
+    make -C src/mono/wasm/ run-browser-tests-System.AppContext
+    ```
+
+### Running outer loop tests using Browser instance
+
+To run all tests, including "outer loop" tests (which are typically slower and in some test suites less reliable, but which are more comprehensive):
+
+- CLI
+    ```
+    XHARNESS_COMMAND=test-browser ./dotnet.sh build /t:Test src/libraries/System.AppContext/tests /p:TargetOS=Browser /p:TargetArchitecture=wasm /p:Configuration=Release /p:Outerloop=true
+    ```
+
+- Makefile target `run-browser-tests-<test>`
+
+    ```
+    MSBUILD_ARGS=/p:OuterLoop=true make -C src/mono/wasm/ run-browser-tests-System.AppContext
+    ```
+
+
+## Kicking off outer loop tests from GitHub Interface
+
+Add the following to the comment of a PR.
+
+```
+/azp run runtime-libraries-mono outerloop
+```
+
 ### Test App Design
 TBD
 
-- 
2.7.4