> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/playbooks/playbook-testing.md).

# Playbook Testing

After completing a playbook, the next step is to test the playbook on an incident to ensure the expected outcome. This can be done using a dev instance of a third-party integration to ingest incidents or by using the out of the box Sample Incident Generator.

**Playbook debugger**

The Cortex XSOAR playbook debugger enables you to build and troubleshoot playbooks, by helping you find tasks that might fail and by testing different conditions, branches, and input and output options. Common use cases include:

* Playbook development - test and improve playbooks as you build them.
* Proof of concept - begin to create and test playbooks even before all integrations are in place, by manually providing inputs and outputs as needed.
* Error troubleshooting - use the debugger to find and fix issues if a playbook stops on an error.
* Explore Marketplace playbooks - install content packs and use the debugger to see whether the included playbooks are relevant for your use case.

{% hint style="info" %}

### Tip

The playbook debugger runs all commands as if it is in an incident. Make sure to skip automation tasks that make critical changes on third-party tools.
{% endhint %}

Building a playbook is an iterative process. The debugger provides a test environment where you can make changes to data and playbook logic and view the results in real time. You have the opportunity to see exactly what is written to context at each step and which indicators are extracted.

**Debugger execution**

The debugger runs the playbook with the permissions of the logged in user, not as dBot. When the user sets breakpoints, skips tasks, or overrides inputs or outputs, those changes only apply to the individual user’s session and do not permanently change the playbook. Using an existing incident as test data does not affect the original incident or change the original context data. When tasks run, however, they execute the same as they would without the debugger. For example, if you run the debugger and a task adds an item to a list, that item will be in the real list, accessible across Cortex XSOAR for all users with permission to view that list.

**Test data**

The debugger uses test data to execute the playbook, so you can see what your expected results would be. There are three options for test data.

1. **New Mock Incident** - by default, the debugger runs using an empty mock incident. An empty mock incident is useful to test simple functionality, such as a playbook that does simple tasks such as parsing inputs.
2. **Playground** - you can load the contents of the Playground as test data, enabling you to use uploaded files and custom context data for testing purposes.
3. **Existing Incident** - you can select an existing Cortex XSOAR incident. For example, when debugging a phishing playbook, you might want to use an existing phishing incident that came from the mail listener integration. Using an existing incident in the debugger does not change the original incident.

   If you need to use event data from third-party software that is not yet set up as an integration, you can import a JSON file into Cortex XSOAR through the mapping feature and create an incident that can then be used as test data.

   You can use a file attachment for your test data by adding the file to an incident and selecting the incident or by uploading the file to the playground and using the playground as test data.

**Inputs and outputs**

The debugger enables you to temporarily override inputs and outputs for a playbook run and to view the results in real time. When you override an input or output in the debugger, the change is saved only in the debugger view and only for the user who made the change. If, after testing, you decide to keep the temporary changes you made, and apply them permanently to the playbook for all users, you need to cancel the override and edit the task. Tasks can be edited directly in the debugger or outside of the debugger using the standard playbook editing options.

**Breakpoints**

Breakpoints are used to pause playbook execution before a specific task. When the playbook is paused, the Debugger Panel displays the current state of context data, indicators, and task information.

At the breakpoint, you can override inputs and outputs to see how changes affect playbook execution.

In addition, conditional breakpoints set conditions for the playbook to proceed. The playbook only pauses if your condition is met, letting you manipulate data to see how different scenarios impact how the playbook runs. For example, you can set a conditional breakpoint to pause the playbook when a phishing incident targets a member of a VIP asset list. If there are no VIPs in this incident, the execution does not pause. If there is a VIP in the incident, you can check that the member was properly identified by the playbook task.

**Skip tasks**

For testing purposes, you might not want to close a port in a firewall, delete an email, or send a notification to a manager. For this purpose, you can skip a task. In other cases, you might skip a task where the integration has not yet been configured. By skipping a task and overriding the output, you can provide the data necessary to complete the playbook run. When you skip a conditional task, you can choose which branch runs after the skipped task, enabling you to test different outcomes for multiple branches.

**Sample Incident Generator**

The Sample Incident Generator enables testing different incident types. If you want to customize the generated incidents, you need to first duplicate the out of the box integration since out of the box content cannot be changed. You can then create custom incident JSON files to test multiple incident types.

![sample-incident-generator-custom.png](/files/s3mufm4941A2GauwFapp)

### **Debug a Playbook**

