diff --git a/docusaurus/docs/cms/testing.md b/docusaurus/docs/cms/testing.md
index 03f396eb29..4e8da16ebf 100644
--- a/docusaurus/docs/cms/testing.md
+++ b/docusaurus/docs/cms/testing.md
@@ -1,145 +1,679 @@
---
title: Testing
displayed_sidebar: cmsSidebar
-description: Learn how to test your Strapi application.
+description: Learn how to test your Strapi application with Jest and Supertest.
tags:
-- auth endpoint controller
-- environment
+ - testing
+ - jest
+ - supertest
+ - unit testing
+ - API testing
---
-# Unit testing
+# Unit and integration testing guide
-Testing uses Jest and Supertest with a temporary SQLite database to run unit and API checks. Walkthroughs generate a Strapi instance, verify endpoints like `/hello`, and authenticate users to ensure controllers behave as expected.
+Testing relies on Jest and Supertest with an in-memory SQLite database, a patched Strapi test harness that also supports TypeScript configuration files, and helpers that automatically register the `/hello` route and authenticated role during setup.
-:::strapi
-The Strapi blog has a tutorial on how to implement and .
-:::
-
-In this guide we will see how you can run basic unit tests for a Strapi application using a testing framework.
+The present guide provides a hands-on approach to configuring in a Strapi 5 application, mocking the Strapi object for unit testing plugin code, and using to test REST endpoints end to end.
-In this example we will use Testing Framework with a focus on simplicity and
- Super-agent driven library for testing node.js HTTP servers using a fluent API.
+The guide aims to recreate the minimal test suite available in the CodeSandbox link.
:::caution
-Please note that this guide will not work if you are on Windows using the SQLite database due to how windows locks the SQLite file.
+The present guide will not work if you are on Windows using the SQLite database due to how Windows locks the SQLite file.
:::
-## Install test tools
+## Install tools
-`Jest` contains a set of guidelines or rules used for creating and designing test cases - a combination of practices and tools that are designed to help testers test more efficiently.
+We'll first install test tools, add a command to run our tests, and configure Jest.
-`Supertest` allows you to test all the `api` routes as they were instances of .
+1. Install Jest and Supertest by running the following command in a terminal:
-`sqlite3` is used to create an on-disk database that is created and deleted between tests.
+
-
+
-
+ ```bash
+ yarn add jest supertest --dev
+ ```
-```bash
-yarn add --dev jest supertest sqlite3
-```
+
-
+
-
+ ```bash
+ npm install jest supertest --save-dev
+ ```
-```bash
-npm install jest supertest sqlite3 --save-dev
-```
+
+
+
+
+ * `Jest` provides the test runner and assertion utilities.
+ * `Supertest` allows you to test all the `api` routes as they were instances of .
+
+2. Update the `package.json` file of your Strapi project with the following:
+
+ * Add a `test` command to the `scripts` section so it looks as follows:
+
+ ```json {12}
+ "scripts": {
+ "build": "strapi build",
+ "console": "strapi console",
+ "deploy": "strapi deploy",
+ "dev": "strapi develop",
+ "develop": "strapi develop",
+ "seed:example": "node ./scripts/seed.js",
+ "start": "strapi start",
+ "strapi": "strapi",
+ "upgrade": "npx @strapi/upgrade latest",
+ "upgrade:dry": "npx @strapi/upgrade latest --dry",
+ "test": "jest --forceExit --detectOpenHandles"
+ },
+ ```
+
+ * Configure Jest at the bottom of the file to ignore Strapi build artifacts and to map any root-level modules you import from tests:
+
+ ```json
+ "jest": {
+ "testPathIgnorePatterns": [
+ "/node_modules/",
+ ".tmp",
+ ".cache"
+ ],
+ "testEnvironment": "node",
+ "moduleNameMapper": {
+ "^/create-service$": "/create-service"
+ }
+ }
+ ```
+
+## Mock Strapi for plugin unit tests
-
+Pure unit tests are ideal for Strapi plugins because they let you validate controller and service logic without starting a Strapi server. Use Jest's **mocking** Mocking is a testing technique where you create fake versions of parts of your application (like services or database calls) to test code in isolation. Instead of connecting to a real database or calling actual services, the mock returns predefined responses, making tests faster and more predictable. utilities to recreate just the parts of the Strapi object and any request context that your code relies on.
-
+### Controller example
-Once this is done add this to `package.json` file
+Create a test file such as `./tests/todo-controller.test.js` that instantiates your controller with a mocked Strapi object and verifies every call the controller performs:
-add `test` command to `scripts` section
+```js title="./tests/todo-controller.test.js"
+const todoController = require('./todo-controller');
-```json
- "scripts": {
- "develop": "strapi develop",
- "start": "strapi start",
- "build": "strapi build",
- "strapi": "strapi",
- "test": "jest --forceExit --detectOpenHandles"
- },
+describe('Todo controller', () => {
+ let strapi;
+
+ beforeEach(() => {
+ strapi = {
+ plugin: jest.fn().mockReturnValue({
+ service: jest.fn().mockReturnValue({
+ create: jest.fn().mockReturnValue({
+ data: {
+ name: 'test',
+ status: false,
+ },
+ }),
+ complete: jest.fn().mockReturnValue({
+ data: {
+ id: 1,
+ status: true,
+ },
+ }),
+ }),
+ }),
+ };
+ });
+
+ it('creates a todo item', async () => {
+ const ctx = {
+ request: {
+ body: {
+ name: 'test',
+ },
+ },
+ body: null,
+ };
+
+ await todoController({ strapi }).index(ctx);
+
+ expect(ctx.body).toBe('created');
+ expect(strapi.plugin('todo').service('create').create).toHaveBeenCalledTimes(1);
+ });
+
+ it('completes a todo item', async () => {
+ const ctx = {
+ request: {
+ body: {
+ id: 1,
+ },
+ },
+ body: null,
+ };
+
+ await todoController({ strapi }).complete(ctx);
+
+ expect(ctx.body).toBe('todo completed');
+ expect(strapi.plugin('todo').service('complete').complete).toHaveBeenCalledTimes(1);
+ });
+});
```
-and add those lines at the bottom of file
+The `beforeEach` hook rebuilds the mock so every test starts with a clean Strapi instance. Each test prepares the `ctx` request object that the controller expects, calls the controller function, and asserts both the response and the interactions with Strapi services.
-```json
- "jest": {
- "testPathIgnorePatterns": [
- "/node_modules/",
- ".tmp",
- ".cache"
- ],
- "testEnvironment": "node"
- }
+### Service example
+
+Services can be tested in the same test suite or in a dedicated file by mocking only the Strapi query layer they call into.
+
+```js title="./tests/create-service.test.js"
+const createService = require('./create-service');
+
+describe('Create service', () => {
+ let strapi;
+
+ beforeEach(() => {
+ strapi = {
+ query: jest.fn().mockReturnValue({
+ create: jest.fn().mockReturnValue({
+ data: {
+ name: 'test',
+ status: false,
+ },
+ }),
+ }),
+ };
+ });
+
+ it('persists a todo item', async () => {
+ const todo = await createService({ strapi }).create({ name: 'test' });
+
+ expect(strapi.query('plugin::todo.todo').create).toHaveBeenCalledTimes(1);
+ expect(todo.data.name).toBe('test');
+ });
+});
```
-Those will inform `Jest` not to look for test inside the folder where it shouldn't.
+By focusing on mocking the specific Strapi APIs your code touches, you can grow these tests to cover additional branches, error cases, and services while keeping them fast and isolated.
## Set up a testing environment
-Test framework must have a clean empty environment to perform valid test and also not to interfere with current database.
+For API-level testing with , the framework must have a clean empty environment to perform valid tests and also not to interfere with your development database.
-Once `jest` is running it uses the `test` [environment](/cms/configurations/environment) (switching `NODE_ENV` to `test`)
-so we need to create a special environment setting for this purpose.
-Create a new config for test env `./config/env/test/database.js` and add the following value `"filename": ".tmp/test.db"` - the reason of that is that we want to have a separate sqlite database for tests, so our test will not touch real data.
-This file will be temporary, each time test is finished, we will remove that file that every time tests are run on the clean database.
-The whole file will look like this:
+Once `jest` is running it uses the `test` [environment](/cms/configurations/environment), so create `./config/env/test/database.js` with the following:
-```js title="path: ./config/env/test/database.js"
+```js title="./config/env/test/database.js"
+module.exports = ({ env }) => {
+ const filename = env('DATABASE_FILENAME', '.tmp/test.db');
+ const rawClient = env('DATABASE_CLIENT', 'sqlite');
+ const client = ['sqlite3', 'better-sqlite3'].includes(rawClient) ? 'sqlite' : rawClient;
-module.exports = ({ env }) => ({
- connection: {
- client: 'sqlite',
+ return {
connection: {
- filename: env('DATABASE_FILENAME', '.tmp/test.db'),
+ client,
+ connection: {
+ filename,
+ },
+ useNullAsDefault: true,
},
- useNullAsDefault: true,
- debug: false
- },
-});
+ };
+};
```
-## Create a Strapi instance
+This configuration mirrors the defaults used in production but converts `better-sqlite3` to the `sqlite` client Strapi expects.
+
+## Create the Strapi test harness
+
+We will create a `tests` folder in your project root and add the example files below. These 3 files work together to create a complete testing infrastructure:
+
+* `ts-compiler-options.js` defines how TypeScript files should be compiled for testing
+* `ts-runtime.js` enables Jest to understand and execute TypeScript files on the fly
+* `strapi.js` is the main **test harness** A test harness is a collection of software and test data configured to test an application by running it in predefined conditions and monitoring its behavior.
In the present case, our test harness sets up a complete Strapi instance in an isolated testing environment, handles TypeScript files, and provides utilities to make testing easier. that sets up and tears down Strapi instances for tests
+
+### TypeScript compiler configuration
+
+Create `tests/ts-compiler-options.js` with the following content:
+
+```js title="./tests/ts-compiler-options.js"
+const fs = require('fs');
+const path = require('path');
+const ts = require('typescript');
+
+const projectRoot = path.resolve(__dirname, '..');
+const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+
+const baseCompilerOptions = {
+ module: ts.ModuleKind.CommonJS,
+ target: ts.ScriptTarget.ES2019,
+ moduleResolution: ts.ModuleResolutionKind.NodeJs,
+ esModuleInterop: true,
+ jsx: ts.JsxEmit.React,
+};
+
+const loadCompilerOptions = () => {
+ let options = { ...baseCompilerOptions };
+
+ if (!fs.existsSync(tsconfigPath)) {
+ return options;
+ }
+
+ try {
+ const tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');
+ const parsed = ts.parseConfigFileTextToJson(tsconfigPath, tsconfigContent);
+
+ if (!parsed.error && parsed.config && parsed.config.compilerOptions) {
+ options = {
+ ...options,
+ ...parsed.config.compilerOptions,
+ };
+ }
+ } catch (error) {
+ // Ignore tsconfig parsing errors and fallback to defaults
+ }
+
+ return options;
+};
+
+module.exports = {
+ compilerOptions: loadCompilerOptions(),
+ loadCompilerOptions,
+};
+```
+
+This file loads your project's TypeScript configuration and provides sensible defaults if the config file doesn't exist.
+
+### TypeScript runtime loader
+
+Create `tests/ts-runtime.js` with the following content:
+
+```js title="./tests/ts-runtime.js"
+const Module = require('module');
+const { compilerOptions } = require('./ts-compiler-options');
+const fs = require('fs');
+const ts = require('typescript');
+
+const extensions = Module._extensions;
+
+if (!extensions['.ts']) {
+ extensions['.ts'] = function compileTS(module, filename) {
+ const source = fs.readFileSync(filename, 'utf8');
+ const output = ts.transpileModule(source, {
+ compilerOptions,
+ fileName: filename,
+ reportDiagnostics: false,
+ });
+
+ return module._compile(output.outputText, filename);
+ };
+}
+
+if (!extensions['.tsx']) {
+ extensions['.tsx'] = extensions['.ts'];
+}
+
+module.exports = {
+ compilerOptions,
+};
+```
+
+This file teaches Node.js how to load `.ts` and `.tsx` files by transpiling them to JavaScript on the fly.
+
+### Main test harness
+
+Create `tests/strapi.js` with the following content:
+
+
+
+```js title="./tests/strapi.js"
+try {
+ require('ts-node/register/transpile-only');
+} catch (err) {
+ try {
+ require('@strapi/typescript-utils/register');
+ } catch (strapiRegisterError) {
+ require('./ts-runtime');
+ }
+}
+
+const fs = require('fs');
+const path = require('path');
+const Module = require('module');
+const ts = require('typescript');
+const databaseConnection = require('@strapi/database/dist/connection.js');
+const knexFactory = require('knex');
+const strapiCoreRoot = path.dirname(require.resolve('@strapi/core/package.json'));
+const loadConfigFilePath = path.join(strapiCoreRoot, 'dist', 'utils', 'load-config-file.js');
+const loadConfigFileModule = require(loadConfigFilePath);
+const { compilerOptions: baseCompilerOptions } = require('./ts-compiler-options');
+
+// ============================================
+// 1. PATCH: TypeScript Configuration Loader
+// ============================================
+// This section patches Strapi's configuration loader to support TypeScript config files
+// (.ts, .cts, .mts). Without this, Strapi would only load .js and .json config files.
+
+if (!loadConfigFileModule.loadConfigFile.__tsRuntimePatched) {
+ const strapiUtils = require('@strapi/utils');
+ const originalLoadConfigFile = loadConfigFileModule.loadConfigFile;
+
+ const loadTypeScriptConfig = (file) => {
+ const source = fs.readFileSync(file, 'utf8');
+ const options = {
+ ...baseCompilerOptions,
+ module: ts.ModuleKind.CommonJS,
+ };
+
+ const output = ts.transpileModule(source, {
+ compilerOptions: options,
+ fileName: file,
+ reportDiagnostics: false,
+ });
+
+ const moduleInstance = new Module(file);
+ moduleInstance.filename = file;
+ moduleInstance.paths = Module._nodeModulePaths(path.dirname(file));
+ moduleInstance._compile(output.outputText, file);
+
+ const exported = moduleInstance.exports;
+ const resolved = exported && exported.__esModule ? exported.default : exported;
+
+ if (typeof resolved === 'function') {
+ return resolved({ env: strapiUtils.env });
+ }
+
+ return resolved;
+ };
+
+ const patchedLoadConfigFile = (file) => {
+ const extension = path.extname(file).toLowerCase();
+
+ if (extension === '.ts' || extension === '.cts' || extension === '.mts') {
+ return loadTypeScriptConfig(file);
+ }
+
+ return originalLoadConfigFile(file);
+ };
+
+ patchedLoadConfigFile.__tsRuntimePatched = true;
+ loadConfigFileModule.loadConfigFile = patchedLoadConfigFile;
+ require.cache[loadConfigFilePath].exports = loadConfigFileModule;
+}
+
+// ============================================
+// 2. PATCH: Configuration Directory Scanner
+// ============================================
+// This section patches how Strapi scans the config directory to:
+// - Support TypeScript extensions (.ts, .cts, .mts)
+// - Validate config file names
+// - Prevent loading of restricted filenames
+
+const configLoaderPath = path.join(strapiCoreRoot, 'dist', 'configuration', 'config-loader.js');
+const originalLoadConfigDir = require(configLoaderPath);
+const validExtensions = ['.js', '.json', '.ts', '.cts', '.mts'];
+const mistakenFilenames = {
+ middleware: 'middlewares',
+ plugin: 'plugins',
+};
+const restrictedFilenames = [
+ 'uuid',
+ 'hosting',
+ 'license',
+ 'enforce',
+ 'disable',
+ 'enable',
+ 'telemetry',
+ 'strapi',
+ 'internal',
+ 'launchedAt',
+ 'serveAdminPanel',
+ 'autoReload',
+ 'environment',
+ 'packageJsonStrapi',
+ 'info',
+ 'dirs',
+ ...Object.keys(mistakenFilenames),
+];
+const strapiConfigFilenames = ['admin', 'server', 'api', 'database', 'middlewares', 'plugins', 'features'];
+
+if (!originalLoadConfigDir.__tsRuntimePatched) {
+ const patchedLoadConfigDir = (dir) => {
+ if (!fs.existsSync(dir)) {
+ return {};
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+ const seenFilenames = new Set();
+
+ const configFiles = entries.reduce((acc, entry) => {
+ if (!entry.isFile()) {
+ return acc;
+ }
+
+ const extension = path.extname(entry.name);
+ const extensionLower = extension.toLowerCase();
+ const baseName = path.basename(entry.name, extension);
+ const baseNameLower = baseName.toLowerCase();
+
+ if (!validExtensions.includes(extensionLower)) {
+ console.warn(`Config file not loaded, extension must be one of ${validExtensions.join(',')}): ${entry.name}`);
+ return acc;
+ }
+
+ if (restrictedFilenames.includes(baseNameLower)) {
+ console.warn(`Config file not loaded, restricted filename: ${entry.name}`);
+ if (baseNameLower in mistakenFilenames) {
+ console.log(`Did you mean ${mistakenFilenames[baseNameLower]}?`);
+ }
+ return acc;
+ }
+
+ const restrictedPrefix = [...restrictedFilenames, ...strapiConfigFilenames].find(
+ (restrictedName) => restrictedName.startsWith(baseNameLower) && restrictedName !== baseNameLower
+ );
+
+ if (restrictedPrefix) {
+ console.warn(`Config file not loaded, filename cannot start with ${restrictedPrefix}: ${entry.name}`);
+ return acc;
+ }
+
+ if (seenFilenames.has(baseNameLower)) {
+ console.warn(`Config file not loaded, case-insensitive name matches other config file: ${entry.name}`);
+ return acc;
+ }
+
+ seenFilenames.add(baseNameLower);
+ acc.push(entry);
+ return acc;
+ }, []);
+
+ return configFiles.reduce((acc, entry) => {
+ const extension = path.extname(entry.name);
+ const key = path.basename(entry.name, extension);
+ const filePath = path.resolve(dir, entry.name);
+
+ acc[key] = loadConfigFileModule.loadConfigFile(filePath);
+ return acc;
+ }, {});
+ };
+
+ patchedLoadConfigDir.__tsRuntimePatched = true;
+ require.cache[configLoaderPath].exports = patchedLoadConfigDir;
+}
+
+// ============================================
+// 3. PATCH: Database Connection Handler
+// ============================================
+// This section normalizes database client names for testing.
+// Maps Strapi's client names (sqlite, mysql, postgres) to actual driver names
+// (sqlite3, mysql2, pg) and handles connection pooling.
+
+databaseConnection.createConnection = (() => {
+ const clientMap = {
+ sqlite: 'sqlite3',
+ mysql: 'mysql2',
+ postgres: 'pg',
+ };
+
+ return (userConfig, strapiConfig) => {
+ if (!clientMap[userConfig.client]) {
+ throw new Error(`Unsupported database client ${userConfig.client}`);
+ }
+
+ const knexConfig = {
+ ...userConfig,
+ client: clientMap[userConfig.client],
+ };
+
+ if (strapiConfig?.pool?.afterCreate) {
+ knexConfig.pool = knexConfig.pool || {};
+
+ const userAfterCreate = knexConfig.pool?.afterCreate;
+ const strapiAfterCreate = strapiConfig.pool.afterCreate;
+
+ knexConfig.pool.afterCreate = (conn, done) => {
+ strapiAfterCreate(conn, (err, nativeConn) => {
+ if (err) {
+ return done(err, nativeConn);
+ }
+
+ if (userAfterCreate) {
+ return userAfterCreate(nativeConn, done);
+ }
-In order to test anything we need to have a strapi instance that runs in the testing environment,
-basically we want to get instance of strapi app as object, similar like creating an instance for .
+ return done(null, nativeConn);
+ });
+ };
+ }
+
+ return knexFactory(knexConfig);
+ };
+})();
+
+// ============================================
+// 4. TEST ENVIRONMENT SETUP
+// ============================================
+// Configure Jest timeout and set required environment variables for testing
+
+if (typeof jest !== 'undefined' && typeof jest.setTimeout === 'function') {
+ jest.setTimeout(30000);
+}
+
+const { createStrapi } = require('@strapi/strapi');
+
+process.env.NODE_ENV = process.env.NODE_ENV || 'test';
+process.env.APP_KEYS = process.env.APP_KEYS || 'testKeyOne,testKeyTwo';
+process.env.API_TOKEN_SALT = process.env.API_TOKEN_SALT || 'test-api-token-salt';
+process.env.ADMIN_JWT_SECRET = process.env.ADMIN_JWT_SECRET || 'test-admin-jwt-secret';
+process.env.TRANSFER_TOKEN_SALT = process.env.TRANSFER_TOKEN_SALT || 'test-transfer-token-salt';
+process.env.ENCRYPTION_KEY = process.env.ENCRYPTION_KEY || '0123456789abcdef0123456789abcdef';
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'test-jwt-secret';
+process.env.DATABASE_CLIENT = process.env.DATABASE_CLIENT || 'sqlite';
+process.env.DATABASE_FILENAME = process.env.DATABASE_FILENAME || ':memory:';
+process.env.STRAPI_DISABLE_CRON = 'true';
+process.env.PORT = process.env.PORT || '0';
+
+const databaseClient = process.env.DATABASE_CLIENT || 'sqlite';
+const clientMap = {
+ sqlite: 'sqlite3',
+ 'better-sqlite3': 'sqlite3',
+ mysql: 'mysql2',
+ postgres: 'pg',
+};
-These tasks require adding some files - let's create a folder `tests` where all the tests will be put and inside it, next to folder `helpers` where main Strapi helper will be in file strapi.js.
+const driver = clientMap[databaseClient];
-```js title="path: ./tests/helpers/strapi.js"
-const Strapi = require("@strapi/strapi");
-const fs = require("fs");
+if (!driver) {
+ throw new Error(`Unsupported database client "${databaseClient}".`);
+}
+
+if (databaseClient === 'better-sqlite3') {
+ process.env.DATABASE_CLIENT = 'sqlite';
+}
+
+require(driver);
let instance;
+// ============================================
+// 5. STRAPI INSTANCE MANAGEMENT
+// ============================================
+// Functions to set up and tear down a Strapi instance for testing
+
async function setupStrapi() {
if (!instance) {
- await Strapi().load();
- instance = strapi;
+ instance = await createStrapi().load();
+
+ // Register the /api/hello test route automatically
+ const contentApi = instance.server?.api?.('content-api');
+ if (contentApi && !instance.__helloRouteRegistered) {
+ const createHelloService = require(path.join(
+ __dirname,
+ '..',
+ 'src',
+ 'api',
+ 'hello',
+ 'services',
+ 'hello'
+ ));
+ const helloService = createHelloService({ strapi: instance });
+
+ contentApi.routes([
+ {
+ method: 'GET',
+ path: '/hello',
+ handler: async (ctx) => {
+ ctx.body = await helloService.getMessage();
+ },
+ config: {
+ auth: false,
+ },
+ },
+ ]);
+
+ contentApi.mount(instance.server.router);
+ instance.__helloRouteRegistered = true;
+ }
- await instance.server.mount();
+ await instance.start();
+ global.strapi = instance;
+
+ // Patch the user service to automatically assign the authenticated role
+ const userService = strapi.plugins['users-permissions']?.services?.user;
+ if (userService) {
+ const originalAdd = userService.add.bind(userService);
+
+ userService.add = async (values) => {
+ const data = { ...values };
+
+ if (!data.role) {
+ const defaultRole = await strapi.db
+ .query('plugin::users-permissions.role')
+ .findOne({ where: { type: 'authenticated' } });
+
+ if (defaultRole) {
+ data.role = defaultRole.id;
+ }
+ }
+
+ return originalAdd(data);
+ };
+ }
}
return instance;
}
async function cleanupStrapi() {
- const dbSettings = strapi.config.get("database.connection");
+ if (!global.strapi) {
+ return;
+ }
- //close server to release the db-file
- await strapi.server.httpServer.close();
+ const dbSettings = strapi.config.get('database.connection');
- // close the connection to the database before deletion
+ await strapi.server.httpServer.close();
await strapi.db.connection.destroy();
- //delete test database after all tests have completed
+ if (typeof strapi.destroy === 'function') {
+ await strapi.destroy();
+ }
+
if (dbSettings && dbSettings.connection && dbSettings.connection.filename) {
const tmpDbFile = dbSettings.connection.filename;
if (fs.existsSync(tmpDbFile)) {
@@ -151,205 +685,230 @@ async function cleanupStrapi() {
module.exports = { setupStrapi, cleanupStrapi };
```
-## Test a Strapi instance
+
-We need a main entry file for our tests, one that will also test our helper file.
+What the test harness does:
-```js title="path: ./tests/app.test.js"
-const fs = require('fs');
-const { setupStrapi, cleanupStrapi } = require("./helpers/strapi");
+1. **TypeScript Support**: Patches Strapi's configuration loader to understand TypeScript files (`.ts`, `.cts`, `.mts`) in your config directory
+2. **Configuration Validation**: Ensures only valid config files are loaded and warns about common mistakes (like naming a file `middleware.js` instead of `middlewares.js`)
+3. **Database Normalization**: Maps database client names to their actual driver names (e.g., `sqlite` → `sqlite3`) and handles connection pooling
+4. **Environment Setup**: Sets all required environment variables for testing, including JWT secrets and database configuration
+5. **Automatic Route Registration**: Automatically registers a `/api/hello` test endpoint that you can use in your tests
+6. **User Permission Helper**: Patches the user service to automatically assign the "authenticated" role to newly created users, simplifying authentication tests
+7. **Cleanup**: Properly closes connections and removes temporary database files after tests complete
+
+Once these files are in place, the harness handles several Strapi 5 requirements automatically, letting you focus on writing actual test logic rather than configuration boilerplate.
+## Create smoke tests
+
+With the harness in place you can confirm Strapi boots correctly by adding a minimal Jest suite with the following **smoke tests** Smoke tests are basic tests that verify the most critical functionality works. The term comes from hardware testing: if you turn on a device and it doesn't catch fire (produce smoke), it passes the first test. In software, smoke tests check if the application starts correctly and basic features work before running more detailed tests. in a `tests/app.test.js` as follows:
+
+```js title="./tests/app.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+
+/** this code is called once before any test is called */
beforeAll(async () => {
- await setupStrapi();
+ await setupStrapi(); // Singleton so it can be called many times
});
+/** this code is called once before all the tests are finished */
afterAll(async () => {
await cleanupStrapi();
});
-it("strapi is defined", () => {
+it('strapi is defined', () => {
expect(strapi).toBeDefined();
});
+
+require('./hello');
+require('./user');
```
-Actually this is all we need for writing unit tests. Just run `yarn test` and see a result of your first test
+Running `yarn test` or `npm run test` should now yield:
```bash
-yarn run v1.13.0
-$ jest
- PASS tests/app.test.js
- ✓ strapi is defined (2 ms)
+PASS tests/create-service.test.js
+PASS tests/todo-controller.test.js
-Test Suites: 1 passed, 1 total
-Tests: 1 passed, 1 total
+Test Suites: 6 passed, 6 total
+Tests: 7 passed, 7 total
Snapshots: 0 total
-Time: 4.187 s
+Time: 7.952 s
Ran all test suites.
-✨ Done in 5.73s.
+✨ Done in 8.63s.
```
-:::tip
-If you receive a timeout error for Jest, please add the following line right before the `beforeAll` method in the `app.test.js` file: `jest.setTimeout(15000)` and adjust the milliseconds value as you need.
-:::
-
-## Test a basic endpoint controller
-
-:::tip
-In the example we'll use and example `Hello world` `/hello` endpoint from [controllers](/cms/backend-customization/controllers) section.
-
+:::caution
+If you receive a timeout error for Jest, increase the timeout by calling `jest.setTimeout(30000)` in `tests/strapi.js` or at the top of your test file.
:::
-Some might say that API tests are not unit but limited integration tests, regardless of nomenclature, let's continue with testing first endpoint.
+## Test a basic API endpoint
-We'll test if our endpoint works properly and route `/hello` does return `Hello World`
+Create `tests/hello.test.js` with the following:
-Let's create a separate test file where `supertest` will be used to check if endpoint works as expected.
+```js title="./tests/hello.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+const request = require('supertest');
-```js title="path: ./tests/hello/index.js"
+beforeAll(async () => {
+ await setupStrapi();
+});
-const request = require('supertest');
+afterAll(async () => {
+ await cleanupStrapi();
+});
-it("should return hello world", async () => {
+it('should return hello world', async () => {
await request(strapi.server.httpServer)
- .get("/api/hello")
- .expect(200) // Expect response http code 200
+ .get('/api/hello')
+ .expect(200)
.then((data) => {
- expect(data.text).toBe("Hello World!"); // expect the response text
+ expect(data.text).toBe('Hello World!');
});
});
-
```
-Then include this code to `./tests/app.test.js` at the bottom of that file
+The harness registers the `/api/hello` route automatically, so the test only has to make the request.
-```js
-require('./hello');
-```
+## Test API authentication
-and run `yarn test` which should return
+Strapi uses a JWT token to handle authentication. We will create one user with a known username and password, and use these credentials to authenticate and get a JWT token. The patched `user.add` helper in the harness ensures the authenticated role is applied automatically.
-```bash
-➜ my-project yarn test
-yarn run v1.13.0
-$ jest --detectOpenHandles
- PASS tests/app.test.js (5.742 s)
- ✓ strapi is defined (4 ms)
- ✓ should return hello world (208 ms)
-
-[2020-05-22T14:37:38.018Z] debug GET /hello (58 ms) 200
-Test Suites: 1 passed, 1 total
-Tests: 2 passed, 2 total
-Snapshots: 0 total
-Time: 6.635 s, estimated 7 s
-Ran all test suites.
-✨ Done in 9.09s.
-```
-
-:::tip
-If you receive an error `Jest has detected the following 1 open handles potentially keeping Jest from exiting` check `jest` version as `26.6.3` works without an issue.
-:::
-
-## Test an `auth` endpoint controller
+Create `tests/auth.test.js`:
-In this scenario we'll test authentication login endpoint with two tests
-
-1. Test `/auth/local` that should login user and return `jwt` token
-2. Test `/users/me` that should return users data based on `Authorization` header
+```js title="./tests/auth.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+const request = require('supertest');
+beforeAll(async () => {
+ await setupStrapi();
+});
-```js title="path: ./tests/user/index.js"
-const request = require('supertest');
+afterAll(async () => {
+ await cleanupStrapi();
+});
-// user mock data
+// User mock data
const mockUserData = {
- username: "tester",
- email: "tester@strapi.com",
- provider: "local",
- password: "1234abc",
+ username: 'tester',
+ email: 'tester@strapi.com',
+ provider: 'local',
+ password: '1234abc',
confirmed: true,
blocked: null,
};
-it("should login user and return jwt token", async () => {
- /** Creates a new user and save it to the database */
- await strapi.plugins["users-permissions"].services.user.add({
+it('should login user and return JWT token', async () => {
+ await strapi.plugins['users-permissions'].services.user.add({
...mockUserData,
});
- await request(strapi.server.httpServer) // app server is an instance of Class: http.Server
- .post("/api/auth/local")
- .set("accept", "application/json")
- .set("Content-Type", "application/json")
+ await request(strapi.server.httpServer)
+ .post('/api/auth/local')
+ .set('accept', 'application/json')
+ .set('Content-Type', 'application/json')
.send({
identifier: mockUserData.email,
password: mockUserData.password,
})
- .expect("Content-Type", /json/)
+ .expect('Content-Type', /json/)
.expect(200)
.then((data) => {
expect(data.body.jwt).toBeDefined();
});
});
+```
-it('should return users data for authenticated user', async () => {
- /** Gets the default user role */
- const defaultRole = await strapi.query('plugin::users-permissions.role').findOne({}, []);
+You can use the JWT token returned to make authenticated requests to the API. Using this example, you can add more tests to validate that the authentication and authorization are working as expected.
- const role = defaultRole ? defaultRole.id : null;
+## Advanced API testing with user permissions
- /** Creates a new user an push to database */
- const user = await strapi.plugins['users-permissions'].services.user.add({
- ...mockUserData,
- username: 'tester2',
- email: 'tester2@strapi.com',
- role,
- });
+When you create API tests, you will most likely need to test endpoints that require authentication. In the following example we will implement a helper to get and use the JWT token.
- const jwt = strapi.plugins['users-permissions'].services.jwt.issue({
- id: user.id,
- });
+Create `tests/user.test.js`:
- await request(strapi.server.httpServer) // app server is an instance of Class: http.Server
- .get('/api/users/me')
- .set('accept', 'application/json')
- .set('Content-Type', 'application/json')
- .set('Authorization', 'Bearer ' + jwt)
- .expect('Content-Type', /json/)
- .expect(200)
- .then(data => {
- expect(data.body).toBeDefined();
- expect(data.body.id).toBe(user.id);
- expect(data.body.username).toBe(user.username);
- expect(data.body.email).toBe(user.email);
+```js title="./tests/user.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+const request = require('supertest');
+
+beforeAll(async () => {
+ await setupStrapi();
+});
+
+afterAll(async () => {
+ await cleanupStrapi();
+});
+
+let authenticatedUser = {};
+
+// User mock data
+const mockUserData = {
+ username: 'tester',
+ email: 'tester@strapi.com',
+ provider: 'local',
+ password: '1234abc',
+ confirmed: true,
+ blocked: null,
+};
+
+describe('User API', () => {
+ beforeAll(async () => {
+ await strapi.plugins['users-permissions'].services.user.add({
+ ...mockUserData,
});
+
+ const response = await request(strapi.server.httpServer)
+ .post('/api/auth/local')
+ .set('accept', 'application/json')
+ .set('Content-Type', 'application/json')
+ .send({
+ identifier: mockUserData.email,
+ password: mockUserData.password,
+ });
+
+ authenticatedUser.jwt = response.body.jwt;
+ authenticatedUser.user = response.body.user;
+ });
+
+ it('should return users data for authenticated user', async () => {
+ await request(strapi.server.httpServer)
+ .get('/api/users/me')
+ .set('accept', 'application/json')
+ .set('Content-Type', 'application/json')
+ .set('Authorization', 'Bearer ' + authenticatedUser.jwt)
+ .expect('Content-Type', /json/)
+ .expect(200)
+ .then((data) => {
+ expect(data.body).toBeDefined();
+ expect(data.body.id).toBe(authenticatedUser.user.id);
+ expect(data.body.username).toBe(authenticatedUser.user.username);
+ expect(data.body.email).toBe(authenticatedUser.user.email);
+ });
+ });
});
```
-Then include this code to `./tests/app.test.js` at the bottom of that file
+## Automate tests with GitHub Actions
-```js
-require('./user');
-```
+To go further, you can run your Jest test suite automatically on every push and pull request with . Create a `.github/workflows/test.yaml` file in your project and add the workflow as follows:
-All the tests above should return an console output like
+```yaml title="./.github/workflows/test.yaml"
+name: 'Tests'
-```bash
-➜ my-project git:(master) yarn test
-
-yarn run v1.13.0
-$ jest --forceExit --detectOpenHandles
-[2020-05-27T08:30:30.811Z] debug GET /hello (10 ms) 200
-[2020-05-27T08:30:31.864Z] debug POST /auth/local (891 ms) 200
- PASS tests/app.test.js (6.811 s)
- ✓ strapi is defined (3 ms)
- ✓ should return hello world (54 ms)
- ✓ should login user and return jwt token (1049 ms)
- ✓ should return users data for authenticated user (163 ms)
-
-Test Suites: 1 passed, 1 total
-Tests: 4 passed, 4 total
-Snapshots: 0 total
-Time: 6.874 s, estimated 9 s
-Ran all test suites.
-✨ Done in 8.40s.
+on:
+ pull_request:
+ push:
+
+jobs:
+ run-tests:
+ name: Run Tests
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: Install modules
+ run: npm ci
+ - name: Run Tests
+ run: npm run test
```
+
+Pairing continuous integration with your unit and API tests helps prevent regressions before they reach production.
\ No newline at end of file
diff --git a/docusaurus/static/llms-full.txt b/docusaurus/static/llms-full.txt
index a59c4d7ef8..5a5083986b 100644
--- a/docusaurus/static/llms-full.txt
+++ b/docusaurus/static/llms-full.txt
@@ -12050,312 +12050,438 @@ An example of what a template could look like is the .
# Testing
Source: https://docs.strapi.io/cms/testing
-# Unit testing
+# Unit and integration testing guide
-:::strapi
-The Strapi blog has a tutorial on how to implement
+The present guide provides a hands-on approach to configuring
-
+
-Once this is done add this to `package.json` file
+ * `Jest` provides the test runner and assertion utilities.
+ * `Supertest` allows you to test all the `api` routes as they were instances of utilities to recreate just the parts of the Strapi object and any request context that your code relies on.
+
+### Controller example
+
+Create a test file such as `./tests/todo-controller.test.js` that instantiates your controller with a mocked Strapi object and verifies every call the controller performs:
+
+```js title="./tests/todo-controller.test.js"
+const todoController = require('./todo-controller');
+
+describe('Todo controller', () => {
+ let strapi;
+
+ beforeEach(() => {
+ strapi = {
+ plugin: jest.fn().mockReturnValue({
+ service: jest.fn().mockReturnValue({
+ create: jest.fn().mockReturnValue({
+ data: {
+ name: 'test',
+ status: false,
+ },
+ }),
+ complete: jest.fn().mockReturnValue({
+ data: {
+ id: 1,
+ status: true,
+ },
+ }),
+ }),
+ }),
+ };
+ });
-add `test` command to `scripts` section
+ it('creates a todo item', async () => {
+ const ctx = {
+ request: {
+ body: {
+ name: 'test',
+ },
+ },
+ body: null,
+ };
-```json
- "scripts": {
- "develop": "strapi develop",
- "start": "strapi start",
- "build": "strapi build",
- "strapi": "strapi",
- "test": "jest --forceExit --detectOpenHandles"
- },
-```
+ await todoController({ strapi }).index(ctx);
-and add those lines at the bottom of file
+ expect(ctx.body).toBe('created');
+ expect(strapi.plugin('todo').service('create').create).toHaveBeenCalledTimes(1);
+ });
-```json
- "jest": {
- "testPathIgnorePatterns": [
- "/node_modules/",
- ".tmp",
- ".cache"
- ],
- "testEnvironment": "node"
- }
+ it('completes a todo item', async () => {
+ const ctx = {
+ request: {
+ body: {
+ id: 1,
+ },
+ },
+ body: null,
+ };
+
+ await todoController({ strapi }).complete(ctx);
+
+ expect(ctx.body).toBe('todo completed');
+ expect(strapi.plugin('todo').service('complete').complete).toHaveBeenCalledTimes(1);
+ });
+});
```
-Those will inform `Jest` not to look for test inside the folder where it shouldn't.
+The `beforeEach` hook rebuilds the mock so every test starts with a clean Strapi instance. Each test prepares the `ctx` request object that the controller expects, calls the controller function, and asserts both the response and the interactions with Strapi services.
-## Set up a testing environment
+### Service example
-Test framework must have a clean empty environment to perform valid test and also not to interfere with current database.
+Services can be tested in the same test suite or in a dedicated file by mocking only the Strapi query layer they call into.
-Once `jest` is running it uses the `test` [environment](/cms/configurations/environment) (switching `NODE_ENV` to `test`)
-so we need to create a special environment setting for this purpose.
-Create a new config for test env `./config/env/test/database.js` and add the following value `"filename": ".tmp/test.db"` - the reason of that is that we want to have a separate sqlite database for tests, so our test will not touch real data.
-This file will be temporary, each time test is finished, we will remove that file that every time tests are run on the clean database.
-The whole file will look like this:
+```js title="./tests/create-service.test.js"
+const createService = require('./create-service');
-```js title="path: ./config/env/test/database.js"
+describe('Create service', () => {
+ let strapi;
-module.exports = ({ env }) => ({
- connection: {
- client: 'sqlite',
- connection: {
- filename: env('DATABASE_FILENAME', '.tmp/test.db'),
- },
- useNullAsDefault: true,
- debug: false
- },
+ beforeEach(() => {
+ strapi = {
+ query: jest.fn().mockReturnValue({
+ create: jest.fn().mockReturnValue({
+ data: {
+ name: 'test',
+ status: false,
+ },
+ }),
+ }),
+ };
+ });
+
+ it('persists a todo item', async () => {
+ const todo = await createService({ strapi }).create({ name: 'test' });
+
+ expect(strapi.query('plugin::todo.todo').create).toHaveBeenCalledTimes(1);
+ expect(todo.data.name).toBe('test');
+ });
});
```
-## Create a Strapi instance
+By focusing on mocking the specific Strapi APIs your code touches, you can grow these tests to cover additional branches, error cases, and services while keeping them fast and isolated.
-In order to test anything we need to have a strapi instance that runs in the testing environment,
-basically we want to get instance of strapi app as object, similar like creating an instance for .
+## Set up a testing environment
-These tasks require adding some files - let's create a folder `tests` where all the tests will be put and inside it, next to folder `helpers` where main Strapi helper will be in file strapi.js.
+For API-level testing with that sets up and tears down Strapi instances for tests
-```js title="path: ./tests/helpers/strapi.js"
-const Strapi = require("@strapi/strapi");
-const fs = require("fs");
+### TypeScript compiler configuration
-let instance;
+Create `tests/ts-compiler-options.js` with the following content:
-async function setupStrapi() {
- if (!instance) {
- await Strapi().load();
- instance = strapi;
-
- await instance.server.mount();
- }
- return instance;
-}
+```js title="./tests/ts-compiler-options.js"
+const fs = require('fs');
+const path = require('path');
+const ts = require('typescript');
+
+const projectRoot = path.resolve(__dirname, '..');
+const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+
+const baseCompilerOptions = {
+ module: ts.ModuleKind.CommonJS,
+ target: ts.ScriptTarget.ES2019,
+ moduleResolution: ts.ModuleResolutionKind.NodeJs,
+ esModuleInterop: true,
+ jsx: ts.JsxEmit.React,
+};
-async function cleanupStrapi() {
- const dbSettings = strapi.config.get("database.connection");
+const loadCompilerOptions = () => {
+ let options = { ...baseCompilerOptions };
- //close server to release the db-file
- await strapi.server.httpServer.close();
+ if (!fs.existsSync(tsconfigPath)) {
+ return options;
+ }
- // close the connection to the database before deletion
- await strapi.db.connection.destroy();
+ try {
+ const tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');
+ const parsed = ts.parseConfigFileTextToJson(tsconfigPath, tsconfigContent);
- //delete test database after all tests have completed
- if (dbSettings && dbSettings.connection && dbSettings.connection.filename) {
- const tmpDbFile = dbSettings.connection.filename;
- if (fs.existsSync(tmpDbFile)) {
- fs.unlinkSync(tmpDbFile);
+ if (!parsed.error && parsed.config && parsed.config.compilerOptions) {
+ options = {
+ ...options,
+ ...parsed.config.compilerOptions,
+ };
}
+ } catch (error) {
+ // Ignore tsconfig parsing errors and fallback to defaults
}
-}
-module.exports = { setupStrapi, cleanupStrapi };
+ return options;
+};
+
+module.exports = {
+ compilerOptions: loadCompilerOptions(),
+ loadCompilerOptions,
+};
```
-## Test a Strapi instance
+This file loads your project's TypeScript configuration and provides sensible defaults if the config file doesn't exist.
-We need a main entry file for our tests, one that will also test our helper file.
+### TypeScript runtime loader
-```js title="path: ./tests/app.test.js"
+Create `tests/ts-runtime.js` with the following content:
+
+```js title="./tests/ts-runtime.js"
+const Module = require('module');
+const { compilerOptions } = require('./ts-compiler-options');
const fs = require('fs');
-const { setupStrapi, cleanupStrapi } = require("./helpers/strapi");
+const ts = require('typescript');
+
+const extensions = Module._extensions;
+
+if (!extensions['.ts']) {
+ extensions['.ts'] = function compileTS(module, filename) {
+ const source = fs.readFileSync(filename, 'utf8');
+ const output = ts.transpileModule(source, {
+ compilerOptions,
+ fileName: filename,
+ reportDiagnostics: false,
+ });
+
+ return module._compile(output.outputText, filename);
+ };
+}
+
+if (!extensions['.tsx']) {
+ extensions['.tsx'] = extensions['.ts'];
+}
+
+module.exports = {
+ compilerOptions,
+};
+```
+
+This file teaches Node.js how to load `.ts` and `.tsx` files by transpiling them to JavaScript on the fly.
+
+### Main test harness
+
+Create `tests/strapi.js` with the following content:
+
+What the test harness does:
+
+1. **TypeScript Support**: Patches Strapi's configuration loader to understand TypeScript files (`.ts`, `.cts`, `.mts`) in your config directory
+2. **Configuration Validation**: Ensures only valid config files are loaded and warns about common mistakes (like naming a file `middleware.js` instead of `middlewares.js`)
+3. **Database Normalization**: Maps database client names to their actual driver names (e.g., `sqlite` → `sqlite3`) and handles connection pooling
+4. **Environment Setup**: Sets all required environment variables for testing, including JWT secrets and database configuration
+5. **Automatic Route Registration**: Automatically registers a `/api/hello` test endpoint that you can use in your tests
+6. **User Permission Helper**: Patches the user service to automatically assign the "authenticated" role to newly created users, simplifying authentication tests
+7. **Cleanup**: Properly closes connections and removes temporary database files after tests complete
+
+Once these files are in place, the harness handles several Strapi 5 requirements automatically, letting you focus on writing actual test logic rather than configuration boilerplate.
+
+## Create smoke tests
+With the harness in place you can confirm Strapi boots correctly by adding a minimal Jest suite with the following **smoke tests** in a `tests/app.test.js` as follows:
+
+```js title="./tests/app.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+
+/** this code is called once before any test is called */
beforeAll(async () => {
- await setupStrapi();
+ await setupStrapi(); // Singleton so it can be called many times
});
+/** this code is called once before all the tests are finished */
afterAll(async () => {
await cleanupStrapi();
});
-it("strapi is defined", () => {
+it('strapi is defined', () => {
expect(strapi).toBeDefined();
});
+
+require('./hello');
+require('./user');
```
-Actually this is all we need for writing unit tests. Just run `yarn test` and see a result of your first test
+Running `yarn test` or `npm run test` should now yield:
```bash
-yarn run v1.13.0
-$ jest
- PASS tests/app.test.js
- ✓ strapi is defined (2 ms)
+PASS tests/create-service.test.js
+PASS tests/todo-controller.test.js
-Test Suites: 1 passed, 1 total
-Tests: 1 passed, 1 total
+Test Suites: 6 passed, 6 total
+Tests: 7 passed, 7 total
Snapshots: 0 total
-Time: 4.187 s
+Time: 7.952 s
Ran all test suites.
-✨ Done in 5.73s.
+✨ Done in 8.63s.
```
-:::tip
-If you receive a timeout error for Jest, please add the following line right before the `beforeAll` method in the `app.test.js` file: `jest.setTimeout(15000)` and adjust the milliseconds value as you need.
-:::
-
-## Test a basic endpoint controller
-
-:::tip
-In the example we'll use and example `Hello world` `/hello` endpoint from [controllers](/cms/backend-customization/controllers) section.
-
+:::caution
+If you receive a timeout error for Jest, increase the timeout by calling `jest.setTimeout(30000)` in `tests/strapi.js` or at the top of your test file.
:::
-Some might say that API tests are not unit but limited integration tests, regardless of nomenclature, let's continue with testing first endpoint.
+## Test a basic API endpoint
-We'll test if our endpoint works properly and route `/hello` does return `Hello World`
+Create `tests/hello.test.js` with the following:
-Let's create a separate test file where `supertest` will be used to check if endpoint works as expected.
+```js title="./tests/hello.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+const request = require('supertest');
-```js title="path: ./tests/hello/index.js"
+beforeAll(async () => {
+ await setupStrapi();
+});
-const request = require('supertest');
+afterAll(async () => {
+ await cleanupStrapi();
+});
-it("should return hello world", async () => {
+it('should return hello world', async () => {
await request(strapi.server.httpServer)
- .get("/api/hello")
- .expect(200) // Expect response http code 200
+ .get('/api/hello')
+ .expect(200)
.then((data) => {
- expect(data.text).toBe("Hello World!"); // expect the response text
+ expect(data.text).toBe('Hello World!');
});
});
-
-```
-
-Then include this code to `./tests/app.test.js` at the bottom of that file
-
-```js
-require('./hello');
```
-and run `yarn test` which should return
+The harness registers the `/api/hello` route automatically, so the test only has to make the request.
-```bash
-➜ my-project yarn test
-yarn run v1.13.0
-$ jest --detectOpenHandles
- PASS tests/app.test.js (5.742 s)
- ✓ strapi is defined (4 ms)
- ✓ should return hello world (208 ms)
-
-[2020-05-22T14:37:38.018Z] debug GET /hello (58 ms) 200
-Test Suites: 1 passed, 1 total
-Tests: 2 passed, 2 total
-Snapshots: 0 total
-Time: 6.635 s, estimated 7 s
-Ran all test suites.
-✨ Done in 9.09s.
-```
+## Test API authentication
-:::tip
-If you receive an error `Jest has detected the following 1 open handles potentially keeping Jest from exiting` check `jest` version as `26.6.3` works without an issue.
-:::
+Strapi uses a JWT token to handle authentication. We will create one user with a known username and password, and use these credentials to authenticate and get a JWT token. The patched `user.add` helper in the harness ensures the authenticated role is applied automatically.
-## Test an `auth` endpoint controller
+Create `tests/auth.test.js`:
-In this scenario we'll test authentication login endpoint with two tests
+```js title="./tests/auth.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+const request = require('supertest');
-1. Test `/auth/local` that should login user and return `jwt` token
-2. Test `/users/me` that should return users data based on `Authorization` header
+beforeAll(async () => {
+ await setupStrapi();
+});
-```js title="path: ./tests/user/index.js"
-const request = require('supertest');
+afterAll(async () => {
+ await cleanupStrapi();
+});
-// user mock data
+// User mock data
const mockUserData = {
- username: "tester",
- email: "tester@strapi.com",
- provider: "local",
- password: "1234abc",
+ username: 'tester',
+ email: 'tester@strapi.com',
+ provider: 'local',
+ password: '1234abc',
confirmed: true,
blocked: null,
};
-it("should login user and return jwt token", async () => {
- /** Creates a new user and save it to the database */
- await strapi.plugins["users-permissions"].services.user.add({
+it('should login user and return JWT token', async () => {
+ await strapi.plugins['users-permissions'].services.user.add({
...mockUserData,
});
- await request(strapi.server.httpServer) // app server is an instance of Class: http.Server
- .post("/api/auth/local")
- .set("accept", "application/json")
- .set("Content-Type", "application/json")
+ await request(strapi.server.httpServer)
+ .post('/api/auth/local')
+ .set('accept', 'application/json')
+ .set('Content-Type', 'application/json')
.send({
identifier: mockUserData.email,
password: mockUserData.password,
})
- .expect("Content-Type", /json/)
+ .expect('Content-Type', /json/)
.expect(200)
.then((data) => {
expect(data.body.jwt).toBeDefined();
});
});
+```
-it('should return users data for authenticated user', async () => {
- /** Gets the default user role */
- const defaultRole = await strapi.query('plugin::users-permissions.role').findOne({}, []);
+You can use the JWT token returned to make authenticated requests to the API. Using this example, you can add more tests to validate that the authentication and authorization are working as expected.
- const role = defaultRole ? defaultRole.id : null;
+## Advanced API testing with user permissions
- /** Creates a new user an push to database */
- const user = await strapi.plugins['users-permissions'].services.user.add({
- ...mockUserData,
- username: 'tester2',
- email: 'tester2@strapi.com',
- role,
- });
+When you create API tests, you will most likely need to test endpoints that require authentication. In the following example we will implement a helper to get and use the JWT token.
- const jwt = strapi.plugins['users-permissions'].services.jwt.issue({
- id: user.id,
- });
+Create `tests/user.test.js`:
- await request(strapi.server.httpServer) // app server is an instance of Class: http.Server
- .get('/api/users/me')
- .set('accept', 'application/json')
- .set('Content-Type', 'application/json')
- .set('Authorization', 'Bearer ' + jwt)
- .expect('Content-Type', /json/)
- .expect(200)
- .then(data => {
- expect(data.body).toBeDefined();
- expect(data.body.id).toBe(user.id);
- expect(data.body.username).toBe(user.username);
- expect(data.body.email).toBe(user.email);
+```js title="./tests/user.test.js"
+const { setupStrapi, cleanupStrapi } = require('./strapi');
+const request = require('supertest');
+
+beforeAll(async () => {
+ await setupStrapi();
+});
+
+afterAll(async () => {
+ await cleanupStrapi();
+});
+
+let authenticatedUser = {};
+
+// User mock data
+const mockUserData = {
+ username: 'tester',
+ email: 'tester@strapi.com',
+ provider: 'local',
+ password: '1234abc',
+ confirmed: true,
+ blocked: null,
+};
+
+describe('User API', () => {
+ beforeAll(async () => {
+ await strapi.plugins['users-permissions'].services.user.add({
+ ...mockUserData,
});
+
+ const response = await request(strapi.server.httpServer)
+ .post('/api/auth/local')
+ .set('accept', 'application/json')
+ .set('Content-Type', 'application/json')
+ .send({
+ identifier: mockUserData.email,
+ password: mockUserData.password,
+ });
+
+ authenticatedUser.jwt = response.body.jwt;
+ authenticatedUser.user = response.body.user;
+ });
+
+ it('should return users data for authenticated user', async () => {
+ await request(strapi.server.httpServer)
+ .get('/api/users/me')
+ .set('accept', 'application/json')
+ .set('Content-Type', 'application/json')
+ .set('Authorization', 'Bearer ' + authenticatedUser.jwt)
+ .expect('Content-Type', /json/)
+ .expect(200)
+ .then((data) => {
+ expect(data.body).toBeDefined();
+ expect(data.body.id).toBe(authenticatedUser.user.id);
+ expect(data.body.username).toBe(authenticatedUser.user.username);
+ expect(data.body.email).toBe(authenticatedUser.user.email);
+ });
+ });
});
```
-Then include this code to `./tests/app.test.js` at the bottom of that file
+## Automate tests with GitHub Actions
-```js
-require('./user');
-```
+To go further, you can run your Jest test suite automatically on every push and pull request with . Create a `.github/workflows/test.yaml` file in your project and add the workflow as follows:
-All the tests above should return an console output like
+```yaml title="./.github/workflows/test.yaml"
+name: 'Tests'
-```bash
-➜ my-project git:(master) yarn test
-
-yarn run v1.13.0
-$ jest --forceExit --detectOpenHandles
-[2020-05-27T08:30:30.811Z] debug GET /hello (10 ms) 200
-[2020-05-27T08:30:31.864Z] debug POST /auth/local (891 ms) 200
- PASS tests/app.test.js (6.811 s)
- ✓ strapi is defined (3 ms)
- ✓ should return hello world (54 ms)
- ✓ should login user and return jwt token (1049 ms)
- ✓ should return users data for authenticated user (163 ms)
-
-Test Suites: 1 passed, 1 total
-Tests: 4 passed, 4 total
-Snapshots: 0 total
-Time: 6.874 s, estimated 9 s
-Ran all test suites.
-✨ Done in 8.40s.
+on:
+ pull_request:
+ push:
+
+jobs:
+ run-tests:
+ name: Run Tests
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: Install modules
+ run: npm ci
+ - name: Run Tests
+ run: npm run test
```
+Pairing continuous integration with your unit and API tests helps prevent regressions before they reach production.
+
# TypeScript
diff --git a/docusaurus/static/llms.txt b/docusaurus/static/llms.txt
index 3f2e868c6a..a76a449584 100644
--- a/docusaurus/static/llms.txt
+++ b/docusaurus/static/llms.txt
@@ -120,7 +120,7 @@
- [Project structure](https://docs.strapi.io/cms/project-structure): Discover the project structure of any default Strapi application.
- [Quick Start Guide - Strapi Developer Docs](https://docs.strapi.io/cms/quick-start): Get ready to get Strapi, your favorite open-source headless cms up and running in less than 3 minutes.
- [Templates](https://docs.strapi.io/cms/templates): Use and create pre-made Strapi applications designed for a specific use case.
-- [Testing](https://docs.strapi.io/cms/testing): Learn how to test your Strapi application.
+- [Testing](https://docs.strapi.io/cms/testing): Learn how to test your Strapi application with Jest and Supertest.
- [TypeScript](https://docs.strapi.io/cms/typescript): Get started with TypeScript for your Strapi application
- [TypeScript development](https://docs.strapi.io/cms/typescript/development): Learn more about TypeScript usage with Strapi 5
- [TypeScript Guides](https://docs.strapi.io/cms/typescript/guides): Learn how you can leverage TypeScript while developing your Strapi project.