8.1. Local Protocol Testing Tools

In this chapter, you'll learn about Local Protocol's testing tools and how to install and configure them.

@localprotojs/test-utils Package#

Local Protocol provides a @localprotojs/test-utils package with utility tools to create integration tests for your custom API routes, modules, or other Local Protocol customizations.

Install @localprotojs/test-utils#

To use the @localprotojs/test-utils package, install it as a devDependency:

npm
yarn
pnpm

Install and Configure Jest#

Writing tests with @localprotojs/test-utils's tools requires installing and configuring Jest in your project.

Run the following command to install the required Jest dependencies:

npm
yarn
pnpm

Then, create the file jest.config.js with the following content:

jest.config.js
1const { loadEnv } = require("@localprotojs/framework/utils")2loadEnv("test", process.cwd())3
4module.exports = {5  transform: {6    "^.+\\.[jt]s$": [7      "@swc/jest",8      {9        jsc: {10          parser: { syntax: "typescript", decorators: true },11        },12      },13    ],14  },15  testEnvironment: "node",16  moduleFileExtensions: ["js", "ts", "json"],17  modulePathIgnorePatterns: ["dist/"],18}19
20if (process.env.TEST_TYPE === "integration:http") {21  module.exports.testMatch = ["**/integration-tests/http/*.spec.[jt]s"]22} else if (process.env.TEST_TYPE === "integration:modules") {23  module.exports.testMatch = ["**/src/modules/*/__tests__/**/*.[jt]s"]24} else if (process.env.TEST_TYPE === "unit") {25  module.exports.testMatch = ["**/src/**/__tests__/**/*.unit.spec.[jt]s"]26}

Add Test Commands#

Finally, add the following scripts to package.json:

package.json
1"scripts": {2  // ...3  "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",4  "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",5  "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"6},

You now have two commands:

• test:integration:http to run integration tests (for example, for API routes and workflows) available under the integration-tests/http directory.
• test:integration:modules to run integration tests for modules available in any __tests__ directory under src/modules.
• test:unit to run unit tests in any __tests__ directory under the src directory.

Test Tools and Writing Tests#

The next chapters explain how to use the testing tools provided by @localprotojs/test-utils to write tests.