This project contains a minimal set of configuration necessary to be able to write unit / integration tests using the Jest testing framework coupled with the amazing miniflare, which provides KV, R2, Durable Objects, etc.. for running cloudflare services locally. This project leverage the typescript compiler (tsc) to create the compiled code necessary for testing.
This example explicitly includes one other library for testing, the uuid library. Due to how this package, and many others get consumed, this is a great litmus test to ensure the testing framework functions properly. There is also a simple math test built into the test suite, just to make sure that if that breaks something is really messed up with the test configuration.
If you are looking for more examples, perhaps with utilizing esbuild, you can take a look at this repo. The minimum requirements do not actually require the use of esbuild or babel or anything like that.
There are tidbits of knowledge scattered throughout the different config files and tests, so it is suggested to take a look through all the files.
To get started just do the normal npm install and stuff like that and you should be able to run npm run test and be ready to start testing.
You may notice, and this is important, that Jest is pegged to 27.x. This is because there is an issue somewhere in the dependency chain where 28.x and jest-environment-miniflare don't play nicely together.
The important details to understand abou tthis example environment are as follows:
- NAMESPACES
- Bindings
- Configuration to support 1 and 2.
In this example you will see I created a namespace called MYSTORE. Any namespace your code references will need to be defined for the test framework to make it available.
The bindings.d.ts in the test folder exists to provide typescript a reference for type checking. So make sure MYSTORE and any other namespaces you need are defined.
The configuration that drives the Jest framework is jest.config.js (in this case). Given that this is a typescript project you may want to keep your codebase clean and use jest.config.ts. But until the bug is fixed which would allow Jest to use that, don't do it. I have shared an example file here named jest.config.ts.txt with an example of the type of problems you may experience if you try to use the latest Jest version. I'm sure at some point this will be resolved, but until then, what is here works.
You will notice that in the jest.config.js file there is a reference to MYSTORE within the kvNamespaces options. This is what miniflare will use to create the actual binding for your KV store to test your code.
In db.test.ts there is a reference to getMiniflareBindings(). Interestingly in the config you will find testEnvironment: "miniflare". This is what brings the actual miniflare global binding into the test suite for use by your tests.
There is a bindings.d.ts and global.d.ts files in the test folder. This provides compile time support for the method getMiniflareBindings() that is provided by jest-environment-miniflare library. The location of these files are properly configured in this repo for their current location. If you want them to live somewhere else, make sure you modify their reference paths accordingly in the test/tsconfig.json file.
A big thanks to cloudflare and the great community therein to help me learn and understand enough to share back with the community.
Lastly, if you have suggestions on educationl information that can / should be added to this project, please send a pull request.