@zoroaster/fork

@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(forkConfig: string|!ForkConfig, input: string, props?: *, contexts?: !Array<!Context>): ForkResult
  • RunFork
  • ForkResult
• Types
  • ForkConfig
  • Preprocessor
  • ForkPreprocessor
  • Context
• Copyright

API

The package is available by importing its default function:

import fork from '@zoroaster/fork'

async fork(
  forkConfig: string|!ForkConfig,
  input: string,
  props?: *,
  contexts?: !Array<!Context>,
): 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.

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

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)

The ContextTesting/Fork 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.

import('child_process').ForkOptions child_process.ForkOptions: Options to fork a child process, allows to set cwd, environment variables, etc.

import('stream').Writable stream.Writable: The writable stream to pipe the logs of the fork to, e.g., process.stdout.

ForkConfig: Parameters for forking.

Name	Type	Description	Default
module*	string	The path to the module to fork.	-
getArgs	function(this: *, !Array<string>, ...Context): !(Array<string> | Promise<!Array<string>>)	The function to get arguments to pass the fork based on the parsed mask input and contexts. The this context is set to the passed properties.	-
getOptions	function(this: *, ...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.	-
options	!child_process.ForkOptions	Options for the forked processed, such as ENV and cwd.	-
inputs	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<[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
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.	-

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	Preprocessor	How to process stdout before asserts.
stderr	Preprocessor	How to process stderr before asserts.

Context: A context made with a constructor.

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

Copyright

(c) Context Testing 2019