@zoroaster/fork NPM

@zoroaster/fork

@zoroaster/fork is used in Zoroaster to test forks. It is part of the @zoroaster/mask package which uses it to compare forks' output against the results written in non-js files. Nevertheless, the package can be used on its own to spawn and test forks — the library allows to fork a process and then asserts on the stderr, stdout and code properties, if they are passed, and returns the actual values if the assertions passed.

yarn add @zoroaster/fork

API

The package is available by importing its default function:

import fork from '@zoroaster/fork'

async fork( `options: !RunFork,`): !ForkResult

This method will fork a process, and pass the inputs when stdin expects an input. Because includeAnswers is set to true by default, the answers will be included in the resulting stdout and stderr properties. Returns the result of the work, updated to contain answers in the interactive mode.

options* !RunFork: Options for the run method.

RunFork: Options for the run method.

Name	Type	Description
forkConfig*	(string \| !ForkConfig)	Either the config, or the path to the module to fork.
input*	string	The input to the test from the mask's result. It will be converted into an array of strings to become arguments to pass to the fork.
props	*	The properties to pass to the `getArgs` and `getOptions` as their this context. These properties will be got from the mask's result.
contexts	!Array<Context>	The contexts for the test to be passed to `getArgs` and `getOptions`.

ForkResult: The output of the fork method.

Name	Type	Description
stdout*	string	The output from the `stdout` stream, possibly with answers fed to `stdin`.
stderr*	string	The output from the `stderr` stream, possibly with answers fed to `stdin`.
code*	number	The code with which the process exited.

For example, to test the fork with the next code:

const [,, ...args] = process.argv
console.log(args)
console.error(process.env.EXAMPLE)
process.exit(5)

@ContextTesting/Fork package can be used:

/* yarn example/ */
import fork from '@zoroaster/fork'

(async () => {
  /** @suppress {checkTypes} */
  const res = await fork({
    contexts: ['CONTEXT'],
    forkConfig: {
      module: 'example/fork',
      getArgs(inputs) {
        return [...inputs, this.prop1]
      },
      getOptions(CONTEXT) {
        return {
          env: {
            'EXAMPLE': `${CONTEXT} - ${this.input}`,
          },
        }
      },
      preprocess(s) {
        /* e.g., to remove whitespace at the end of each line
          s.split('\n').map(a => a.trimRight()).join('\n')
        */
        return `pre-${s}`
      },
      /* stripAnsi: true */
    },
    input: 'hello world',
    props: {
      prop1: '999',
      'stdout': `pre-[ 'hello', 'world', '999' ]`,
      'stderr': 'pre-CONTEXT - hello world',
    },
  })
  console.log(res)
})()

{
  code: 5,
  stdout: "[ 'hello', 'world', '999' ]\n",
  stderr: 'CONTEXT - hello world\n'
}

Types

The following types are used in this software.

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 \| 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.