mirror of
https://github.com/flynx/test.js.git
synced 2025-12-19 10:01:41 +00:00
most of the docs are done, minor tweaks and editing left...
Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
This commit is contained in:
parent
8a4498d323
commit
b4b8517fc7
313
README.md
313
README.md
@ -1,11 +1,44 @@
|
||||
# test.js
|
||||
experimental test runner....
|
||||
|
||||
Experimental test runner....
|
||||
|
||||
## Features
|
||||
|
||||
XXX
|
||||
|
||||
## Contents
|
||||
- [test.js](#testjs)
|
||||
- [Features](#features)
|
||||
- [Contents](#contents)
|
||||
- [Architecture](#architecture)
|
||||
- [Combinational testing](#combinational-testing)
|
||||
- [Unit testing](#unit-testing)
|
||||
- [Basic usage](#basic-usage)
|
||||
- [Components](#components)
|
||||
- [`DEFAULT_TEST_FILES`](#default_test_files)
|
||||
- [`IGNORE_TEST_FILES`](#ignore_test_files)
|
||||
- [`Merged(..)`](#merged)
|
||||
- [`<merged>.members`](#mergedmembers)
|
||||
- [`<merged>.size` / `<merged>.usize`](#mergedsize--mergedusize)
|
||||
- [`<merged>.add(..)` / `<merged>.remove(..)`](#mergedadd--mergedremove)
|
||||
- [`<merged>.clear()`](#mergedclear)
|
||||
- [`<merged>.keys(..)` / `<merged>.values(..)` / `<merged>.entries(..)`](#mergedkeys--mergedvalues--mergedentries)
|
||||
- [`<merged>.toObject(..)`](#mergedtoobject)
|
||||
- [`<merged>.checkShadowing(..)`](#mergedcheckshadowing)
|
||||
- [`<merged>.handleShadowing(..)`](#mergedhandleshadowing)
|
||||
- [`<member>.filename`](#memberfilename)
|
||||
- [`Setups(..)` / `Setup(..)` (Merged)](#setups--setup-merged)
|
||||
- [`Modifiers(..)` / `Modifier(..)` (Merged)](#modifiers--modifier-merged)
|
||||
- [`Tests(..)` / `Test(..)` (Merged)](#tests--test-merged)
|
||||
- [`Cases(..)` / `Case(..)` (Merged)](#cases--case-merged)
|
||||
- [`Assert(..)`](#assert)
|
||||
- [`run(..)`](#run)
|
||||
- [Advanced components](#advanced-components)
|
||||
- [`runner(..)`](#runner)
|
||||
- [`parser(..)`](#parser)
|
||||
- [Utilities](#utilities)
|
||||
- [`getCallerFilename()`](#getcallerfilename)
|
||||
- [License](#license)
|
||||
|
||||
|
||||
## Architecture
|
||||
@ -17,6 +50,7 @@ This package implements two testing schemes:
|
||||
- Unit testing
|
||||
Simple independent tests.
|
||||
|
||||
|
||||
### Combinational testing
|
||||
|
||||
In general the idea here is that you define three things:
|
||||
@ -52,30 +86,305 @@ This is the traditional self-contained test approach.
|
||||
|
||||
## Basic usage
|
||||
|
||||
```shell_session
|
||||
$ touch test.js
|
||||
$ chmod +x test.js
|
||||
```
|
||||
|
||||
The code:
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
|
||||
var test = require('ig-test')
|
||||
|
||||
test.Setups({
|
||||
basic: function(assert){
|
||||
state: function(assert){
|
||||
return {
|
||||
a: 123,
|
||||
b: 321,
|
||||
} },
|
||||
})
|
||||
|
||||
test.Modifiers({
|
||||
inc: function(assert, state){
|
||||
Object.keys(state)
|
||||
.forEach(function(k){
|
||||
state[k] += 1 })
|
||||
return state },
|
||||
})
|
||||
|
||||
test.Tests({
|
||||
|
||||
})
|
||||
|
||||
test.Cases({
|
||||
|
||||
})
|
||||
|
||||
// make the test runnable as a standalone script...
|
||||
__filename == (require.main || {}).filename
|
||||
&& tests.run()
|
||||
```
|
||||
|
||||
Run the tests
|
||||
```shell_session
|
||||
$ runtests
|
||||
```
|
||||
|
||||
or
|
||||
```shell_session
|
||||
$ node ./test.js
|
||||
```
|
||||
|
||||
|
||||
## Components
|
||||
|
||||
### `DEFAULT_TEST_FILES`
|
||||
|
||||
[`glob`][glob] pattern(s) used to find test files by default.
|
||||
```
|
||||
DEFAULT_TEST_FILES =
|
||||
undefined
|
||||
| <path>
|
||||
| [ <path>, .. ]
|
||||
```
|
||||
|
||||
Default value: `"**/?(*-)test.js"`
|
||||
|
||||
|
||||
### `IGNORE_TEST_FILES`
|
||||
|
||||
A list of [`glob`][glob] patterns to ignore while searching for tests.
|
||||
```
|
||||
IGNORE_TEST_FILES =
|
||||
undefined
|
||||
| [ <path>, .. ]
|
||||
```
|
||||
|
||||
Default value: `['node_modules/**']`
|
||||
|
||||
|
||||
### `Merged(..)`
|
||||
|
||||
Implements a _merged_ collection of instances (_members_).
|
||||
```
|
||||
Merged({ <key>: <func>, .. })
|
||||
-> <member>
|
||||
|
||||
Merged(<key>, <func>)
|
||||
-> <member>
|
||||
```
|
||||
|
||||
On construction this will assign the input object / `<key>`-`<func>` into the resulting
|
||||
`<member>`/instance object.
|
||||
|
||||
Each `<member>`/instance created is added to the constructor as a _member_ (i.e.
|
||||
added into `.members`)
|
||||
|
||||
Provides a set of methods and properties to access/introspect the _merged_
|
||||
(hence the name) attributes of the _members_ (i.e. `.keys(..)`, `.values(..)`,
|
||||
`.entries(..)`, `.size`/`.usize` and `.members`).
|
||||
|
||||
|
||||
#### `<merged>.members`
|
||||
|
||||
List of _members_ / instances of `Merged` in order of creation.
|
||||
|
||||
|
||||
#### `<merged>.size` / `<merged>.usize`
|
||||
|
||||
Number of _members_ including the `"-"` members and not including respectively.
|
||||
|
||||
#### `<merged>.add(..)` / `<merged>.remove(..)`
|
||||
|
||||
Add / remove a member.
|
||||
```
|
||||
<merged>.add(<member>)
|
||||
-> <merged>
|
||||
|
||||
<merged>.remove(<member>)
|
||||
-> <merged>
|
||||
```
|
||||
|
||||
#### `<merged>.clear()`
|
||||
|
||||
Remove (_clear_) all the members.
|
||||
|
||||
|
||||
#### `<merged>.keys(..)` / `<merged>.values(..)` / `<merged>.entries(..)`
|
||||
|
||||
```
|
||||
<merged>.keys()
|
||||
<merged>.keys(<merged>)
|
||||
-> <list>
|
||||
|
||||
<merged>.values()
|
||||
<merged>.values(<merged>)
|
||||
-> <list>
|
||||
|
||||
<merged>.entries()
|
||||
<merged>.entries(<merged>)
|
||||
-> <list>
|
||||
```
|
||||
|
||||
These are similar to `Object.keys(..)` / `Object.values(..)` / `Object.entries(..)`
|
||||
but will also if called without arguments return a list of the callers member
|
||||
keys/values/entries respectively.
|
||||
|
||||
Note that members' attributes can _shadow_ previous member attributes, only one
|
||||
value per key will be returned. `<merged>` will warn when adding a member of its
|
||||
attributes will _shadow_ already existing members' attributes (see:
|
||||
[`<merged>.checkShadowing(..)`](#mergedcheckshadowing) and
|
||||
[`<merged>.handleShadowing(..)`](#mergedhandleshadowing));
|
||||
Also note that the check for shadowing is performed when the `<member>` is
|
||||
created and not when new attributes are added manually.
|
||||
|
||||
|
||||
#### `<merged>.toObject(..)`
|
||||
|
||||
Create an object containing all visible member attributes.
|
||||
```
|
||||
<merged>.toObject()
|
||||
-> <object>
|
||||
```
|
||||
|
||||
#### `<merged>.checkShadowing(..)`
|
||||
|
||||
Find all shadowed attributes within `<merged>`.
|
||||
```
|
||||
<merged>.checkShadowing()
|
||||
```
|
||||
|
||||
Find all attributes in `<merged>` that will be shadowed by `<member>`
|
||||
```
|
||||
<merged>.checkShadowing(<member>)
|
||||
-> <list>
|
||||
```
|
||||
|
||||
|
||||
#### `<merged>.handleShadowing(..)`
|
||||
|
||||
Will be called on `<member>` construction when attribute _shadowing_ is detected.
|
||||
```
|
||||
`<merged>.handleShadowing(<attr>)`
|
||||
-> <merged>
|
||||
```
|
||||
|
||||
By default this will print a warning and continue, but can be overloaded by the
|
||||
user to react to _shadowing_ in a different manner.
|
||||
|
||||
|
||||
#### `<member>.filename`
|
||||
|
||||
The filename where the `<member>` was defined.
|
||||
|
||||
|
||||
### `Setups(..)` / `Setup(..)` (Merged)
|
||||
|
||||
XXX
|
||||
|
||||
A _subclass_ or rather _sub-constructor_ of `Merged`.
|
||||
|
||||
Note that `Setups` and `Setup` are references to the same object, they exists
|
||||
for better readability in cases when we add a single test or a bunch of tests,
|
||||
e.g:
|
||||
```javascript
|
||||
test.Setup('some-setup',
|
||||
function(){
|
||||
// ...
|
||||
})
|
||||
|
||||
test.Setups({
|
||||
'some-other-setup': function(){
|
||||
// ...
|
||||
},
|
||||
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### `Modifiers(..)` / `Modifier(..)` (Merged)
|
||||
|
||||
XXX
|
||||
|
||||
A _sub-constructor_ of `Merged`.
|
||||
|
||||
### `Tests(..)` / `Test(..)` (Merged)
|
||||
|
||||
XXX
|
||||
|
||||
A _sub-constructor_ of `Merged`.
|
||||
|
||||
### `Cases(..)` / `Case(..)` (Merged)
|
||||
|
||||
XXX
|
||||
|
||||
A _sub-constructor_ of `Merged`.
|
||||
|
||||
|
||||
### `Assert(..)`
|
||||
|
||||
XXX this may still change...
|
||||
|
||||
|
||||
### `run(..)`
|
||||
|
||||
Run the test system.
|
||||
```
|
||||
run()
|
||||
run(<tests>)
|
||||
run(<default-files>)
|
||||
run(<default_files>, <tests>)
|
||||
-> <parse-result>
|
||||
```
|
||||
|
||||
This will:
|
||||
- parse `process.argv`
|
||||
- locate and run tests
|
||||
- report basic stats
|
||||
|
||||
`<tests>` format:
|
||||
```
|
||||
{
|
||||
setups: <stups>,
|
||||
modifiers: <modifiers>,
|
||||
tests: <tests>,
|
||||
cases: <cases>,
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Advanced components
|
||||
|
||||
### `runner(..)`
|
||||
|
||||
The default test combinator and runner.
|
||||
|
||||
|
||||
### `parser(..)`
|
||||
|
||||
The default [`ig-argv`][ig-argv] parser setup.
|
||||
|
||||
|
||||
## Utilities
|
||||
|
||||
### `getCallerFilename()`
|
||||
|
||||
Returns the filename of the module where `getCallerFilename()` is called.
|
||||
|
||||
|
||||
## License
|
||||
|
||||
[BSD 3-Clause License](./LICENSE)
|
||||
|
||||
Copyright (c) 2016-2020, Alex A. Naanou,
|
||||
All rights reserved.
|
||||
|
||||
|
||||
<!-- External links -->
|
||||
[glob]: https://github.com/isaacs/node-glob
|
||||
[object.js]: https://github.com/flynx/object.js
|
||||
[ig-argv]: https://github.com/flynx/argv.js
|
||||
|
||||
|
||||
<!-- vim:set ts=4 sw=4 spell : -->
|
||||
4
test.js
4
test.js
@ -232,7 +232,9 @@ object.Constructor('Assert', {
|
||||
|
||||
//---------------------------------------------------------------------
|
||||
|
||||
// XXX
|
||||
var mergeIter = function(iter){
|
||||
// XXX should this get a function as argument???
|
||||
return function(c){
|
||||
c = c || this
|
||||
return (c.members || [])
|
||||
@ -309,7 +311,7 @@ object.Constructor('Merged', {
|
||||
checkShadowing: function(other){
|
||||
var existing = new Set(this.keys())
|
||||
|
||||
other = other || this.values()
|
||||
other = other || this.members
|
||||
return (other instanceof Array ?
|
||||
other
|
||||
: [other])
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user