7.4. Debug Workflows
In this chapter, you'll learn about the different ways you can debug workflows in Medusa.
Debugging workflows is essential to ensure your custom features work as expected. It helps you identify unexpected issues and bugs in your workflow logic.
Approaches to Debug Workflows#
There are several ways to debug workflows in Medusa:
Approach | When to Use |
|---|---|
To ensure your workflow produces the expected results and handles edge cases. | |
To inspect specific steps in your workflow and understand the data flow. | |
To check values during execution with minimal overhead. | |
To monitor stored workflow executions and long-running workflows, especially in production environments. |
Approach 1: Write Integration Tests#
Integration tests run your workflow in a controlled environment to verify its behavior and outcome. By writing integration tests, you ensure your workflow produces the expected results and handles edge cases.
When to Use Integration Tests#
It's recommended to always write integration tests for your workflows. This helps you catch issues early and ensures your custom logic works as intended.
How to Write Integration Tests for Workflows#
Refer to the Integration Tests chapter to learn how to write integration tests for your workflows and find examples of testing workflows.
Approach 2: Add Breakpoints#
Breakpoints allow you to pause workflow execution at specific steps and inspect the data. They're useful for understanding the data flow in your steps and identifying issues.
When to Use Breakpoints#
Use breakpoints when you need to debug specific steps in your workflow, rather than the entire workflow. You can verify that the step is behaving as expected and is producing the correct output.
Where Can You Add Breakpoints#
Since Medusa stores an internal representation of the workflow constructor on application startup, breakpoints within the workflow's constructor won't work during execution. Learn more in the Data Manipulation chapter.
Instead, you can add breakpoints in:
- A step function.
- A step's compensation function.
- The
transformcallback function of a step.
For example:
How to Add Breakpoints#
If your code editor supports adding breakpoints, you can add them in your step and compensation functions, or the transform callback function. When the workflow execution reaches the breakpoint, your code editor will pause execution, allowing you to inspect the data and walk through the code.
If you're using VS Code or Cursor, learn how to add breakpoints in the VS Code documentation. For other code editors, refer to their respective documentation.
Approach 3: Log Messages#
Logging messages is a simple yet effective way to debug code. By logging messages, you can check values during execution with minimal overhead.
When to Use Logging#
Use logging when debugging workflows and you want to check values during execution without the overhead of setting up breakpoints.
Logging is also useful when you want to verify variable values between steps or in a transform callback function.
How to Log Messages#
Since Medusa stores an internal representation of the workflow constructor on application startup, you can't directly log messages in the workflow's constructor.
Instead, you can log messages in:
- A step function.
- A step's compensation function.
- The
transformcallback function of a step.
You can log messages with console.log. In step and compensation functions, you can also use the Logger to log messages with different log levels (info, warn, error).
For example:
If you execute the workflow, you'll see the logged message in your console.
Approach 4: Monitor Workflow Executions in Medusa Admin#
The Medusa Admin has a Workflows settings page that provides a user-friendly interface to view stored workflow executions.
When to Use Admin Monitoring#
Use the Medusa Admin to monitor stored workflow executions when debugging unexpected issues and edge cases, especially in production environments and long-running workflows that run in the background.
By viewing the workflow executions through the Medusa Admin, you can:
- View the status of stored workflow executions.
- Inspect input and output data for each execution and its steps.
- Identify any issues or errors in the workflow execution.
How to Monitor Workflow Executions in the Admin#
The Workflows settings page in the Medusa Admin shows you the history of stored workflow executions only. Workflow executions are stored if a workflow is long-running, or if the store and retentionTime options are set on the workflow.
For example, to store workflow executions:
6} from "@medusajs/framework/workflows-sdk"7 8const step1 = createStep(9 "step-1",10 async () => {11 const message = "Hello from step 1!"12 13 return new StepResponse(14 message15 )16 }17)18 19export const myWorkflow = createWorkflow(20 {21 name: "my-workflow",22 retentionTime: 99999,23 store: true,24 },25 () => {26 const response = step1()27 28 return new WorkflowResponse({29 response,30 })31 }32)
You can view all executions of this workflow in the Medusa Admin under the Workflows settings page. Each execution will show you the status, input, and output data.
