Using @jdeighan/base-utils

CHANGELOG How to debug

$ 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
`fails(() => code)`
	- when passed a function, tests that it throws an exception
`throws(() => code, class)`
	- when passed a function, tests that it throws the given Error class
`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:

1. 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.

2. In calls to the equal() and like() functions, the 1st argument is the value, and therefore transformed by the function passed to the transformValue() method, and the 2nd argument is the expected value and therefore transformed by the function passed to the transformExpected() method

3. UnitTester is a class exported by @jdeighan/base-utils/utest. Although I could have created a new class that extends UnitTester, then overridden the transformValue() method in the new class, for simple cases, I prefer to just assign a function to the transformValue 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:

• for-each-file
• gen-bin-key
• gen-parsers
• get-imports-from

Building this project

Build this project using these instructions

How to get a screen shot in Windows 11

1. Press Windows-Shift-S
2. Select an area
3. Open Paint app
4. Paste
5. Save as PNG