@zoroaster/fork

1.5.0 • Public • Published

@zoroaster/fork

npm version Build status

@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

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 Node.JS Docs!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: !(Node.JS Docsstream.Writable | NodeJS.WriteStream), stdout: !(Node.JS Docsstream.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[]) => Node.JS Docs!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 © Art Deco™ for ContextTesting 2020 ContextTesting

Package Sidebar

Install

npm i @zoroaster/fork

Weekly Downloads

4

Version

1.5.0

License

AGPL-3.0

Unpacked Size

54.1 kB

Total Files

23

Last publish

Collaborators

  • zvr