@zoroaster/mask is The Code For _Zoroaster_ Mask Testing.

``sh
yarn add -D @zoroaster/mask
`

Table Of Contents

- Table Of Contents
- API
- makeTestSuite(path: (string|!Array), config: MaskConfig): TestSuite
- Types
* MaskContext
* MaskConfig
- Testing Forks
* ForkConfig
* Preprocessor
* ForkPreprocessor
- Enabling JSDoc
- Copyright & License





API

The package is available by importing its default function:

`js
import makeTestSuite from '@zoroaster/mask'
`





makeTestSuite(
  path: (string|!Array),
  config: MaskConfig,
): TestSuite

The exported test suite will be run with _Zoroaster_ Context-Testing Framework. The simplest form of a mask is to use the getResults property, which acts as a template for test cases, which will receive the inputs (e.g., input) from the mask result as properties of the this context, and the contexts via the arguments. The output will be compared to the expected property of the mask.

_For example, given the following function:_

`js
import read from '@wrote/read'

/**
* An example function that reads a file.
* @param {string} path The path to the file to read.
* @param {string} input The string to prepend.
*/
const fn = async (path, input) => {
const res = await read(path)
return ${input}: ${res}
}

export default fn
`

_Zoroaster can test it using a mask:_


`
example/test/mask/default.js
✓ runs the test
not hello world: this is a test
✗ fails the test
| Error: 'hello world: this is a test' == 'not hello world: this is a test'
| at fails the test (example/test/result/default.md:8:1)

example/test/mask/default.js > fails the test
Error: 'hello world: this is a test' == 'not hello world: this is a test'
at fails the test (example/test/result/default.md:8:1)

