Why unit testing?
There are many test packages for Node (my favorite is ava) and there are also a few for Apps Script but I couldn’t find one that was exactly what I was after, so I’ve released the one I use as a library. Unit testing your code as you go along will make it easier to find errors right away, check results are as expected, and keeping a running repertoire of tests ensures that you don’t break anything when you make changes.
Here’s how it works.
Initializing Unit tester
You’ll need the bmUnitTest library – library details at the end of this post.
// unit tester
const unit = new bmUnitTester.Unit()
initialize an instance
There are a number of behavioral options, but we’ll deal with them throughout the course of this library. This library is deliberately simple to use straight out of the box.
Test sections
Tests are best organized into sections – so you can keep your tests all together but easily skip irrelevant tests when required. A test section looks like this
unit.section(() => {
unit.is('foo', 'foo')
unit.not('foo', 'bar')
})
test section
2 methods
is (expected, actual, options) – it passes if expected equals actual
not (expected, actual. options) – it passes if expected not equals actual
The definition of ‘equals’ is the key to the simplicity of this library.
results
unit.section(() => {
unit.is('foo', 'foo')
unit.not('foo', 'bar')
})
Starting section
0.0 - passed (true test) "foo"
0.1 - passed (false test) "bar"
Finished section passes: 2 failures: 0
section results
Adding descriptions
Sections and tests can have descriptions. Here’s a more descriptive version of those tests and section
unit.section(() => {
unit.is('foo', 'foo', { description: 'foo is foo' })
unit.not('foo', 'bar', { description: 'foo is not bar' })
}, { description: 'sections can have descriptions' })
Starting section sections can have descriptions
1.0 foo is foo - passed (true test) "foo"
1.1 foo is not bar - passed (false test) "bar"
Finished section sections can have descriptions passes: 2 failures: 0
descriptions
Deep equality
Comparing for equality is complicated in JavaScript. Unit test by default uses deepEqual – so an object is deemed equal to another object if they have the same properties, property types and property values. You can specify a custom compare function, but deepEqual is almost always what you want. These examples show how the standard JavaScript equality test compares with deepEqual.
// tests for equality by default use 'deepEqual
unit.section(() => {
const fixture = { a: 1, b: 2, c: { x: [1, 2, 3] } }
unit.is(fixture, fixture, { description: 'deep equal comparison' })
unit.is(fixture, { ...fixture }, { description: 'deep equal compares object values/content' })
unit.not(fixture, { ...fixture }, {
description: 'Using a custom compare',
compare: (expect, actual) => expect === actual
})
}, { description: 'deepequal versus javascript equal' })
Starting section deepequal versus javascript equal
2.0 deep equal comparison - passed (true test) {"a":1,"b":2,"c":{"x":[1,2,3]}}
2.1 deep equal compares object values/content - passed (true test) {"a":1,"b":2,"c":{"x":[1,2,3]}}
2.2 Using a custom compare - passed (false test) {"a":1,"b":2,"c":{"x":[1,2,3]}}
Finished section deepequal versus javascript equal passes: 3 failures: 0
deepequal comparison
Undefined and null
You normally don’t want to see an undefined anywhere, but a null is acceptable. By default Unit always treats undefined as an error, and null as a normal object. As usual this is modifiable via options at instance, section or test level. In these examples the usual equality tests are modified by whether undefined and null are ever acceptable values.
Here’s how.
unit.section(() => {
unit.is (undefined, undefined, {description: 'by default undefined is never good'})
unit.is (null, null, {description: 'but null can be ok'})
unit.is (undefined, undefined, {
neverUndefined: false,
description: 'but we can change that to allow undefined'
})
unit.is (null, null, {
neverNull: true,
description: 'and lets make null always bad also'
})
}, {description: 'null and undefined treatment'})
Starting section null and undefined treatment
3.0 by default undefined is never good - failed (true test) {
[ Unexpected value: Expected undefined but got undefined]
name: 'Unexpected value',
expectedValue: undefined,
actualValue: undefined
}
3.1 but null can be ok - passed (true test) null
3.2 but we can change that to allow undefined - passed (true test) undefined
3.3 and lets make null always bad also - failed (true test) {
[ Unexpected value: Expected null but got null]
name: 'Unexpected value',
expectedValue: null,
actualValue: null
}
Finished section null and undefined treatment passes: 2 failures: 2
dealing with undefined and null
Options
You’ll have noticed a number of options specified in the tests so far. A full list of available options is given at the end of this article. Here’s some examples of overriding section level options with test level options.
unit.section (()=> {
unit.is (2,1)
unit.is(1,1, {description: 'this one will fail with the section compare function'})
unit.is(1,1, {description: 'but is ok with the default deepequal', compare: unit.defaultCompare})
unit.is(100,50)
}, {
description: 'all options can be set at instance, section or test level',
compare: (expect, actual) => expect === actual *2
})
1:00:11 PM Info Starting section all options can be set at instance, section or test level
1:00:11 PM Info 4.0 - passed (true test) 1
1:00:11 PM Info 4.1 this one will fail with the section compare function - failed (false test) { [Unexpected value: Expected 1 but got 1] name: 'Unexpected value', expectedValue: 1, actualValue: 1 }
1:00:11 PM Info 4.2 but is ok with the default deepequal - passed (true test) 1
1:00:11 PM Info 4.3 - passed (true test) 50
1:00:11 PM Info Finished section all options can be set at instance, section or test level passes: 3 failures: 1
overriding options
Test return object
A test will return an object describing the test and the result, which may be useful for further processing. The UnitResult response look like this
unit.section (()=> {
console.log(unit.is ([1,2],[1,2]))
}, {
description: 'tests return a useful object'
})
example UnitResult
{ options:
{ compare: [Function: compare],
invert: false,
description: '',
neverUndefined: true,
neverNull: false,
showErrorsOnly: false,
skip: false },
section:
{ test: [Function],
results: [ [Circular] ],
number: 5,
options:
{ compare: [Function: compare],
invert: false,
description: 'tests return a useful object',
neverUndefined: true,
neverNull: false,
showErrorsOnly: false,
skip: false } },
testNumber: 0,
eql: true,
failed: false,
expect: [ 1, 2 ],
actual: [ 1, 2 ],
jsEqual: false
}
UnitResult
/**
* UnitResult
* @typedef {Object} UnitResult
* @property {TestOptions} options - the test options
* @property {UnitSection} section - The section this result belongs to
* @property {number} testNumber - Serial number within the section
* @property {boolean} eql - whether actual equals expected using the compare function (default deep equality)
* @property {boolean} failed - whether the test failed
* @property {boolean} jsEqual whether expected === actual (vanilla javascript equality)
* @property {*} expect - the expected value
* @property {*} actual - the actual value
*/
TestOptions
/**
* @typedef {Object} TestOptions
* @property {function} [compare = this.defaultCompare] - function to compare expected to actual
* @property {boolean} [invert = false] - whether success is that expected !== actual
* @property {string} [description = ''] - The test description
* @property {boolean} [neverUndefined = true] - if actual is ever undefined it's a failure
* @property {boolean} [neverNull = false] - if actual is ever null it's a failure
* @property {boolean} [showErrorsOnly = false] - only verbose if there's an error
*/
UnitSection
/**
* @typedef {Object} UnitSection
* @property {function} test - The section test collection
* @property {UnitResult[]} results - The results for this section
* @property {number} number - the section serial number
* @property {TestOptions} options - the section options
*/
UnitResult object
Skipping tests and sections
Sometimes you might want to skip sections or individual tests. You can use the skip option to temporary disable a section or a test
Skipping a section
When a section is skipped it is reported but not executed
unit.section (()=> {
unit.is('foo','bar')
}, {
description: 'entire sections can be skipped',
skip: true
})
1:00:11 PM Info Skipping section entire sections can be skipped
skip section
Skipping a test
When an individual test is skipped it is completely ignored
unit.section (()=> {
unit.not('foo','bar', {description: 'this one will run'})
unit.not('foo','bar', {description: 'this one will be skipped and not even reported', skip:true})
}, {
description: 'so can individual tests',
})
1:00:11 PM Info Starting section so can individual tests
1:00:11 PM Info 7.0 this one will run - passed (false test) "bar"
1:00:11 PM Info Finished section so can individual tests passes: 1 failures: 0
skip test
Reducing verbosity
Once you’ve established a test set you probably will only want to see the reports of the failures. You can use the showErrorsOnly option to do that at instance, section or individual test level. Let’s rerun all the tests in this article, but this time only show the errors.
const unit = new bmUnitTester.Unit({showErrorsOnly: true})
... all the sections in this article so far
Starting section
1:17:03 PM Info Finished section passes: 2 failures: 0
1:17:03 PM Info Starting section sections can have descriptions
1:17:03 PM Info Finished section sections can have descriptions passes: 2 failures: 0
1:17:03 PM Info Starting section deepequal versus javascript equal
1:17:03 PM Info Finished section deepequal versus javascript equal passes: 3 failures: 0
1:17:03 PM Info Starting section null and undefined treatment
1:17:03 PM Info 3.0 by default undefined is never good - failed (true test) { [Unexpected value: Expected undefined but got undefined]
name: 'Unexpected value',
expectedValue: undefined,
actualValue: undefined }
1:17:03 PM Info 3.3 and lets make null always bad also - failed (true test) { [Unexpected value: Expected null but got null]
name: 'Unexpected value',
expectedValue: null,
actualValue: null }
1:17:03 PM Info Finished section null and undefined treatment passes: 2 failures: 2
1:17:03 PM Info Starting section all options can be set at instance, section or test level
1:17:03 PM Info 4.1 this one will fail with the section compare function - failed (false test) { [Unexpected value: Expected 1 but got 1] name: 'Unexpected value', expectedValue: 1, actualValue: 1 }
1:17:03 PM Info Finished section all options can be set at instance, section or test level passes: 3 failures: 1
1:17:03 PM Info Starting section tests return a useful object
1:17:03 PM Info Finished section tests return a useful object passes: 1 failures: 0
1:17:03 PM Info Skipping section entire sections can be skipped
1:17:03 PM Info Starting section so can individual tests
1:17:03 PM Info Finished section so can individual tests passes: 1 failures: 0
showing only the tests with errors
Test set summary
At the end of it all, you can request a report of how it all went
unit.report()
1:17:03 PM Info Section summary
1:17:03 PM Info passes 2 failures 0
1:17:03 PM Info sections can have descriptions passes 2 failures 0
1:17:03 PM Info deepequal versus javascript equal passes 3 failures 0
1:17:03 PM Info null and undefined treatment passes 2 failures 2
1:17:03 PM Info all options can be set at instance, section or test level passes 3 failures 1
1:17:03 PM Info tests return a useful object passes 1 failures 0
1:17:03 PM Info entire sections can be skipped passes 0 failures 0
1:17:03 PM Info so can individual tests passes 1 failures 0
1:17:03 PM Info Total passes 14 (82.4%) Total failures 3 (17.6%)
1:17:03 PM Info SOME TESTS FAILED
summary report
List of methods and properties
Here’s the skeleton class. You can call any of these if you need some more fine control of the tests. The full code is on github or via the IDE at the end of this article
/**
* UnitResult
* @typedef {Object} UnitResult
* @property {TestOptions} options - the test options
* @property {UnitSection} section - The section this result belongs to
* @property {number} testNumber - Serial number within the section
* @property {boolean} eql - whether actual equals expected using the compare function (default deep equality)
* @property {boolean} failed - whether the test failed
* @property {boolean} jsEqual whether expected === actual (vanilla javascript equality)
* @property {*} expect - the expected value
* @property {*} actual - the actual value
*/
/**
* @typedef {Object} UnitSection
* @property {function} test - The section test collection
* @property {UnitResult[]} results - The results for this section
* @property {number} number - the section serial number
* @property {TestOptions} options - the section options
*/
/**
* @typedef {Object} TestOptions
* @property {function} [compare = this.defaultCompare] - function to compare expected to actual
* @property {boolean} [invert = false] - whether success is that expected !== actual
* @property {string} [description = ''] - The test description
* @property {boolean} [neverUndefined = true] - if actual is ever undefined it's a failure
* @property {boolean} [neverNull = false] - if actual is ever null it's a failure
* @property {boolean} [showErrorsOnly = false] - only verbose if there's an error
*/
TestOptions defaults
{
compare: (expect, actual) => {
return deepEquals(expect, actual)
},
invert: false,
description: '',
neverUndefined: true,
neverNull: false,
showErrorsOnly: false,
skip: false
}
class _Unit {
/**
* @param {object} params
* @param {TestOptions} [params.options] default options to apply to all sections
* @return {Unit}
*/
constructor(options = {}) {
}
get defaultCompare () {
}
/**
* start a section of tests
* @param {function} test a function with all the tests
* @param {TestOptions} [options] default options for this section
* @return {UnitResult[]} tests that have failed so far in this section
*/
section(test, options = {}) {
}
/**
* get the section currently being processed
* @return {UnitSection}
*/
get currentSection() {
}
/**
* do a test - succes is when compare is true
* @param {*} expect the expected value
* @param {*} actual the actual value
* @param {TestOptions} options
* @return UnitResult
*/
is(expect, actual, options) {
}
/**
* do a test - succes is when compare is false
* @param {*} expect the expected value
* @param {*} actual the actual value
* @param {TestOptions} options
* @return UnitResult
*/
not(expect, actual, options) {
}
/**
* @param {UnitResult} result the unit result to get the description of
* @return {string} the decorated description
*/
getTestDescription(result) {
}
/**
*
* @param {UnitResult} result the unit result to decorate
* @return {string} the decorated result
*/
getTestResult(result) {
}
/**
* log the test
* @param {UnitResult} result the unit result to decorate
* @return {string} the decorated result
*/
reportTest(result) {
}
/**
* all the tests passed
* @return {Boolean} whether all was good
*/
isGood() {
}
/**
* all the tests passed in a section
* @param {UnitSection} section
* @return {Boolean} whether all was good
*/
isSectionGood(section) {
}
/**
* get the total number of tests that were errors
* return {number}
*/
get totalErrors() {
}
/**
* get the total number of tests that were successes
* return {number}
*/
get totalPasses() {
}
/**
* get the total number of sections that contain errors
* @param {UnitSection} section
* return {number}
*/
sectionErrors(section) {
}
/**
* get the total number of sections that contain no errors
* @param {UnitSection} section
* return {number}
*/
sectionPasses(section) {
}
/**
* complete summay report of all the tests
* @return {boolean} if true then there's no errors
*/
report() {
}
}
// export class
var Unit = _Unit
class skeleton
Links
library bmUnitTest
IDE
library ID 1zOlHMOpO89vqLPe5XpC-wzA9r5yaBkWt_qFjKqFNsIZtNJ-iUjBYDt-x
github