kapok-js
Javascript Testing utilities for CLI
Table of Contents
- Installation
- Usage
- API
- Kapok.config
- Kapok.start(command[, args][, options])
- Kapok.size
- Kapok.killAll()
- Kapok#constructor(command[, args][, options])
- Kapok#assert(condition[, options])
- Kapok#joinUntil(condition[, options])
- Kapok#until(condition[, options])
- Kapok#assertUntil(condition[, options])
- Kapok#ignoreUntil(condition[, options])
- Kapok#done([callback])
- Kapok#doneAndKill([callback])
- Kapok#kill([signal, callback])
- Event: 'data'
- Event: 'out:data'
- Event: 'err:data'
- Event: 'line'
- Event: 'out:line'
- Event: 'err:line'
- Event: 'error'
- Event: 'exit'
- Event: 'signal:exit'
- License
Installation
yarn add -D kapok-js
Usage
; const kapok = 'echo' 'hello\nworld';kapok;
Advanced Usage
;; const code = ` console.log('🌺'); console.log('* * *'); console.log('start'); console.log(JSON.stringify({ hello: 'world' }, null, 2)); console.log('end');`; /*🌺* * *start{ "hello": "world"}end*/ const kapok = 'node' '-e' code; /* just like childProcess.spawn() */kapok /* ignore lines until the line matches "*" */ /* join multi lines until the line is equal to '}', and then join the lines into a string */ ;
API
Kapok.config
config.shouldShowLog
<Boolean>: Show log message or not. Defaults totrue
config.shouldThrowError
<Boolean>: Throw a new Error or not when assert fails. Defaults tofalse
A global config to all Kapok
instances. Can be override.
Kapok.start(command[, args][, options])
command
<String>: The command to runargs
<Array>: List of string argumentsoptions
<Object>: Just like spawn options- Returns <Kapok>
Spawns a new process using the given command
, just like child_process.spawn()
, but returns a Kapok
instance.
Kapok
inherits EventEmitter
Kapok.size
- Returns <Number>
Get existing kapok instances size
Kapok.killAll()
- Return <Promise>
Kill all existing kapok instances
Kapok#constructor(command[, args][, options])
The same with Kapok.start()
Kapok#assert(condition[, options])
condition
<String|RegExp|Function>: Testingmessage
, throw an error if returnsfalse
. Themessage
is the each line data of process outputs- If is a
String
, it will returnmessage === condition
- If is a
RegExp
, it will returncondition.test(message)
- If is a
Function
, it will returncondition(message, lines)
message
<String>: Data message of each linelines
<Array>: An array of data. A data includesmessage
andansiMessage
.ansiMessage
is likemessage
, but includes some ANSI code.
- If is a
options
<String|Object>errorMessage
<String>: Ifcondition
returnsfalse
, it will throw a new error with the message. If theoptions
is aString
, it will become a short hand ofoptions.errorMessage
action
<Function>: An addition function to do something whileassert
function fires. Support returning a promise for async actionshouldShowLog
<Boolean>: Show log message or not. Defaults toKapok.config.shouldShowLog
shouldThrowError
<Boolean>: Throw a new Error or not when assert fails. Defaults toKapok.config.shouldThrowError
- Returns <Kapok>
Iterate each line of the process outputs, and assert the data message of each line.
Example
const kapok = 'echo' 'a\nb\nc';kapok /* using `String` */ /* using `RegExp` */ /* using `Function` */ ;
Kapok#joinUntil(condition[, options])
condition
<Number|String|RegExp|Function>: Decide when to stop grouping lines- If is a
Number
, it will returntrue
if the delta line number is equal withcondition
number - If is a
String
, it will returnmessage === condition
- If is a
RegExp
, it will returncondition.test(message)
- If is a
Function
, it will returncondition(message, lines)
- If is a
options
<Object>join
<String|Function|false>: Join the groupedmessages
into a string- If is a
String
, it will join messages bymessages.join(joinString)
- If is a
Function
, it will join messages byjoin(lines)
- If is
false
, it won't join messages - By default, it is an empty string
- If is a
action
<Function>: An addition function to do something while condition matched. Support returning a promise for async actionshouldShowLog
<Boolean>: Show log message or not. Defaults toKapok.config.shouldShowLog
- Returns <Kapok>
A helper function to join multi lines into a string and pass to the next assert()
. Joining function will stop when condition()
matched.
Example
const input = a: 'hello' b: 'world' ;const code = ` var data = eval(); console.log(JSON.stringify(data, null, 2));`;const kapok = 'node' '-e' code;kapok ;
Kapok#until(condition[, options])
condition
<Number|String|RegExp|Function>: Decide when to start to assert next line- If is a
Number
, it will returntrue
if the delta line number is equal withcondition
number - If is a
String
, it will returnmessage === condition
- If is a
RegExp
, it will returncondition.test(message)
- If is a
Function
, it will returncondition(message, lines)
- If is a
options
<Object>action
<Function>: An addition function to do something while condition matched. Support returning a promise for async actionshouldShowLog
<Boolean>: Show log message or not. Defaults toKapok.config.shouldShowLog
- Returns <Kapok>
Message will not pass to the next assert()
until condition()
matched.
Example
const kapok = 'echo' '# a\n# b\nc';kapok; /* lines before 'c' would be ignored */
Kapok#assertUntil(condition[, options])
condition
<Number|String|RegExp|Function>: Decide when to start to assert- If is a
Number
, it will returntrue
if the delta line number is equal withcondition
number - If is a
String
, it will returnmessage === condition
- If is a
RegExp
, it will returncondition.test(message)
- If is a
Function
, it will returncondition(message, lines)
- If is a
options
<Object>action
<Function>: An addition function to do something while condition matched. Support returning a promise for async actionshouldShowLog
<Boolean>: Show log message or not. Defaults toKapok.config.shouldShowLog
- Returns <Kapok>
Message will not pass to the next assert()
until condition()
matched.
Example
const kapok = 'echo' '# a\n# b\nc';kapok; /* lines before 'c' would be ignored */
Kapok#ignoreUntil(condition[, options])
condition
<Number|String|RegExp|Function>: Decide when to stop ignoring- If is a
Number
, it will returntrue
if the delta line number is equal withcondition
number - If is a
String
, it will returnmessage === condition
- If is a
RegExp
, it will returncondition.test(message)
- If is a
Function
, it will returncondition(message, lines)
- If is a
options
<Object>action
<Function>: An addition function to do something while condition matched. Support returning a promise for async actionshouldShowLog
<Boolean>: Show log message or not. Defaults toKapok.config.shouldShowLog
- Returns <Kapok>
A little like .until()
, but .ignoreUntil()
will event ignore the last line of the matched condition()
.
Example
const kapok = 'echo' '# a\n# b\nc';kapok; /* lines before 'c' would be ignored */
Kapok#done([callback])
callback
<Function>: Provide a callback function. If there's no error, the first argument isundefined
, otherwise, the first argument is an array of errors- Returns <Promise>
Stop asserting. Could provide a callback function or return a promise for async function.
Example
Using jest
const kapok = 'echo' 'hello'; ;
Kapok#doneAndKill([callback])
callback
<Function>: Provide a callback function. If there's no error, the first argument isundefined
, otherwise, the first argument is an array of errors- Returns <Promise>
Like done()
, but also kill the process after stop asserting.
Kapok#kill([signal, callback])
callback
<Function>: Provide a callback function.- Returns <Promise>
Killing kapok process. Could provide a callback function or return a promise for async function.
Event: 'data'
data
<Object>message
<String>: Data messageansiMessage
<String>: Data message includes ANSI code
The data
event will emitted when the stdout
or stderr
output data.
Event: 'out:data'
data
<Object>message
<String>: Data messageansiMessage
<String>: Data message includes ANSI code
The out:data
event will emitted when the stdout
output data.
Event: 'err:data'
data
<Object>message
<String>: Data messageansiMessage
<String>: Data message includes ANSI code
The err:data
event will emitted when the stderr
output data.
Event: 'line'
line
<Object>message
<String>: Data messageansiMessage
<String>: Data message includes ANSI code
The line
event will emitted when the stdout
or stderr
output each lines.
Event: 'out:line'
line
<Object>message
<String>: Data messageansiMessage
<String>: Data message includes ANSI code
The out:line
event will emitted when the stdout
output each lines.
Event: 'err:line'
line
<Object>message
<String>: Data messageansiMessage
<String>: Data message includes ANSI code
The err:line
event will emitted when the stderr
output each lines.
Event: 'error'
The same with child_process error event
Event: 'exit'
The same with child_process exit event
Event: 'signal:exit'
code
<String>: Exit codesignal
<String>: Signal
The signal:exit
event will emitted when receive SIG*
exit event.
License
MIT