test-established-expectations
Snapshot testing in chai using json files without automatic file population. Meaning, the first time you run the tests, they automatically populate the snapshots.
Note that because JSON values are compared, some inputs may be parsed unexpectedly. For example, Map
objects will simply get stringified as {}
.
Currently requires Mocha.
Usage
Installation
npm i -D test-established-expectations
You most likely want this a dev dependency (since it's meant for testing), hence the -D
.
assertExpectedOutput
The most basic usage is with assertExpectedOutput
. It accepts a function, calls it, and compares its output to the previously stored output:
import {describe, it} from 'mocha';
import {assertExpectedOutput} from 'test-established-expectations';
function myFunctionToTest() {
return 'dummy function';
}
describe(myFunctionToTest.name, () => {
it('should match expected output', async () => {
await assertExpectedOutput(myFunctionToTest, {
key: {
subKey: 'basic expectation',
},
});
});
});
assertExpectation
assertExpectation
is a more versatile alternative, as it doesn't rely on a function being input. For assertExpectation
to work, you must already have the result
or output that you need to compare.
import {describe, it} from 'mocha';
import {assertExpectation} from 'test-established-expectations';
function myFunctionToTest() {
return 'dummy function';
}
describe(myFunctionToTest.name, () => {
it('should match expected output with function as key', async () => {
const result = myFunctionToTest();
await assertExpectation({
key: {
topKey: {function: myFunctionToTest},
subKey: 'basic expectation with function key',
},
result,
});
});
});
expectationCases
Use expectationCases
to quickly run multiple sets of expectation tests for a single function:
import {expectationCases} from 'test-established-expectations';
function myFunctionToTest(input1: string, input2: number) {
return `${input1}-${input2}`;
}
describe(myFunctionToTest.name, () => {
expectationCases(myFunctionToTest, [
{
it: 'should combine inputs',
inputs: [
'first input',
2,
],
},
{
it: 'should combine different inputs',
inputs: [
'one',
22,
],
},
]);
// optionally pass an options parameter as the second parameter
expectationCases(
myFunctionToTest,
{
// if the given function to test is anonymous, this testKey must be provided
testKey: 'topKey',
cwd: 'my/path',
expectationFile: 'my-expectation-file.json',
},
[
{
it: 'should combine different inputs with options',
inputs: [
'more',
-1,
],
},
],
);
});
Other top keys
Other top key options that match common testing methods: {describe: 'my test key'}
, {context: 'my test key'}
:
import {describe, it} from 'mocha';
import {assertExpectation} from 'test-established-expectations';
function myFunctionToTest() {
return 'dummy function';
}
describe(myFunctionToTest.name, () => {
it('should match expected output', async () => {
const result = myFunctionToTest();
await assertExpectation({
key: {
// the topKey here extracts the function name manually
topKey: {describe: myFunctionToTest.name},
subKey: 'basic expectation',
},
result,
});
});
});
You can also just use a string for ultimate flexibility:
import {describe, it} from 'mocha';
import {assertExpectation} from 'test-established-expectations';
function myFunctionToTest() {
return 'dummy function';
}
describe(myFunctionToTest.name, () => {
it('should match expected output', async () => {
const result = myFunctionToTest();
await assertExpectation({
key: {
// the topKey here is a string
topKey: 'my test',
subKey: 'basic expectation',
},
result,
});
});
});
Keys
topKey
and subKey
are used to store the expected outputs in a nested JSON file object structure. This way, it's easy to mirror a test file's describe
, it
structure (describe for the topKey
, it for the subKey
).
Expectation file
A custom expectation file can be chosen with expectationFile
:
import {describe, it} from 'mocha';
import {assertExpectedOutput} from 'test-established-expectations';
function myFunctionToTest() {
return 'dummy function';
}
describe(myFunctionToTest.name, () => {
it('should match expected output', async () => {
await assertExpectedOutput(myFunctionToTest, {
key: {
subKey: 'basic expectation',
},
// use a custom json file to store expectations
expectationFile: 'my-json-file.json',
});
});
});
Prevent overwriting stored values
By default, these assertions overwrite the expectations file with the latest results. This makes it easy to compare failures and to generate initial expectations. If you wish to disable this feature, set noOverwriteWhenDifferent
to true
:
import {describe, it} from 'mocha';
import {assertExpectedOutput} from 'test-established-expectations';
function myFunctionToTest() {
return 'dummy function';
}
describe(myFunctionToTest.name, () => {
it('should match expected output', async () => {
await assertExpectedOutput(myFunctionToTest, {
key: {
subKey: 'basic expectation',
},
// prevent overwriting the stored expectations when this expectation fails
noOverwriteWhenDifferent: true,
});
});
});