$ npm install @jdeighan/base-utils
In the interest of getting some good documentation in place, I'm going to let the unit tests serve as the most detailed documentation. Each module will have a documentation page the gives a summary of the main functions/classes/objects of the module, along with a link to the unit tests for that module
Although I do all of my development using the CoffeeScript language
(coffeescript.org, install with npm install coffeescript
)
that doesn't mean that you need to have CoffeeScript installed to
use these libraries. My projects always include both the CoffeeScript
and JavaScript versions of the libraries and, in fact, you'll see that
I always import the JavaScript files in my libraries.
The /utest
module provides the following functions:
`equal(x,y)`
- tests for deep equality
`like(x,y)`
- tests if a hash has a key/value, but allows additional ones.
when comparing lists of hashes,
applies this test to the hashes in the list
`notequal(x,y)`
- tests for deep inequality
`truthy(x)`
- tests if a value is truthy
`falsy(x)`
- tests if a value is falsy
`throws(() => code)`
- when passed a function, tests that it throws an exception
`succeeds(() => code)`
- when passed a function, tests that it doesn't throw an exception
it also exports a class named UnitTester
and an object named u
.
The u
object is a UnitTester instance. In fact, the u
object
is the object used by the functions above.
So, for example, here are a few unit tests from the base-utils
library:
u.truthy notdefined(undefined)
u.falsy notdefined(12)
u.succeeds () => pass()
u.equal {a:1, b:2}, {a:1, b:2}
u.notequal {a:1, b:2}, {a:1, b:3}
You might note that the tests are not named. The unit tester can determine on which line the tests exist and will report that whether a test succeeds or fails, thus allowing you to locate it quickly.
In addition, you can override methods transformValue()
and/or
transformExpected()
of the u
object. These methods will be called on the
parameters passed to the methods above before the test is performed,
allowing you to avoid calling the same function on a series of unit tests
just to test the same function.
As an example, there is a function named escapeStr()
that will take a
string and change TAB characters to →
, space characters to ˳
,
newline characters to ▼
and carriage return characters to ◄
.
You might want to test a bunch of input strings like this:
equal escapeStr(" XXX\n"), "˳˳˳XXX▼"
equal escapeStr("\t ABC\n"), "→˳ABC▼"
equal escapeStr("X\nX\nX\n"), "X▼X▼X▼"
equal escapeStr("XXX\n\t\t"), "XXX▼→→"
equal escapeStr("XXX\n "), "XXX▼˳˳"
But you could also define a transformValue()
method, then simplify
the tests, e.g.:
(() =>
t = new UnitTester()
t.transformValue = (str) => escapeStr(str)
equal " XXX\n", "˳˳˳XXX▼"
equal "\t ABC\n", "→˳ABC▼"
equal "X\nX\nX\n", "X▼X▼X▼"
equal "XXX\n\t\t", "XXX▼→→"
equal "XXX\n ", "XXX▼˳˳"
)()
NOTE:
-
When you need to create a new variable in a unit test, it's best to wrap the test(s) in an anonymous function, then immediately call it. Since the variable is isolated from the rest of the code, you needn't worry about name clashes with variables that you might create later on.
-
In calls to the
equal()
andlike()
functions, the 1st argument is the value, and therefore transformed by the function passed to thetransformValue()
method, and the 2nd argument is the expected value and therefore transformed by the function passed to thetransformExpected()
method -
UnitTester
is a class exported by@jdeighan/base-utils/utest
. Although I could have created a new class that extends UnitTester, then overridden thetransformValue()
method in the new class, for simple cases, I prefer to just assign a function to thetransformValue
property on the base class.
his project includes these libraries:
- / - basic utilities
- /ll-fs - low-level file system utilities
- /source-map - use source maps to map line numbers
- /v8-stack - get JS call stack
- /exceptions - exception handling
- /cmd-args - get command line arguments
- /utest - unit test utilities
- /prefix - handle line prefixes, e.g. indentation
- /named-logs - save logs keyed by a name
- /indent - handle line indentations
- /taml - allow TABS in yaml-like strings, etc.
- /log - advanced logging
- /stack - manage our own call stack
- /debug - advanced debugging
- /state-machine - finite state machine
- /fs - file system utilities
- /FileProcessor - read, then rewrite files
This project includes these binaries:
Build this project using these instructions
- Press Windows-Shift-S
- Select an area
- Open Paint app
- Paste
- Save as PNG