The Cortex XSOAR playbook debugger enables you to build, test, and troubleshoot playbooks. To open a detached system playbook, a copy of a system playbook, or a custom playbook in the debugger, select the playbook and click **Edit**. To open an attached playbook in the debugger, select the playbook and click **View** to access the debugger. While editing a playbook, sub-playbooks can be opened directly in the debugger by choosing **Open sub-playbook** in the task pane.

{% hint style="info" %}

### Note

The debugger runs with the permissions of the logged in user. If a user runs potentially harmful commands, they are logged to the audit trail with the user’s username.
{% endhint %}

In some cases, you may have a playbook that includes two or more copies of the same sub-playbook. When you set breakpoints, override inputs or outputs, or skip tasks in sub-playbook A, the same changes apply to the identical sub-playbook B. In addition, if you set a breakpoint, override inputs or outputs, or skip tasks within a loop in a playbook, that setting will be applied every time the loop executes.

(Multi-tenant) - The debugger cannot be run from the main account in a multi-tenant deployment.

**Choose Test Data**

By default, the debugger runs the playbook using an empty mock incident. Other options are to load the contents of the playground or choose an existing incident. Click **Debugger Panel** and for **Test data**, select the playground or an existing incident from the drop-down. The last fifty incidents appear in the dropdown list, as well as any incidents you own or are a member of, or that you have starred. You can enter a search term to find a specific incident from this list to use for test data.

{% hint style="info" %}

### Note

Using an existing incident in the debugger does not affect the original incident or change the original context data.
{% endhint %}

You can [create a new incident from a JSON file](/xsoar-6-administrator-guide/6.12/investigate-and-respond-to-threats/day-to-day-tasks-in-cortex-xsoar/incident-management/create-an-incident.md) using a Cortex XSOAR mapper. This can be useful in cases where you might not yet have an integration set up but you need to test a playbook with third-party event data. Once the new incident is created in Cortex XSOAR, you can select it from the list of incidents when choosing test data.

**Start and Stop the Debugger**

To start the debugger, click **Run**. When you click **Stop**, the debugger stops and the context data is reset to the original incident data. In the case of a new mock incident, the context data is cleared and the context is empty. Any breakpoints, skips, or overrides you applied are still available.

**Set a Breakpoint**

Breakpoints help you understand task results. Breakpoints do not apply to manual tasks, as a manual task will always pause the playbook run, unless you skip the manual task. When the playbook reaches a breakpoint, no new tasks begin, but parallel tasks that have already begun continue. Breakpoints can be set in both the parent playbook and sub-playbooks.

1. To set a breakpoint, click on the breakpoint button for a task. When a breakpoint is set, the breakpoint button changes to orange.

   ![debugger-breakpoint.png](/files/jjv3IBhZYtZS9Nxmtbbn)