🦅 Executed 2 tests: 1 error.
`





Types

The following types are used to define the configuration of the mask.

__MaskContext__: The this context of mask methods which contains the mask's properties extracted from the result file.


| Name | Type | Description |
| ---------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| __input__ | | The input to the mask, normally as string, but parsed into an object if jsonProps contains the 'input' value. |
| preamble | string | The text at the top of the mask result file if present. |
| inputs | string | The synchronous inputs for the fork, each on a new line in form of question: answer. This is not hard-coded, it's just a convention for naming the inputs to forks field. |


__MaskConfig__: Configuration for making test suites.


| Name | Type | Description | Default |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| context | (function(new: Context) \| !Array<function(new: Context)> \| *) | The single or multiple context constructors or objects to initialise for each test. | - |
| persistentContext | (function(new: Context) \| !Array<function(new: Context)> \| *) | The context constructor(s) that will be initialised and destroyed once per test suite, having a persistent state across tests. | - |
| fork | (string \| !ForkConfig) | The path to the module to fork with the mask's input split by whitespace as arguments, output of which will be compared against the code, stdout and stderr properties of the mask. Arguments with whitespace should be wrapped in speech marks, i.e. ' or ". Additionally, ForkConfig with module, getArgs, options and getOptions properties can be passed for more control of how the fork will be started. | - |
| jsonProps | !Array<string> | The properties of the mask to parse as _JSON_ values. | - |
| jsProps | !Array<string> | The properties of the mask to parse into JavaScript objects. For example, a property can be written as { config: true } and will be evaluated into an object. | - |
| splitRe | !RegExp | A regular expression used to detect the beginning of a new test in a mask result file. The default is /^\/\/ /gm for results from all files, and /^## /gm for results from .md files. Default /^\/\/ /gm or /^## /gm. | - |
| propStartRe | !RegExp | The regex to detect the start of the property, e.g., in /⁎ propName ⁎/ it is the default regex that detects /⁎. There's no option to define the end of the regex after the name. [If copying, replace ⁎ with *]. | \/\‎⁎ |
| propEndRe | !RegExp | The regex which indicates the end of the property, e.g, in /⁎ propName ⁎/ some prop value /⁎⁎/ it is the default that detects /⁎⁎/. [If copying, replace ⁎ with *]. | /\/\⁎\⁎\// |
| getResults | (this: context of mask methods which contains the mask's properties extracted from the result file.">MaskContext, ...args: Context[]) => (* \| !Promise) | A possibly async function which returns results of a test. If it outputs a string, it will be compared against the expected property of the mask using string comparison. If it outputs an object, its deep equality with expected can be tested by adding 'expected' to the jsonProps. Otherwise, the result must be mapped for comparison with expected using the mapActual method. | - |
| getTransform | (this: context of mask methods which contains the mask's properties extracted from the result file.">MaskContext, ...args: Context[]) => !( method implementation.">stream.Transform \| Promise< method implementation.">!stream.Transform>) | A possibly async function which returns a _Transform_ stream to be ended with the input specified in the mask's result. Its output will be accumulated and compared against the expected output of the mask. | - |
| getReadable | (this: context of mask methods which contains the mask's properties extracted from the result file.">MaskContext, ...args: Context[]) => !(stream.Readable \| Promise<!stream.Readable>) | A possibly async function which returns a _Readable_ stream constructed with the input from the mask. Its output will be stored in memory and compared against the expected output of the mask. | - |
| getThrowsConfig | (this: context of mask methods which contains the mask's properties extracted from the result file.">MaskContext, ...args: Context[]) => _assertThrows.Config | A function which should return a configuration for assert-throws, including fn and args, when testing an error. | - |
| mapActual | (result: *) => string | The function to get a value to test against expected mask property from results returned by getResults. | - |
| assertResults | (actual: , expected: !Object<string, >) => (!Promise \| undefined) | A possibly async function containing any addition assertions on the results. The results from getResults and a map of expected values extracted from the mask's result (where jsonProps are parsed into JS objects) will be passed as arguments. | - |





Testing Forks

With masks, it is very easy to test fork processes.

__ForkConfig__: Parameters for forking.


| Name | Type | Description | Default |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| __module*__ | string | The path to the module to fork. | - |
| options | !child_process.ForkOptions | Options for the forked processed, such as ENV and cwd. | - |
| inputs | !Array<!Array<(!RegExp \| string)>> | Inputs to push to stdin when stdout writes data. The inputs are kept on stack, and taken off the stack when the RegExp matches the written data, e.g., [[/question/, 'answer'], [/question2/, 'answer2']]. | - |
| stderrInputs | !Array<!Array<(!RegExp \| string)>> | Inputs to push to stdin when stderr writes data (similar to inputs), e.g., [[/question/, 'answer'], [/question2/, 'answer2']]. | - |
| log | (boolean \| { stderr: !(stream.Writable \| NodeJS.WriteStream), stdout: !(stream.Writable \| NodeJS.WriteStream) }) | Whether to pipe data from stdout, stderr to the process's streams. If an object is passed, the output will be piped to streams specified as its stdout and stderr properties. | false |
| includeAnswers | boolean | Whether to add the answers to the stderr and stdout output. | true |
| stripAnsi | boolean | Remove ANSI escape sequences from the stdout and stderr prior to checking of the result. | true |
| normaliseOutputs | boolean | On Windows, updates all \n to \r\n, as console.log only prints \n. | false |
| preprocess | (Preprocessor \| and stderr preprocessors.">ForkPreprocessor) | The function to run on stdout and stderr before comparing it to the output. Pass an object with stdout and stderr properties for individual pre-processors. | - |
| getArgs | (this: Object, forkArgs: !Array<string>, ...contexts: Context[]) => !(Array<string> \| Promise<!Array<string>>) | The function to extend arguments to pass the fork based on the parsed mask input and contexts. The this context is set to the passed properties. | - |
| getOptions | (this: Object, ...contexts: Context[]) => !child_process.ForkOptions | The function to get options for the fork, such as ENV and cwd, based on contexts. The this context is set to the passed properties. | - |


function(string): string __Preprocessor__: The function which processes fork's outputs before returning them for asserts.


__ForkPreprocessor__: An object with stdout and stderr preprocessors.


| Name | Type | Description |
| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| stdout | (stdout: string) => string | How to process stdout before asserts. |
| stderr | (stdout: string) => string | How to process stderr before asserts, for example, you can strip \r symbols with clearr` package. |

Enabling JSDoc

The JSDoc for contexts can be enabled by specifying types for the params to the functions.

!Zoroaster Mask JSDoc Contexts

Copyright & License

GNU Affero General Public License v3.0

alt="Art Deco">	© Art Deco™ for ContextTesting 2020