@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

Table Of Contents

• Table Of Contents
• API
• async fork(options): !ForkResult
  • RunFork
  • ForkResult
• Types
  • ForkConfig
  • Preprocessor
  • ForkPreprocessor
  • Context
• Copyright & License

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.

Context: A context made with a constructor.

Name	Type	Description
_init	() => (!Promise | void)	The function to initialise the context.
_destroy	() => (!Promise | void)	The function to destroy the context.

Copyright & License

GNU Affero General Public License v3.0

	© Art Deco™ for ContextTesting 2020