Add new cli testing suite information to READMEs

Author: t-ski

README.md

@@ -27,12 +27,16 @@ new UnitTest("Throws error for division by zero")
 
 **🔩   [Unit](./packages/@unit/README.md)**   `unit`
 
-> Test arbitrary units of code based on deep expectation comparisons.
+> Test arbitrary units of code based on deep expected value comparisons.
 
 **🔩   [HTTP](./packages/@http/README.md)**   `http`
 
 > Test HTTP(S) endpoints based on expectation filtered responses.
 
+**🔩   [CLI](./packages/@cli/README.md)**   `cli`
+
+> Test command line interfaces based on expected stdout or stderr.
+
 ##
 
 <sub>© Thassilo Martin Schiepanski</sub>

package-lock.json

@@ -1,6 +1,6 @@
 # [rJS Testing](https://github.com/rapidjs-org/testing) CLITest `cli`
 
-rJS Testing CLI testing suite (`CLITest`): Test command line interfaces based on stdout and -err.
+rJS Testing CLI testing suite (`CLITest`): Test command line interfaces based on expected stdout or stderr.
 
 ``` cli
 npm i -D @rapidjs.org/testing-cli
@@ -30,40 +30,45 @@ HTTPTest.configure(configuration: RequestOptions & {
 
 ``` ts
 .actual(binary: string, arg?: string[])
-.actual(args: string[]) // imply binary if defined a common
+.actual(args: string[]) // Imply binary if defined a common
 ```
 
 #### Expected
 
 ``` ts
-.expected(binary: string, arg?: string[])
-.expected(args: string[]) // imply binary if defined a common
+.expected(feedback: {
+  stdout?: string|string[];         // Either text as is, or array of lines
+  stderr?: string|string[];
+})
+.expected(stdout: string|string[])  // Only check stdout
 ```
 
+> The execution output to be compared is whitespace normalised, i.e. any non-break whitespace character is condensed to a single space.
+
 ### Value-based Assertion
 
 ``` ts
-new CLITest("List files")
-.actual(<expression>)
-.expected(<expression>);
+new CLITest("Print working directory")
+.actual("pwd")
+.expected("/Users/rjs/app");
 ```
 
 ## Comparison Strategy
 
-...
+Before a comparison of a binary execution output, it is whitespace normalised. This is, any non-break whitespace character is condensed to a single space.
 
 **✅ &thinsp; SUCCESS**
 
 ``` js
-.actual(<expression>)
-.expected(<expression>)
+.actual("ls", [ "-L" ])
+.expected("img1.png img2.png")
 ```
 
 **❌ &thinsp; FAILURE**
 
 ``` js
