docs: update readmes

thi-ng · Sep 29, 2021 · 9e07798 · 9e07798
1 parent b7c0abe
commit 9e07798
Show file tree

Hide file tree

Showing 8 changed files with 197 additions and 15 deletions.
diff --git a/packages/defmulti/README.md b/packages/defmulti/README.md
@@ -62,7 +62,7 @@ node --experimental-specifier-resolution=node --experimental-repl-await
 > const defmulti = await import("@thi.ng/defmulti");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 801 bytes
+Package sizes (gzipped, pre-treeshake): ESM: 861 bytes
 
 ## Dependencies
 
@@ -107,6 +107,8 @@ function, but also exposes the following operations:
 
 - `.add(id, fn)` - adds/overrides implementation for given dispatch
   value
+- `.addAll(impls)` - add/override multiple implementations (given as object,
+  with keys referring to dispatch values)
 - `.remove(id)` - removes implementation for dispatch value
 - `.callable(...args)` - takes same args as if calling the
   multi-function, but only checks if an implementation exists for the
@@ -138,7 +140,7 @@ causes issues to people, parents could be implemented as sorted list
 impact... please open an issue if you run into problems!
 
 ```ts
-const foo = defmulti((x )=> x);
+const foo = defmulti((x) => x);
 foo.isa(23, "odd");
 foo.isa(42, "even");
 foo.isa("odd", "number");
@@ -169,10 +171,10 @@ Same example, but with relationships provided as argument to `defmulti`:
 
 ```ts
 const foo = defmulti((x) => x, {
-    23: ["odd"],
-    42: ["even"],
-    "odd": ["number"],
-    "even": ["number"],
+    23: "odd",
+    42: "even",
+    "odd": "number",
+    "even": "number",
 });
 
 foo.rels();

diff --git a/packages/defmulti/tpl.readme.md b/packages/defmulti/tpl.readme.md
@@ -61,6 +61,8 @@ function, but also exposes the following operations:
 
 - `.add(id, fn)` - adds/overrides implementation for given dispatch
   value
+- `.addAll(impls)` - add/override multiple implementations (given as object,
+  with keys referring to dispatch values)
 - `.remove(id)` - removes implementation for dispatch value
 - `.callable(...args)` - takes same args as if calling the
   multi-function, but only checks if an implementation exists for the
@@ -92,7 +94,7 @@ causes issues to people, parents could be implemented as sorted list
 impact... please open an issue if you run into problems!
 
 ```ts
-const foo = defmulti((x )=> x);
+const foo = defmulti((x) => x);
 foo.isa(23, "odd");
 foo.isa(42, "even");
 foo.isa("odd", "number");
@@ -123,10 +125,10 @@ Same example, but with relationships provided as argument to `defmulti`:
 
 ```ts
 const foo = defmulti((x) => x, {
-    23: ["odd"],
-    42: ["even"],
-    "odd": ["number"],
-    "even": ["number"],
+    23: "odd",
+    42: "even",
+    "odd": "number",
+    "even": "number",
 });
 
 foo.rels();

