docs: add section on testing providers (#9453)

2024-10-04 10:29:45 +03:00
parent aec99b49cc
commit bc8de8e5b1
16 changed files with 597 additions and 391 deletions
@@ -234,7 +234,7 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
      await authIdentityService.retrieve({
        entity_id: data.body.email, // email or some ID
      })
-    
+
      return {
        success: false,
        error: "Identity with email already exists",
@@ -248,13 +248,13 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
            // can include password or any other relevant information
          }
        })
-    
+
        return {
          success: true,
          authIdentity: createdAuthIdentity,
        }
      }
-    
+
      return { success: false, error: error.message }
    }
  }
@@ -299,7 +299,7 @@ class MyAuthProviderService extends AbstractAuthModuleProvider {
          user: data.user // example
        }
      )
-    
+
      return { success: true, authIdentity }
    } catch (error) {
      return { success: false, error: error.message }
@@ -452,3 +452,23 @@ module.exports = defineConfig({
  }
 })
 ```
+
+---
+
+## 5. Test it Out
+
+To test out your authentication provider, use any of the [Authentication Routes](https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route), using your provider's ID as a path parameter.
+
+For example, to get a registration token for an admin user, send a `POST` request to `/auth/user/my-auth/register` replacing `my-auth` with your authentication provider's ID:
+
+```bash
+curl -X POST http://localhost:9000/auth/user/my-auth/register
+-H 'Content-Type: application/json' --data-raw '{
+  "email": "Whitney_Schultz@gmail.com",
+  "password": "supersecret"
+}'
+```
+
+Change the request body to pass the data required for your authentication provider to register the user.
+
+If registration is successful, the response will have a `token` property.
@@ -230,3 +230,9 @@ module.exports = defineConfig({
  }
 })
 ```
+
+---
+
+## 5. Test it Out
+
+To test out your file provider, use the Medusa Admin or the [Upload API route](https://docs.medusajs.com/v2/api/admin#uploads_postuploads) to upload a file.
@@ -124,14 +124,14 @@ system.
 class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
  // ...
  async validateFulfillmentData(
-    optionData: any, 
-    data: any, 
+    optionData: any,
+    data: any,
    context: any
  ): Promise<any> {
    // assuming your client retrieves an ID from the
    // third-party service
    const externalId = await this.client.getId()
-  
+
    return {
      ...data,
      externalId
@@ -176,7 +176,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {

 ### canCalculate

-This method indicates whether a shippin option's price is calculated during 
+This method indicates whether a shippin option's price is calculated during
 checkout or is fixed.

 #### Example
@@ -214,7 +214,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
    // assuming the client can calculate the price using
    // the third-party service
    const price = await this.client.calculate(data)
-  
+
    return price
  }
 }
@@ -230,7 +230,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {

 ### createFulfillment

-This method is used when a fulfillment is created. If the method returns in the object a 
+This method is used when a fulfillment is created. If the method returns in the object a
 `data` property, it's stored in the fulfillment's `data` property.

 The `data` property is useful when handling the fulfillment later,
@@ -244,9 +244,9 @@ You can also use this method to perform an action with the third-party fulfillme
 class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
  // ...
  async createFulfillment(
-    data: any, 
-    items: any, 
-    order: any, 
+    data: any,
+    items: any,
+    order: any,
    fulfillment: any
  ): Promise<any> {
    // assuming the client creates a fulfillment
@@ -255,7 +255,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
      fulfillment,
      items
    )
-  
+
    return {
      data: {
        ...data,
@@ -327,7 +327,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {

 ### createReturnFulfillment

-This method is used when a fulfillment is created for a return. If the method returns in the object a 
+This method is used when a fulfillment is created for a return. If the method returns in the object a
 `data` property, it's stored in the fulfillment's `data` property.

 The `data` property is useful when handling the fulfillment later,
@@ -346,7 +346,7 @@ class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
    const externalData = await this.client.createReturn(
      fulfillment
    )
-  
+
    return {
      data: {
        ...fulfillment.data,
@@ -425,7 +425,7 @@ This method retrieves the documents of a fulfillment of a certain type.
 class MyFulfillmentProviderService extends AbstractFulfillmentProviderService {
  // ...
  async retrieveDocuments(
-    fulfillmentData: any, 
+    fulfillmentData: any,
    documentType: any
  ): Promise<void> {
    // assuming the client retrieves documents
@@ -493,3 +493,14 @@ module.exports = defineConfig({
  }
 })
 ```
+
+---
+
+## 5. Test it Out
+
+Before you use your fulfillment provider, in the Medusa Admin:
+
+1. Add the fulfillment provider to a location.
+2. Add in the location a delivery shipping option that uses the provider.
+
+Then, place an order, choosing the shipping option you created during checkout, and create a fulfillment in the Medusa Admin. The fulfillment is created using your provider.
@@ -184,3 +184,61 @@ module.exports = defineConfig({
  }
 })
 ```
+
+Make sure to specify the correct channels for your provider in the `channels` option.
+
+---
+
+## 5. Test it Out
+
+### Create Subscriber
+
+To test out the provider, create a subscriber at `src/subscribers/user-created.ts` with the following content:
+
+```ts title="src/subscribers/user-created.ts"
+import { Modules } from "@medusajs/framework/utils"
+import {
+  SubscriberArgs,
+  type SubscriberConfig,
+} from "@medusajs/medusa"
+
+export default async function userCreatedHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const notificationModuleService = container.resolve(
+    Modules.NOTIFICATION
+  )
+  const userModule = container.resolve(
+    Modules.USER
+  )
+
+  const user = await userModule.retrieveUser(data.id)
+
+  await notificationModuleService.createNotifications({
+    to: user.email,
+    channel: "email",
+    template: "new-user"
+  })
+}
+
+export const config: SubscriberConfig = {
+  event: "user.created",
+}
+```
+
+In the subscriber, you resolve the Notification and User modules. Then, you use the User Module's main service to retrieve the user's details.
+
+Finally, you use the Notification Module's main service to send a notification to the user's email through the `email` channel (assuming that's your provider's channel).
+
+Make sure to replace the value of `template` to the ID of the template in your provider.
+
+### Create User
+
+Use the following command to create a user:
+
+```bash
+npx medusa user -e admin@test.com -p supersecret
+```
+
+After the user is created, the subscriber is executed, sending the notification using your provider.
@@ -721,3 +721,17 @@ module.exports = defineConfig({
  }
 })
 ```
+
+---
+
+## 5. Test it Out
+
+Before you use your payment provider, enable it in a region using the Medusa Admin.
+
+Then, go through checkout to place an order. Your payment provider is used to authorize the payment.
+
+---
+
+## Useful Guides
+
+- [Storefront Guide: how to implement UI for your payment provider during checkout](https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment)