ag-error-jest
Provides jest matchers to simplify testing of subclasses of AgErrors from the ag-error package. See the ag-error readme for more detail about AgErrors themselves.
Installation
With npm:
npm install --save-dev @australiangreens/ag-error-jest
With yarn:
yarn add --dev @australiangreens/ag-error-jest
Setup
Making use of the package once installs works in the same way as
jest-extended, relying on
side-effects. Add ag-error-jest
to your jest setupFilesAfterEnv
configuration property. See the jest
docs for details
For example in jest.config.js
:
export default {
//...
"setupFilesAfterEnv": ["@australiangreens/ag-error-jest"],
//...
}
Alternatively if you already have a ./src/setupTests.ts
in your
setupFilesAfterEnv
, then you and add an import into that intead:
import '@australiangreens/ag-error-test';
Usage
So your test files for each error only needs to be something like:
import { BoilerplateError } from './BoilerplateError';
test('BoilerplateError meets requirements to be a valid AgError', () => {
expect(BoilerplateError).toBeValidAgErrorClass(
'BoilerplateError',
'AgError:BoilerplateError',
);
});
Caveat: Different constructor signature
If you add extra arguments to the constructor, the toBeValidAgErrorClass()
matcher may not work. In this case you should should be able to use
toBeValidAgErrorObject()
which checks the first two requirements, but will
need to manually test the first.
The following example shows a test for a special CiviApiAxiosError error that is a wrapper for axios related errors.
import { CiviApiAxiosError } from './CiviApiAxiosError';
import { createAxiosError } from '../../../utils/testing';
test('CiviApiAxiosError meets requirements to be a valid AgError', () => {
const err = new CiviApiAxiosError('some message', createAxiosError('Network Error', {}, null, {}, null));
expect(err).toBeValidAgErrorObject('CiviApiAxiosError', 'AgError:BoilerplateError:CiviApiError:CiviApiAxiosError');
// This is the bit we have to do manually.
// Not a normal sort of test, but basically want to ensure the way we've done
// this doesn't actually end up using the class name even if minified. We can
// (sort of) emulate this by deliberately breaking our own rules using a name
// that does not match the class to make sure the correct one is being used.
class DummySubClass extends CiviApiAxiosError {
static errorName = 'NotTheSame';
}
const dummy = new DummySubClass('some message', createAxiosError('Network Error', {}, null, {}, null));
expect(dummy.name).not.toEqual(dummy.constructor.name);
});
About the build process
Originally the plan was to only compile with ESM as the target, since that is what we are using across all our apps. However due to Jest not yet properly handling ESM, we need to provide the commonjs files too.
To achive this, we use the hybrid module pattern described here: https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html
We make a few changes however:
- For the directory in dist we use "esm" instead of "mjs"
- Rather than using a separate
tsconfig-base.json
, justtsconfig.json
contain the ESM definition and havetsconfig-cjs.son
extend and override it. - In
tsconfig-cjs.json
, adddeclaration": false
.
The reasoning for last point is that we don't need the declaration files in both places; they are basically just for editor hinting. the handbook states "The .d.ts syntax intentionally looks like ES Modules syntax", so it makes more sense to put the declarations in the esm directory.