-.actual(<expression>)
-.expected(<expression>)
+.actual("ls", [ "-L" ])
+.expected("img1.png    img2.png")
 ```
 
 ##

packages/@cli/README.md

@@ -34,4 +34,4 @@
     "dependencies": {
         "@rapidjs.org/testing": "0.x"
     }
-}
+}

packages/@cli/package.json

@@ -28,71 +28,72 @@ export class CLITest extends Test<IOutput> {
 
 	private normalizeOutput(output: Partial<IOutput>): IOutput {
 		const normalizeStdValue = (value: string) => {
-			return (value ?? "")
-			.replace(/(\n|\r)+/g, "\n")
-			.replace(/(\t| )+/g, " ")
-			.trim()
-			?? null;
-		}
+			return (
+				(value ?? "")
+					.replace(/(\n|\r)+/g, "\n")
+					.replace(/(\t| )+/g, " ")
+					.trim() ?? null
+			);
+		};
 		return {
 			stdout: normalizeStdValue(output.stdout),
 			stderr: normalizeStdValue(output.stderr)
 		};
 	}
-	
+
 	protected evalActualExpression(args: string[]): Promise<IOutput>;
 	protected evalActualExpression(binary: string, args?: string[]): Promise<IOutput>;
-	protected evalActualExpression(binaryOrArgs: string|string[], args: string[] = []): Promise<IOutput> {
-		// TODO: Pipe chain abstraction (?)
-		const effectiveBinary: string = (!binaryOrArgs || Array.isArray(binaryOrArgs))
-		? CLITest.configuration.commonBinary
-		: binaryOrArgs;
-		if(!effectiveBinary) throw new SyntaxError("Missing binary to execute");
+	protected evalActualExpression(binaryOrArgs: string | string[], args: string[] = []): Promise<IOutput> {
+		// TODO: Unix pipes abstraction (?)
+		// TODO: Possibility top check underlying effect (and chain with other test suite) (?)
+
+		const effectiveBinary: string =
+			!binaryOrArgs || Array.isArray(binaryOrArgs) ? CLITest.configuration.commonBinary : binaryOrArgs;
+		if (!effectiveBinary) throw new SyntaxError("Missing binary to execute");
 
-		const effectiveArgs: string[] = (args ?? [ binaryOrArgs ].flat()) ?? [];
+		const effectiveArgs: string[] = args ?? [binaryOrArgs].flat() ?? [];
 
 		return new Promise((resolve, reject) => {
-			exec([ effectiveBinary, effectiveArgs ].flat().join(" "), (err: Error, stdout: string, stderr: string) => {
-				if(err && !stderr) {
+			exec([effectiveBinary, effectiveArgs].flat().join(" "), (err: Error, stdout: string, stderr: string) => {
+				if (err && !stderr) {
 					reject(err);
 
 					return;
 				}
-				
-				resolve(this.normalizeOutput({
-					stdout, stderr
-				}));
+
+				resolve(
+					this.normalizeOutput({
+						stdout,
+						stderr
+					})
+				);
 			});
 		});
 	}
 
-	protected evalExpectedExpression(expectedOutput: Partial<IOutput>|string): IOutput {
+	protected evalExpectedExpression(expectedOutput: Partial<IOutput> | string): IOutput {
 		return this.normalizeOutput(
-			(typeof(expectedOutput) === "string")
-			? {	
-				stdout: expectedOutput
-			}
-			: {
-				stdout: [ expectedOutput.stdout ].flat().join("\n"),
-				stderr: [ expectedOutput.stderr ].flat().join("\n")
-			}
+			typeof expectedOutput === "string"
+				? {
+						stdout: expectedOutput
+					}
+				: {
+						stdout: [expectedOutput.stdout].flat().join("\n"),
+						stderr: [expectedOutput.stderr].flat().join("\n")
+					}
 		);
 	}
 
 	protected getDifference(actual: IOutput, expected: IOutput) {
 		const filterObj = (sourceObj: IOutput, targetObj: IOutput) => {
 			return {
-				...(sourceObj.stdout !== targetObj.stdout)
-				? { stdout: sourceObj.stdout }
-				: {},
-				...(sourceObj.stderr !== targetObj.stderr)
-				? { stderr: sourceObj.stderr }
-				: {},
-			}
+				...(sourceObj.stdout !== targetObj.stdout ? { stdout: sourceObj.stdout } : {}),
+				...(sourceObj.stderr !== targetObj.stderr ? { stderr: sourceObj.stderr } : {})
+			};
 		};
 		return {
 			actual: filterObj(actual, expected),
 			expected: filterObj(expected, actual)
-		}
+		};
 	}
 }

packages/@cli/src/CLITest.ts

@@ -31,6 +31,7 @@ new UnitTest("Throws error for division by zero")
 | :- | :- | :- |
 | `unit`   `@rapidjs.org/testing-unit` | `UnitTest` | Unit testing ([Read Documentation](../@unit/README.md)) |
 | `http`   `@rapidjs.org/testing-http` | `HTTPTest` | HTTP(S) testing ([Read Documentation](../@http/README.md)) |
+| `cli`   `@rapidjs.org/testing-cli` | `CLITest` | CLI testing ([Read Documentation](../@cli/README.md)) |
 
 ## Test Cases
 

packages/testing/README.md

@@ -1,6 +1,6 @@
 {
     "name": "@rapidjs.org/testing",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Context-sensitive, (a)sync-uniform testing framework for JavaScript and TypeScript.",
     "author": "Thassilo Martin Schiepanski",
     "homepage": "https://github.com/rapidjs-org/testing#readme",