Strapi plugin creates a Vitest unit testing harness, that can be used to test Strapi apps and standalone plugins. It loads Strapi as a singleton that can be used by multiple test files. You don't have to require your tests from the `app.test.js` file, each test file is independent of others. It can be also used in watch mode.
Strapi plugin creates a Vitest unit testing harness, that can be used to test Strapi apps and standalone plugins. It loads Strapi as a singleton that can be used by multiple independent test files. It can also be used in watch mode.
Plugin still < v1.0.0, implementations may change.
This plugin provides a Vitest testing harness to enable easier testing with Strapi. The major advantage here is that Vitest uses Vite and therefore takes advantage of modern js that includes running ESM or TS without any transpilation. Read about Vitest & Vite to learn more. Vitest works with Jest and Chai assertions and is very, very fast with little simple config needed to use it.
The way this harness is made allows for Strapi to run a singleton that can be used by various test files without reloading it each time
for each file; it loads Strapi once, and you just write tests that work in independent test files without appending them to app.test.js
.
In addition to testing Strapi applications, it can also be used to test standalone plugins. It has a mini-strapi app that is exposed when you install and initialize it into a plugin project. The mini-app is started and has the root package (plugin) installed by default. You can then customize the mini-app tests/helpers/harness/test-app
for anything required by the plugin.
pnpm add -D strapi-plugin-vitest
Use your preferred package manager yarn/pnpm/npm
where pnpm
is mentioned.
To initialize the harness, you need to run pnpm vitest-init
This command is meant to be run once to expose the testing harness. However, you can run it any time to get the fresh/updated harness, and it will overwrite any existing harness files (VCS is essential here). You can freely edit these files if you wish to customize the harness or add new features through extensions and plugins. You can migrate your previous customizations through VCS diffs if you so run this command on existing customizations.
The initialization script:
test/helpers
directory (ones that it ships with).
This Test harness has added plugins: expect-more-jest, jest-extended, sinon-chai.env.test
file to extend the .env
file if available. This means you can fine-tune any existing environments for testing purposes. I use it to turn on or off certain plugins during testing, for example.app.test.ts
or plugin.test.ts
example file (respective if it is installed in a Strapi app/plugin) vitest.config.js
vitest configuration fileconfig/env/test/database.(js|ts)
file if missingpackage.json
assist with initialization, usage and other chores (please review them for correctness):vitest:w
- executes script to run vitest in watch mode (custom watcher)vitest:clean
- executes script to clean test application build artifacts (only available when testing standalone plugins)vitest:build
- executes script to build test application though not necessary, happens automatically when you run any of the following scripts (only available when testing standalone plugins)vitest:develop
- executes script to run the test application in develop mode (only available when testing standalone plugins)vitest:start
- executes script to run the test application in start mode (only available when testing standalone plugins)vitest:console
- executes script to run the test application in console mode (only available when testing standalone plugins)vitest:diag
- executes script to run your application or the test-app application (when testing standalone plugins) in start mode, but in a test environment to allow you to diagnose problems. See troubleshooting for more information.vitest:dev-deps
- executes script to install required dev-dependencies, just run it after every init. You can edit or remove this script once you are done with it.vitest:deps
- same as above but for dependencies (will only update any packages you moved to dependencies if applicable)tsconfig.config
ModificationsCreate or add the following into tsconfig.json
:
1
2
3
4
5
6
7
8
9
{
"compilerOptions": {
"types": [
"@strapi/strapi",
"vitest/globals",
"./schemas"
]
}
}
plugins.js|ts
ConfigurationEnable the plugin in your test plugins' configuration - for applications testing only.
This plugin also cleans the DB based on configuration during tests startup/destroy.
1
2
3
4
5
6
7
8
9
module.exports = {
vitest: {
enabled: true,
config: {
cleanDBAtRegister: Boolean, // use either to clean DB before or after strapi server register and destroy
cleanDBAtDestroy: Boolean,
}
}
}
To run tests do the following:
pnpm vitest
This will run all tests in the tests directory, according to the vitest.config.js configuration. See Vitest for more information about running tests, arguments and options.
If the package under test is a standalone Strapi plugin, then this will build the test-app
on each run. On the first run, the harness will create a default super admin: superadmin@test.co.zw
with password: Password123
. You can use this to login to the admin backend if you run the console, develop or start scripts. See below.
As mentioned before, this harness allows you to run tests files independent of the app.test.js
file, you can even delete this file, it's just there as a sample; unlike as documented by Strapi. (Strapi Team is free to add this package to Strapi Documentation or to Strapi suite of packages). Meaning you can run a file directly, without worrying
of how the singleton will mount. Everything will be done by this harness, making it easier and standard to test Strapi
code. For example, you can run specific test that match title = # validate my-service
, without running other tests:
pnpm test -t "my-service"
Read Vitest filtering documentation for more information on tests filtering.
See example test file app.test.ts
/plugin.test.ts
, you can generate other similar test files and just run them as usual, without adding them to any main test file or worry about special treatment for test code.
pnpm vitest:dev-deps
and pnpm vitest:deps
(if available), you can remove the scripts once you are done with them.Sometimes it may not be clear why the harness is failing to start. To see why startup is failing, if no real followable error is showing:
pnpm vitest:diag
which runs NODE_ENV=test pnpm strapi start
when strapi-plugin-vitest
is used to test an application, or NODE_ENV=test pnpm vitest:start
when testing a standalone plugineither commands (for applications or plugins) will run Strapi as usual, but within a test environment. Any errors being swallowed up by test suite will be thrown.
For some reason the vitest watcher is not working with Strapi. Therefore, I devised a watcher to use with this plugin.
vitest-watch
or vitest:w
to run under watch mode. Pass other Vitest arguments as required.vitest-init
& vitest:deps
/vitest:dev-deps
required^0.23.4
from ^0.22.1
: manually change the version in your package.json after review because it introduces a few breaking changes, but fixes, adds features and improvements. See vitest releasesimport { ... } from 'strapi-plugin-vitest'
, most of them were adopted from strapi tests/helpers etc. Since this is ts, most of the utils will give you info you need to use them.vitest-init
to get the latest version of the harness. You don't have to back up any files, it'll be done for you.vitest-init
to get the latest version of the harness. Before you do, rename vitest-config.js
to vitest-config.bck.js
, if you have any changes, move them into the new vitest-config.js
.tests/helpers/harness
from tests/helpers
. If you have any customizations in the old harness files, then you have to manually move any customizations into the new files before you delete the old files.Emmanuel Mahuni
MIT
npm install strapi-plugin-vitest
Check out the available plugin resources that will help you to develop your plugin or provider and get it listed on the marketplace.