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 17:50:45 +03:00
parent e9fce4c5c2
commit 58f297cc75
18 changed files with 1125 additions and 76 deletions
--- a/www/apps/resources/app/test-tools-reference/moduleIntegrationTestRunner/page.mdx
+++ b/www/apps/resources/app/test-tools-reference/moduleIntegrationTestRunner/page.mdx
@@ -0,0 +1,154 @@
+import { TypeList } from "docs-ui"
+
+export const metadata = {
+  title: `moduleIntegrationTestRunner Reference`,
+}
+
+# {metadata.title}
+
+This document provides a reference to the `moduleIntegrationTestRunner` function provided by the `medusa-test-utils` package.
+
+## Example
+
+```ts
+import { moduleIntegrationTestRunner } from "medusa-test-utils"
+import { HELLO_MODULE } from ".."
+import HelloModuleService from "../service"
+import MyCustom from "../models/my-custom"
+
+moduleIntegrationTestRunner<HelloModuleService>({
+  moduleName: HELLO_MODULE,
+  moduleModels: [MyCustom],
+  resolve: "./modules/hello",
+  testSuite: ({ service }) => {
+    // TODO write tests
+  }
+})
+```
+
+## Parameters
+
+<TypeList
+  types={[
+    {
+      type: "`object`",
+      name: "Input",
+      description: "Object parameter of test options.",
+      children: [
+        {
+          type: "`string`",
+          name: "moduleName",
+          description: "The module's name.",
+          optional: false
+        },
+        {
+          type: "DmlEntity[]",
+          name: "moduleModels",
+          description: "The module's data models.",
+          optional: false
+        },
+        {
+          type: "string",
+          name: "resolve",
+          description: "The path to the module relative to the `src` directory.",
+          optional: false
+        },
+        {
+          type: "`() => void`",
+          name: "testSuite",
+          description: "The Jest tests to run.",
+          optional: false
+        },
+        {
+          type: "`Record<string, any>`",
+          name: "moduleOptions",
+          description: "Options to pass to the module.",
+        },
+        {
+          type: "`Record<string, any>`",
+          name: "injectedDependencies",
+          description: "Dependencies to inject into the module's container. They key is the registration name, and the value is the instance of the dependency.",
+        },
+        {
+          type: "`string`",
+          name: "schema",
+          description: "The PostgreSQL schema that the database is created in.",
+        },
+        {
+          type: "`boolean`",
+          name: "debug",
+          description: "Whether to show database log messages.",
+          defaultValue: "false"
+        }
+      ]
+    }
+  ]}
+  sectionTitle="Parameters"
+/>
+
+## Test Suite Parameters
+
+The function passed to `testSuite` accepts the following parameters:
+
+<TypeList
+  types={[
+    {
+      type: "`object`",
+      name: "Input",
+      description: "Object parameter of test utilities.",
+      children: [
+        {
+          type: "any",
+          name: "service",
+          description: "An instance of the module's main service. Its type is the type argument passed to the `moduleIntegrationTestRunner` function.",
+          optional: false
+        },
+        {
+          type: "`Record<string, string>`",
+          name: "dbConfig",
+          description: "The created database's configurations",
+          children: [
+            {
+              type: "`string`",
+              name: "schema",
+              description: "The PostgreSQL schema the database is created in."
+            },
+            {
+              type: "`string`",
+              name: "clientUrl",
+              description: "The connection URL to the database."
+            },
+          ]
+        },
+        {
+          type: "`TestDatabase`",
+          name: "MikroOrmWrapper",
+          description: "Utility functions to query and manage the database.",
+          children: [
+            {
+              type: `[SqlEntityManager](https://mikro-orm.io/api/5.9/knex/class/EntityManager)`,
+              name: "manager",
+              description: "An instance of MikroORM's entity manager, which can be used to run queries and perform other database tasks."
+            },
+            {
+              type: "`() => Promise<void>`",
+              name: "setupDatabase",
+              description: "Creates the database for the test."
+            },
+            {
+              type: "`() => Promise<void>`",
+              name: "clearDatabase",
+              description: "Removes all data in the database's tables."
+            },
+            {
+              type: "`() => SqlEntityManager`",
+              name: "forkManager",
+              description: "Returns a new entity manager."
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+  sectionTitle="Test Suite Parameters"
+/>