The Code For Zoroaster Mask Testing.

alt="Pipeline Badge">
@zoroaster/mask is The Code For _Zoroaster_ Mask Testing.
``sh`
yarn add -D @zoroaster/mask
- Table Of Contents
- API
- makeTestSuite(path: (string|!Array
- Types
* MaskContext
* MaskConfig
- Testing Forks
* ForkConfig
* Preprocessor
* ForkPreprocessor
- Enabling JSDoc
- Copyright & License
The package is available by importing its default function:
`js`
import makeTestSuite from '@zoroaster/mask'
makeTestSuite(
config: MaskConfig,
): TestSuite - path* (string \| !Array<string>): The path to the mask result file or directory. Can also pass an array of paths.
- config* MaskConfig: Configuration for making test suites.
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:_
| Mask | Mask Result |
|---|---|
` class Context { export default makeTestSuite('example/test/result', { | ` / expected / fails the testhello world / expected / |
`
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.
`
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. |question: answer
| 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 . 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. | - |{ config: true }
| 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 and will be evaluated into an object. | - |/^\/\/ /gm
| splitRe | !RegExp | A regular expression used to detect the beginning of a new test in a mask result file. The default is for results from all files, and /^## /gm for results from .md files. Default /^\/\/ /gm or /^## /gm. | - |/β propName β/
| propStartRe | !RegExp | The regex to detect the start of the property, e.g., in 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 *]. | \/\ββ |/β propName β/ some prop value /ββ/
| propEndRe | !RegExp | The regex which indicates the end of the property, e.g, in it is the default that detects /ββ/. [If copying, replace β with *]. | /\/\β\β\// |expected
| 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 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. | - |assert-throws
| 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 , including fn and args, when testing an error. | - |expected
| mapActual | (result: *) => string | The function to get a value to test against mask property from results returned by getResults. | - |getResults
| assertResults | (actual: , expected: !Object<string, >) => (!Promise \| undefined) | A possibly async function containing any addition assertions on the results. The results from and a map of expected values extracted from the mask's result (where jsonProps are parsed into JS objects) will be passed as arguments. | - |
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. | - |stdin
| inputs | !Array<!Array<(!RegExp \| string)>> | Inputs to push to 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']]. | - |stdin
| stderrInputs | !Array<!Array<(!RegExp \| string)>> | Inputs to push to when stderr writes data (similar to inputs), e.g., [[/question/, 'answer'], [/question2/, 'answer2']]. | - |stdout
| log | (boolean \| { stderr: !(
stream.Writable \| NodeJS.WriteStream), stdout: !(
stream.Writable \| NodeJS.WriteStream) }) | Whether to pipe data from , 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 |stderr
| includeAnswers | boolean | Whether to add the answers to the and stdout output. | true |stdout
| stripAnsi | boolean | Remove ANSI escape sequences from the and stderr prior to checking of the result. | true |\n
| normaliseOutputs | boolean | On Windows, updates all to \r\n, as console.log only prints \n. | false |stderr
| preprocess | (Preprocessor \| and 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. | - |this
| 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 context is set to the passed properties. | - |ENV
| getOptions | (this: Object, ...contexts: Context[]) =>
!child_process.ForkOptions | The function to get options for the fork, such as 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
| stderr | (stdout: string) => string | How to process before asserts, for example, you can strip \r symbols with clearr` package. |
The JSDoc for contexts can be enabled by specifying types for the params to the functions.
!Zoroaster Mask JSDoc Contexts
GNU Affero General Public License v3.0
| Β© Art Decoβ’ for ContextTesting 2020 |
|---|