https://github.com/cap32/kapok-js
Javascript Testing utilities for CLI
https://github.com/cap32/kapok-js
cli javascript node node-js nodejs test testing testing-framework testing-tools utilities
Last synced: about 1 year ago
JSON representation
Javascript Testing utilities for CLI
- Host: GitHub
- URL: https://github.com/cap32/kapok-js
- Owner: Cap32
- License: mit
- Created: 2017-04-30T09:40:45.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2018-01-21T07:00:16.000Z (over 8 years ago)
- Last Synced: 2025-04-22T12:12:23.491Z (about 1 year ago)
- Topics: cli, javascript, node, node-js, nodejs, test, testing, testing-framework, testing-tools, utilities
- Language: JavaScript
- Homepage:
- Size: 93.8 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# kapok-js
[](https://travis-ci.org/Cap32/kapok-js) [](https://circleci.com/gh/Cap32/kapok-js)
Javascript Testing utilities for CLI
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [Kapok.config](#kapokconfig)
- [Kapok.start\(command\[, args\]\[, options\]\)](#kapokstartcommand-args-options)
- [Kapok.size](#kapoksize)
- [Kapok.killAll\(\)](#kapokkillall)
- [Kapok#constructor\(command\[, args\]\[, options\]\)](#kapokconstructorcommand-args-options)
- [Kapok#assert\(condition\[, options\]\)](#kapokassertcondition-options)
- [Kapok#joinUntil\(condition\[, options\]\)](#kapokjoinuntilcondition-options)
- [Kapok#until\(condition\[, options\]\)](#kapokuntilcondition-options)
- [Kapok#assertUntil\(condition\[, options\]\)](#kapokassertuntilcondition-options)
- [Kapok#ignoreUntil\(condition\[, options\]\)](#kapokignoreuntilcondition-options)
- [Kapok#done\(\[callback\]\)](#kapokdonecallback)
- [Kapok#doneAndKill\(\[callback\]\)](#kapokdoneandkillcallback)
- [Kapok#kill\(\[signal, callback\]\)](#kapokkillsignal-callback)
- [Event: 'data'](#event-data)
- [Event: 'out:data'](#event-outdata)
- [Event: 'err:data'](#event-errdata)
- [Event: 'line'](#event-line)
- [Event: 'out:line'](#event-outline)
- [Event: 'err:line'](#event-errline)
- [Event: 'error'](#event-error)
- [Event: 'exit'](#event-exit)
- [Event: 'signal:exit'](#event-signalexit)
- [License](#license)
```bash
yarn add -D kapok-js
```
```js
import Kapok from 'kapok-js';
const kapok = new Kapok('echo', ['hello\nworld']);
kapok.assert('hello').assert('world');
```
##### Advanced Usage
```js
import Kapok from 'kapok-js';
import { isEqual } from 'lodash';
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 = new Kapok('node', ['-e', code]); /* just like childProcess.spawn() */
kapok
.ignoreUntil(/\*/) /* ignore lines until the line matches "*" */
.assert('start')
.joinUntil('}') /* join multi lines until the line is equal to '}', and then join the lines into a string */
.assert((message) => isEqual({ hello: 'world' }, JSON.parse(message)))
.assert('end')
.done(() => {
console.log('done');
})
;
```
- `config.shouldShowLog` \: Show log message or not. Defaults to `true`
- `config.shouldThrowError` \: Throw a new Error or not when assert fails. Defaults to `false`
A global config to all `Kapok` instances. Can be override.
---
#### Kapok.start(command[, args][, options])
- `command` \: The command to run
- `args` \: List of string arguments
- `options` \: Just like [spawn options](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options)
- Returns \
Spawns a new process using the given `command`, just like `child_process.spawn()`, but returns a `Kapok` instance.
`Kapok` inherits [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
---
- Returns \
Get existing kapok instances size
---
- Return \
Kill all existing kapok instances
---
#### Kapok#constructor(command[, args][, options])
The same with `Kapok.start()`
---
#### Kapok#assert(condition[, options])
- `condition` \: Testing `message`, throw an error if returns `false`. The `message` is the each line data of process outputs
+ If is a `String`, it will return `message === condition`
+ If is a `RegExp`, it will return `condition.test(message)`
+ If is a `Function`, it will return `condition(message, lines)`
* `message` \: Data message of each line
* `lines` \: An array of data. A data includes `message` and `ansiMessage`. `ansiMessage` is like `message`, but includes some ANSI code.
- `options`
+ `errorMessage` \: If `condition` returns `false`, it will throw a new error with the message. If the `options` is a `String`, it will become a short hand of `options.errorMessage`
+ `action` \: An addition function to do something while `assert` function fires. Support returning a promise for async action
+ `shouldShowLog` \: Show log message or not. Defaults to `Kapok.config.shouldShowLog`
+ `shouldThrowError` \: Throw a new Error or not when assert fails. Defaults to `Kapok.config.shouldThrowError`
- Returns \
Iterate each line of the process outputs, and assert the data message of each line.
###### Example
```js
const kapok = new Kapok('echo', ['a\nb\nc']);
kapok
.assert('a') /* using `String` */
.assert(/b/) /* using `RegExp` */
.assert((message) => message === 'c') /* using `Function` */
.done()
;
```
---
#### Kapok#joinUntil(condition[, options])
- `condition` \: Decide when to stop grouping lines
+ If is a `Number`, it will return `true` if the delta line number is equal with `condition` number
+ If is a `String`, it will return `message === condition`
+ If is a `RegExp`, it will return `condition.test(message)`
+ If is a `Function`, it will return `condition(message, lines)`
- `options` \
+ `join` : Join the grouped `messages` into a string
* If is a `String`, it will join messages by `messages.join(joinString)`
* If is a `Function`, it will join messages by `join(lines)`
* If is `false`, it won't join messages
* By default, it is an empty string
+ `action` \: An addition function to do something while condition matched. Support returning a promise for async action
+ `shouldShowLog` \: Show log message or not. Defaults to `Kapok.config.shouldShowLog`
- Returns \
A helper function to join multi lines into a string and pass to the next `assert()`. Joining function will stop when `condition()` matched.
###### Example
```js
const input = { a: 'hello', b: 'world' };
const code = `
var data = eval(${JSON.stringify(input)});
console.log(JSON.stringify(data, null, 2));
`;
const kapok = new Kapok('node', ['-e', code]);
kapok
.joinUntil('}')
.assert((message) => {
const json = JSON.parse(message);
return isEqual(json, input);
})
.done()
;
```
---
#### Kapok#until(condition[, options])
- `condition` \: Decide when to start to assert next line
+ If is a `Number`, it will return `true` if the delta line number is equal with `condition` number
+ If is a `String`, it will return `message === condition`
+ If is a `RegExp`, it will return `condition.test(message)`
+ If is a `Function`, it will return `condition(message, lines)`
- `options` \
+ `action` \: An addition function to do something while condition matched. Support returning a promise for async action
+ `shouldShowLog` \: Show log message or not. Defaults to `Kapok.config.shouldShowLog`
- Returns \
Message will not pass to the next `assert()` until `condition()` matched.
###### Example
```js
const kapok = new Kapok('echo', ['# a\n# b\nc']);
kapok.until(/^[^#]/).assert('c').done(); /* lines before 'c' would be ignored */
```
---
#### Kapok#assertUntil(condition[, options])
- `condition` \: Decide when to start to assert
+ If is a `Number`, it will return `true` if the delta line number is equal with `condition` number
+ If is a `String`, it will return `message === condition`
+ If is a `RegExp`, it will return `condition.test(message)`
+ If is a `Function`, it will return `condition(message, lines)`
- `options` \
+ `action` \: An addition function to do something while condition matched. Support returning a promise for async action
+ `shouldShowLog` \: Show log message or not. Defaults to `Kapok.config.shouldShowLog`
- Returns \
Message will not pass to the next `assert()` until `condition()` matched.
###### Example
```js
const kapok = new Kapok('echo', ['# a\n# b\nc']);
kapok.assertUntil('c').done(); /* lines before 'c' would be ignored */
```
---
#### Kapok#ignoreUntil(condition[, options])
- `condition` \: Decide when to stop ignoring
+ If is a `Number`, it will return `true` if the delta line number is equal with `condition` number
+ If is a `String`, it will return `message === condition`
+ If is a `RegExp`, it will return `condition.test(message)`
+ If is a `Function`, it will return `condition(message, lines)`
- `options` \
+ `action` \: An addition function to do something while condition matched. Support returning a promise for async action
+ `shouldShowLog` \: Show log message or not. Defaults to `Kapok.config.shouldShowLog`
- Returns \
A little like `.until()`, but `.ignoreUntil()` will event ignore the last line of the matched `condition()`.
###### Example
```js
const kapok = new Kapok('echo', ['# a\n# b\nc']);
kapok.ignoreUntil(/^#/).assert('c'); /* lines before 'c' would be ignored */
```
---
- `callback` \: Provide a callback function. If there's no error, the first argument is `undefined`, otherwise, the first argument is an array of errors
- Returns \
Stop asserting. Could provide a callback function or return a promise for async function.
###### Example
Using [jest](http://facebook.github.io/jest/)
```js
const kapok = new Kapok('echo', ['hello']);
test('echo', async () => kapok.assert('hello').done());
```
---
#### Kapok#doneAndKill([callback])
- `callback` \: Provide a callback function. If there's no error, the first argument is `undefined`, otherwise, the first argument is an array of errors
- Returns \
Like `done()`, but also kill the process after stop asserting.
---
#### Kapok#kill([signal, callback])
- `callback` \: Provide a callback function.
- Returns \
Killing kapok process. Could provide a callback function or return a promise for async function.
---
- `data` \
+ `message` \: Data message
+ `ansiMessage` \: Data message includes ANSI code
The `data` event will emitted when the `stdout` or `stderr` output data.
- `data` \
+ `message` \: Data message
+ `ansiMessage` \: Data message includes ANSI code
The `out:data` event will emitted when the `stdout` output data.
- `data` \
+ `message` \: Data message
+ `ansiMessage` \: Data message includes ANSI code
The `err:data` event will emitted when the `stderr` output data.
- `line` \
+ `message` \: Data message
+ `ansiMessage` \: Data message includes ANSI code
The `line` event will emitted when the `stdout` or `stderr` output each lines.
- `line` \
+ `message` \: Data message
+ `ansiMessage` \: Data message includes ANSI code
The `out:line` event will emitted when the `stdout` output each lines.
- `line` \
+ `message` \: Data message
+ `ansiMessage` \: Data message includes ANSI code
The `err:line` event will emitted when the `stderr` output each lines.
The same with [child_process error event](https://nodejs.org/api/child_process.html#child_process_event_error)
The same with [child_process exit event](https://nodejs.org/api/child_process.html#child_process_event_exit)
- `code` \: Exit code
- `signal` \: Signal
The `signal:exit` event will emitted when receive `SIG*` exit event.
MIT