docs: added documentation on testing tools (#8939)

- Added documentation on how to use Medusa's tools from the `medusa-test-utils` package to create integration and unit tests. - Added a manual reference on the `medusaIntegrationTestRunner` and `moduleIntegrationTestRunner` functions. Since the typings in the source code aren't very informative, I opted for a manual reference shedding light on the important bits. Closes DOCS-852
2024-09-03 14:50:45 +00:00
parent e9fce4c5c2
commit 58f297cc75
18 changed files with 1125 additions and 76 deletions
@@ -0,0 +1,103 @@
+export const metadata = {
+  title: `${pageNumber} Medusa Testing Tools`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn about Medusa's testing tools and how to install and configure them.
+
+## medusa-test-utils Package
+
+Medusa provides a `medusa-test-utils` package with utility tools to create integration tests for your custom API routes, modules, or other Medusa customizations.
+
+### Install medusa-test-utils
+
+To use the `medusa-test-utils` package, install it as a `devDependency`:
+
+```bash npm2yarn
+npm install --save-dev medusa-test-utils
+```
+
+---
+
+## Install and Configure Jest
+
+Writing tests with `medusa-test-utils`'s tools requires installing and configuring Jest in your project.
+
+{/* TODO remove this note at some point in the future */}
+
+<Note>
+
+If your Medusa project was created after September 3rd, Jest is already installed and configured.
+
+</Note>
+
+Run the following command to install the required Jest dependencies:
+
+```bash npm2yarn
+npm install --save-dev jest @types/jest @swc/jest
+```
+
+Then, create the file `jest.config.js` with the following content:
+
+```js title="jest.config.js"
+const { loadEnv } = require('@medusajs/utils')
+loadEnv('test', process.cwd())
+
+module.exports = {
+  transform: {
+    "^.+\\.[jt]s$": [
+      "@swc/jest",
+      {
+        jsc: {
+          parser: { syntax: "typescript", decorators: true },
+        },
+      },
+    ],
+  },
+  testEnvironment: "node",
+  moduleFileExtensions: ["js", "ts", "json"],
+  modulePathIgnorePatterns: ["dist/"],
+}
+
+if (process.env.TEST_TYPE === "integration:http") {
+  module.exports.testMatch = ["**/integration-tests/http/*.spec.[jt]s"]
+} else if (process.env.TEST_TYPE === "integration:modules") {
+  module.exports.testMatch = ["**/src/modules/*/__tests__/**/*.[jt]s"]
+} else if (process.env.TEST_TYPE === "unit") {
+  module.exports.testMatch = ["**/src/**/__tests__/**/*.unit.spec.[jt]s"]
+}
+```
+
+---
+
+## Add Test Commands
+
+Finally, add the following scripts to `package.json`:
+
+```json title="package.json"
+"scripts": {
+  // ...
+  "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
+  "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",
+  "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
+},
+```
+
+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.
+
+<Note>
+
+Unit tests aren't covered by Medusa's testing tools.
+
+</Note>
+
+---
+
+## Test Tools and Writing Tests
+
+The next chapters explain how to use the testing tools provided by `medusa-test-utils` to write tests.