2. Once a breakpoint is reached, click on the task to [override inputs and outputs](#UUID-dcce76ad-0717-7075-c0fe-4a954ae5d8a2_id7282ee13-34a0-4f3d-be10-225ce04668fb) if needed.
3. When you are finished with the task, select an option for the playbook to continue.

   For an automated task, you have the options **Run automation now** or **Complete Manually**. If you choose **Complete Manually**, click on **Mark Completed** for the playbook to continue.

   For a task that is a sub-playbook, click **Run playbook now** for the playbook to continue.

   For a conditional task, choose which branch the playbook should follow and click **Mark Completed** for the playbook to continue. The default branch is **else**.

   When the playbook reaches a breakpoint, the task has an orange line at the top to indicate the breakpoint.

   ![debugger-orange-line.png](/files/YVQMHJy3zwAqHctdtbhA)

   Breakpoint alerts are also displayed at the top of the playbook, enabling you to navigate between multiple breakpoints that have been reached in the playbook or sub-playbooks.

**Set a Conditional Breakpoint**

Conditional breakpoints enable you to debug loops and tasks with multiple values. The playbook only pauses if your condition is met, letting you manipulate data to see how different scenarios impact the playbook run.

1. Click on the breakpoint button for a task.

   Once a breakpoint is set and the breakpoint icon is orange, a tooltip appears enabling you to add a condition to the breakpoint.

   ![debugger-conditional-breakpoint.png](/files/vvWWynQPAGXnnC1gXEyt)
2. On both sides of the condition statement, you can choose available playbook data **From previous tasks** or use **As value** to set any other value.

   Clicking on the curly brackets enables you to use data from the current playbook and from sub-playbooks.

   ![debugger-conditonal-breakpoint-settings.png](/files/jHTthLOEaT6rGYICapGB)
3. Click on the **Equals (String)** to select from a set of conditions (contains, ends with, greater than, etc.)

   Note - If the breakpoint condition as defined does not exist when the debugger runs, the condition will default to false. For example, if you choose IP address and there is no IP address available, the playbook will not pause.
4. Click **Save** to save your conditional breakpoint.

**Override Inputs and Outputs**

You can override task inputs or outputs before or during a playbook run, to troubleshoot tasks that fail and to test different options for playbook development. If you override an input or output during a playbook run, the override is applied to the run if the playbook has not yet reached that task. If you edit (permanently change) inputs during a playbook run, the changes only take effect the next time you run the playbook. You cannot use filters or transformers for overrides.

1. To override an input or output, open the task and hover over any existing input or output. Click on the **Override** button.

   ![debugger-override-input.png](/files/JU1WONYBnyrfQEDiPbek)
2. Enter a new input or output that will be used only in the debugger. For output overrides, you can enter a value, an array of values, or JSON. For input overrides, you can only enter plain text.
3. Click **OK** to save your changes.

   The playbook task card displays a label indicating that the task input or output has been overridden.

**Skip Tasks**

You might need to skip tasks within a playbook:

* To check if a particular task is causing an issue.
* To avoid performing tasks not relevant for your troubleshooting.
* To skip tasks with potentially harmful results such as blocking a user or opening a port in a firewall.
* To skip tasks for integrations that are not yet configured.

1. To skip a task, click the ‘skip’ button for the task.

   When a task is set to skip, the ‘skip’ button will be orange.

   ![debugger-skip-task.png](/files/NwhuFgDCyY4JNpr9MPT8)
2. If output is required for the playbook to proceed, click on the task and [Override Inputs and Outputs](#UUID-dcce76ad-0717-7075-c0fe-4a954ae5d8a2_id7282ee13-34a0-4f3d-be10-225ce04668fb).

**Skip Conditional Tasks**

When you skip a conditional task, you can set which branch runs after the skipped task, enabling you to test different outcomes for multiple branches.

1. Choose **skip** for a conditional task. The **skip** button will turn orange.
2. Click on the task. Select which branch runs after the skipped task. If you do not choose, the else branch runs by default.

   ![debugger-skip-condition-path.png](/files/MyQUjKo7APOhtbxkwhXf)
3. Click **OK**to save your changes.

**View Context Data, Indicators, and Task Information**

Within the debugger panel, you can view the context data during the playbook run, as well as the indicators as they are extracted.

* Click on any completed task in the playbook, while the debugger is running.

  View the results of that task in the debugger panel.

  ![debugger-panel.png](/files/xQckY4WYHzHXsvBlDWux)

### **Debugger Troubleshooting**

**User Permissions**

The debugger runs with the permissions of the logged in user. The user must have permissions for both **`PlaybooksRW`** and **`InvestigationRW`** to run the debugger.

**Debugger Worker Pool**

The playbook debugger has a separate worker pool. If you have many users running debugger sessions at the same time, and there are performance issues, you can increase the number of workers. To change the number of workers, go to Settings → About → Troubleshooting → **Server Configuration** and add the server configuration **`workers.count.Debug`**. The default number of workers is 1.

**Terminate Debugger Sessions**

By default, every 24 hours, the system closes any debugger sessions that have been open for more than 180 minutes. You can change the frequency of the automatic terminations and also the length of time a debugger session can remain open. To change the default from 24 hours, go to Settings → About → Troubleshooting → **Server Configuration** and add the server configuration **`clean.playbook.debug.sessions.interval`**. The unit is hours.. To change the maximum time a debugger session can remain open, add the server configuration **`playbook.debug.sessions.duration.max`**. The unit is minutes.

The default admin can close either all debugger sessions or a specific user’s debugger sessions through the API.

* To close all debugger sessions, send a POST request to the endpoint **`/debugsession/remove`**.
* To close only the debugger sessions for a specific user, include the following request parameter in the body of the request **`{"username": "`*****`CHOSEN_USERNAME`*****`"}`**. Note that if no user is specified in the request, all open debugger sessions for all users will be terminated.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xsoar-6-administrator-guide/6.12/configure-cortex-xsoar/customize-and-configure-cortex-xsoar/playbooks/playbook-testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.