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
@@ -0,0 +1,58 @@
+export const metadata = {
+  title: `${pageNumber} Write Integration Tests`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn about the `medusaIntegrationTestRunner` utility function used to write integration tests.
+
+## medusaIntegrationTestRunner Utility
+
+The `medusaIntegrationTestRunner` utility function is provided by the `medusa-test-utils` package to create integration tests in your Medusa project. It runs a full Medusa application, allowing you test API routes, workflows, or other customizations.
+
+For example:
+
+export const highlights = [
+  ["4", "api", "A set of utility methods used to send requests to the Medusa application."],
+  ["4", "getContainer", "A function to retrieve the Medusa container."]
+]
+
+```ts title="integration-tests/http/test.spec.ts" highlights={highlights}
+import { medusaIntegrationTestRunner } from "medusa-test-utils"
+
+medusaIntegrationTestRunner({
+  testSuite: ({ api, getContainer }) => {
+    // TODO write tests...
+  }
+})
+```
+
+The `medusaIntegrationTestRunner` function accepts an object as a parameter. The object has a required property `testSuite`.
+
+`testSuite`'s value is a function that defines the tests to run. The function accepts as a parameter an object that has the following properties:
+
+- `api`: a set of utility methods used to send requests to the Medusa application. It has the following methods:
+    - `get`: Send a `GET` request to an API route.
+    - `post`: Send a `POST` request to an API route.
+    - `delete`: Send a `DELETE` request to an API route.
+- `getContainer`: a function that retrieves the Medusa Container. Use the `getContainer().resolve` method to resolve resources from the Medusa Container.
+
+The tests in the `testSuite` function are written using [Jest](https://jestjs.io/).
+
+### Other Options and Inputs
+
+Refer to [this reference in the Learning Resources documentation](!resources!/test-tools-reference/medusaIntegrationTestRunner) for other available parameter options and inputs of the `testSuite` function.
+
+---
+
+## Database Used in Tests
+
+The `medusaIntegrationTestRunner` function creates a database with a random name before running the tests. Then, it drops that database after all the tests end.
+
+To manage that database, such as changing its name or perform operations on it in your tests, refer to the [references in the Learning Resources documentation](!resources!/test-tools-reference/medusaIntegrationTestRunner).
+
+---
+
+## Example Integration Tests
+
+The next chapters provide examples of writing integration tests for API routes and workflows.