From d6bbbdda7580d74d78fecae6c99b850bc90414c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Sat, 14 Mar 2020 11:53:20 +0100
Subject: Update CLI for unit_test_runner.ts (#4352)

* drop server guard before unit test result check

To prevent cascading test failures when js_unit_test http server
guard is dropped before asserting that tests were successful.
This is really a band-aid and doesn't solve underlying issue with
http server.

* Update CLI for unit_test_runner.ts

* Change cli/js/tests/unit_test_runner.ts command line interface to work in 3
  modes:
  - "one-off" - run tests that match permissions of currently running
    process
  - "master" - run tests for all possible permission combinations, by
   spawning subprocesses running in "worker" mode and communicating via
   TCP socket; requires elevated permissions
  - "worker" - run tests for set of permissions provided by CLI arg;
  requires elevated permissions to setup TCP connection to "master";
  after initial setup process drops permissions to given set

* Support filtering of tests by string passed after "--" CLI arg

* Update cli/js/tests/README.md
---
 cli/js/tests/README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 52 insertions(+), 5 deletions(-)

(limited to 'cli/js/tests/README.md')

diff --git a/cli/js/tests/README.md b/cli/js/tests/README.md
index 5809224f7..40c3410e1 100644
--- a/cli/js/tests/README.md
+++ b/cli/js/tests/README.md
@@ -37,11 +37,58 @@ ways:
 - sanitization of async ops - ensuring that tests don't leak async ops by
   ensuring that all started async ops are done before test finishes
 
-`unit_test_runner.ts` is main script used to run unit tests.
+## Running tests
+
+`unit_test_runner.ts` is the main script used to run unit tests.
 
 Runner discoveres required permissions combinations by loading
 `cli/js/tests/unit_tests.ts` and going through all registered instances of
-`unitTest`. For each discovered permission combination a new Deno process is
-created with respective `--allow-*` flags which loads
-`cli/js/tests/unit_tests.ts` and executes all `unitTest` that match runtime
-permissions.
+`unitTest`.
+
+There are three ways to run `unit_test_runner.ts`:
+
+- run tests matching current process permissions
+
+```
+// run tests that don't require any permissions
+target/debug/deno unit_test_runner.ts
+
+// run tests with "net" permission
+target/debug/deno --allow-net unit_test_runner.ts
+
+target/debug/deno --allow-net --allow-read unit_test_runner.ts
+```
+
+- run all tests - "master" mode, that spawns worker processes for each
+  discovered permission combination:
+
+```
+target/debug/deno -A unit_test_runner.ts --master
+```
+
+By default all output of worker processes is discarded; for debug purposes
+`--verbose` flag can be provided to preserve output from worker
+
+```
+target/debug/deno -A unit_test_runner.ts --master --verbose
+```
+
+- "worker" mode; communicates with parent using TCP socket on provided address;
+  after initial setup drops permissions to specified set. It shouldn't be used
+  directly, only be "master" process.
+
+```
+target/debug/deno -A unit_test_runner.ts --worker --addr=127.0.0.1:4500 --perms=net,write,run
+```
+
+### Filtering
+
+Runner supports basic test filtering by name:
+
+```
+target/debug/deno unit_test_runner.ts -- netAccept
+
+target/debug/deno -A unit_test_runner.ts --master -- netAccept
+```
+
+Filter string must be specified after "--" argument
-- 
cgit v1.2.3