diff --git a/packages/distance/README.md b/packages/distance/README.md
@@ -123,6 +123,7 @@ Package sizes (gzipped, pre-treeshake): ESM: 1.06 KB
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/heaps](https://github.com/thi-ng/umbrella/tree/develop/packages/heaps)
 - [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)

diff --git a/packages/dsp/package.json b/packages/dsp/package.json
@@ -122,6 +122,9 @@
         "./biquad": {
             "import": "./biquad.js"
         },
+        "./bounce": {
+            "import": "./bounce.js"
+        },
         "./complex": {
             "import": "./complex.js"
         },

diff --git a/packages/geom/README.md b/packages/geom/README.md
@@ -83,7 +83,7 @@ node --experimental-specifier-resolution=node --experimental-repl-await
 > const geom = await import("@thi.ng/geom");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 10.29 KB
+Package sizes (gzipped, pre-treeshake): ESM: 10.58 KB
 
 ## Dependencies
 

diff --git a/packages/pixel/README.md b/packages/pixel/README.md
@@ -301,6 +301,7 @@ console.log(clusters);
 
 ### Support packages
 
+- [@thi.ng/pixel-dither](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel-dither) - TODO
 - [@thi.ng/pixel-io-netpbm](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel-io-netpbm) - Multi-format NetPBM reader & writer support for [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel)
 
 ### Related packages
@@ -339,6 +340,7 @@ Package sizes (gzipped, pre-treeshake): ESM: 9.22 KB
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/binary](https://github.com/thi-ng/umbrella/tree/develop/packages/binary)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
+- [@thi.ng/distance](https://github.com/thi-ng/umbrella/tree/develop/packages/distance)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/k-means](https://github.com/thi-ng/umbrella/tree/develop/packages/k-means)
 - [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)

diff --git a/packages/testament/README.md b/packages/testament/README.md
@@ -13,13 +13,15 @@ This project is part of the
   - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [CLI](#cli)
+  - [Result exports](#result-exports)
 - [API](#api)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Minimal, rational & TypeScript-friendly test runner.
+Minimal, rational & TypeScript-friendly test runner, result export as CSV/JSON, watch mode.
 
 ### Status
 
@@ -56,11 +58,96 @@ Package sizes (gzipped, pre-treeshake): ESM: 1.15 KB
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 - [chokidar](https://github.com/thi-ng/umbrella/tree/develop/packages/undefined)
 
+## CLI
+
+The library includes a CLI runner to execute tests in various files once, or
+watch them for changes and then re-execute any changed files. Options and file
+paths can be given in any order.
+
+```bash
+testament --help
+
+# Usage: testament [opts] path1 [path2...]
+#
+# Options:
+# --all, -a        Run all tests (don't stop at 1st failure)
+# --csv            Export results as CSV
+# --json           Export results as JSON
+# -o               Output file path for exported results
+# --timeout, -t    Set default timeout value (milliseconds)
+# --watch, -w      Watch given files/dirs for changes
+#
+# --help, -h       Print this help and quit
+```
+
+**Note:** The CLI tool respects the [`NO_COLOR`](https://no-color.org/) convention.
+
+### Result exports
+
+Test results can be exported in CSV or JSON formats. To include failed tests, make sure you include the `--all`/`-a` CLI flag. If no output file (`-o`) is given, the results will be written to stdout
+
+```bash
+testament --all --csv -o results.csv test
+
+testament --all --json -o results.json test
+```
+
+The following details are recorded per test case:
+
+- **group**: Parent group ID/title
+- **title**: Test title/descriptor
+- **time**: Time taken (incl. retries) in milliseconds (rounded)
+- **trials**: Number of trials taken
+- **error**: Error message, failure reason
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/testament/)
 
-TODO
+Groups of test cases can be specified via `group()`. The tests are NOT executed
+immediately until `execute()` is being called (done automatically when using the
+CLI wrapper). All tests within the group will share the (optionally) provided
+configuration options (which themselves will be stubbed using `GLOBAL_OPTS`).
+
+If a test is async, use the passed `TestCtx` handlers (esp. `done()` and
+`setTimeout()`) to ensure timeouts and any errors or test failures are handled
+properly.
+
+If a test case function makes use of the provided `TestCtx` arg in any way, it
+**MUST** call `done()`, since _testament_ assumes it is an async case.
+
+Any uncaught errors thrown in the group's lifecycle handlers will not be caught
+by the group wrapper either (In fact, they will be caught, but then
+re-thrown...). Furthermore, if the `exit` option is true (default), any uncaught
+error will cause the entire process to terminate (unless running a browser).
+
+See docs for full options
+
+```ts
+import { group, execute } from "@thi.ng/testament";
+import { assert } from "@thi.ng/errors";
+
+// register group of test cases
+group(
+  "basics",
+  {
+    add: () => { assert(1 + 1 === 2); },
+    sub: ({ done, setTimeout }) => {
+      setTimeout(() => { assert(3 - 1 === 1); done(); }, 50);
+    }
+  },
+  // shared options for all cases in the group
+  {
+    maxTries: 3,
+    timeOut: 100,
+    beforeEach: ({ logger }) => logger.info("before"),
+    afterEach: ({ logger }) => logger.info("after"),
+  }
+);
+
+// only needed if NOT using the CLI runner
+const results = await execute();
+```
 
 ## Authors
 

diff --git a/packages/testament/tpl.readme.md b/packages/testament/tpl.readme.md
@@ -33,11 +33,96 @@ ${pkg.deps}
 
 ${examples}
 
+## CLI
+
+The library includes a CLI runner to execute tests in various files once, or
+watch them for changes and then re-execute any changed files. Options and file
+paths can be given in any order.
+
+```bash
+testament --help
+
+# Usage: testament [opts] path1 [path2...]
+#
+# Options:
+# --all, -a        Run all tests (don't stop at 1st failure)
+# --csv            Export results as CSV
+# --json           Export results as JSON
+# -o               Output file path for exported results
+# --timeout, -t    Set default timeout value (milliseconds)
+# --watch, -w      Watch given files/dirs for changes
+#
+# --help, -h       Print this help and quit
+```
+
+**Note:** The CLI tool respects the [`NO_COLOR`](https://no-color.org/) convention.
+
+### Result exports
+
+Test results can be exported in CSV or JSON formats. To include failed tests, make sure you include the `--all`/`-a` CLI flag. If no output file (`-o`) is given, the results will be written to stdout
+
+```bash
+testament --all --csv -o results.csv test
+
+testament --all --json -o results.json test
+```
+
+The following details are recorded per test case:
+
+- **group**: Parent group ID/title
+- **title**: Test title/descriptor
+- **time**: Time taken (incl. retries) in milliseconds (rounded)
+- **trials**: Number of trials taken
+- **error**: Error message, failure reason
+
 ## API
 
 ${docLink}
 
-TODO
+Groups of test cases can be specified via `group()`. The tests are NOT executed
+immediately until `execute()` is being called (done automatically when using the
+CLI wrapper). All tests within the group will share the (optionally) provided
+configuration options (which themselves will be stubbed using `GLOBAL_OPTS`).
+
+If a test is async, use the passed `TestCtx` handlers (esp. `done()` and
+`setTimeout()`) to ensure timeouts and any errors or test failures are handled
+properly.
+
+If a test case function makes use of the provided `TestCtx` arg in any way, it
+**MUST** call `done()`, since _testament_ assumes it is an async case.
+
+Any uncaught errors thrown in the group's lifecycle handlers will not be caught
+by the group wrapper either (In fact, they will be caught, but then
+re-thrown...). Furthermore, if the `exit` option is true (default), any uncaught
+error will cause the entire process to terminate (unless running a browser).
+
+See docs for full options
+
+```ts
+import { group, execute } from "@thi.ng/testament";
+import { assert } from "@thi.ng/errors";
+
+// register group of test cases
+group(
+  "basics",
+  {
+    add: () => { assert(1 + 1 === 2); },
+    sub: ({ done, setTimeout }) => {
+      setTimeout(() => { assert(3 - 1 === 1); done(); }, 50);
+    }
+  },
+  // shared options for all cases in the group
+  {
+    maxTries: 3,
+    timeOut: 100,
+    beforeEach: ({ logger }) => logger.info("before"),
+    afterEach: ({ logger }) => logger.info("after"),
+  }
+);
+
+// only needed if NOT using the CLI runner
+const results = await execute();
+```
 
 ## Authors