> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/guides/development/how-to-test-processes-and-tasks.md).

# How to test Processes and Tasks

How to run single Tasks and Processes for testing.

Testing is a core part of building integrations in Frends. The platform provides two complementary testing tools that fit directly into the development workflow: the Test panel in the Process Editor, which lets you verify a single Task's configuration in isolation, and the Run once feature, which executes the full Process so you can validate the complete flow. Used together, they make it straightforward to catch issues early and narrow down problems quickly.

## Requirements

Both testing features require an active Agent in the Agent Group you are targeting. Without a running Agent, neither Tasks nor Processes can execute.

To test a Task with the Test panel, the Agent Group must also have the **Allow running test Processes** setting enabled. This is found in the advanced settings of the Agent Group configuration under **Administration** > **Environments**. The default Development Agent Group has this enabled out of the box.

Your Process must be saved before it can be executed with Run once. Frends validates the Process on save, so a successful save confirms the Process is ready to run.

## Testing a Task in the Process Editor

When you are building a Process, it helps to know early that a single Task does what you expect. The Test panel in the Process Editor lets you run one Task with sample values, right where you are working, and see what it returns. In this walkthrough we test an HTTP Request Task that fetches customers from an example API. The same steps work for any Task. If you want the technical details of the panel, see [Task Unit Testing](https://docs.frends.com/reference/process-development/task-unit-testing.md).

### Before you start

You need an Agent running in the Agent Group you test in, and the Agent Group needs the **Allow running test Processes** setting turned on, as described in the Requirements section above. The Development Agent Group has the setting turned on by default, so you most likely do not need to change anything.

### Open the Test panel

Open the Process in the Process Editor and click the Task shape you want to test. In our example this is the HTTP Request Task. The Task parameters open in the sidebar on the right. Scroll to the bottom of the parameters and click **Create new test**, which is just above **Show advanced settings**. The **Test** panel opens next to the Task parameters.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FnNpUGl4cgBV2aVns5JOx%2Fframed_20261109-122733.png?alt=media&amp;token=ab52f56c-2c1a-4ae9-a44f-45c6f1e51f12" alt=""><figcaption><p>Create new test opens the Test panel for the selected Task.</p></figcaption></figure>

### Enter the test values

The **Parameters** tab has the same fields as the Task parameters, but anything you type here is used only by the test. Your Process is not changed. If the Process normally gets a value from somewhere else, for example from the Trigger or from a Process Variable, type a sample value here instead.

Take a look at the **Execute in selected agent group** dropdown at the top of the panel as well. It shows where the test runs, and in most cases the Development Agent Group is what you want.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2F4g9kKJDhFqTlQwbdGZWl%2Fframed_20261109-144626.png?alt=media&amp;token=d69cb649-7063-48fe-92c3-94833662fb61" alt=""><figcaption><p>Test values are typed on the Parameters tab.</p></figcaption></figure>

### Run the test

Click **Run**. Frends runs the Task on an Agent in the selected Agent Group, and the outcome appears on the **Result** tab when the Task is ready. If a test takes longer than you expected, click **Stop** to end it. You can change the values and click **Run** again as many times as you like.

### What the results look like

Depending on the values and the Task, a test ends in one of a few ways. Here is what each looks like and what to do next.

#### A successful result

When the Task completes, the **Result** tab shows the full result object, in the same form you would see in a Process Instance. For our HTTP Request example this includes the response body, and you can expand it to look at the individual properties. If the result looks the way you expected, the Task is ready to be connected to the rest of your Process.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2Fu0SQwIVYMQ6VmEvPkaCu%2Fimage.png?alt=media&amp;token=32405bcb-e936-4dae-b749-a0faf4236b99" alt=""><figcaption><p>A successful test shows the full result object.</p></figcaption></figure>

#### An error from the Task

If the Task itself runs into a problem, the **Result** tab shows the error message and the details instead of a result. For example, an HTTP Request to an address that cannot be reached ends this way. Read the message, correct the values on the **Parameters** tab and run the test again.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FUuq5ApGvrXth2sAsm5ZB%2Fframed_20261109-145100.png?alt=media&amp;token=65cb5e8d-5a77-4c42-9f7d-5f5be8718c3d" alt=""><figcaption><p>A failed test shows the error message and details.</p></figcaption></figure>

#### A reference that is not available

A test runs only the Task, so references to data from other parts of the Process, such as `#var`, `#result` or Trigger data, do not work. If a parameter uses one, the test fails and the error is shown on the **Result** tab. The fix is to type a sample value for that parameter on the **Parameters** tab. Your Process keeps using the original reference. For example, if a Sleep Task takes its **Seconds** from `#var.seconds`, type `2` in the test.

#### A missing Environment Variable

Parameters can refer to Environment Variables with `#env`, for example for a password or an API key, and this works in a test. The variable has to be saved first, though. If it is not, the test fails with a variable not found error. Save the variable on the Environment Variables page and run the test again.

### When to use something else

The Test panel runs one Task at a time, so it cannot show how Tasks work together, and the Call Subprocess shape cannot be tested with it. To check the whole flow, or to test a Subprocess, use Run once, described in the next section.

## Testing the Full Process with Run Once

Once individual Tasks are working correctly, the next step is validating the full Process flow. The Run once feature lets you manually execute any Process without relying on an automated Trigger. This is the primary method for integration testing during development.

<details>

<summary>How to Manually Execute a Process</summary>

In order to run a Process when you need it, instead of relying on automation from the different Triggers, there's a useful action called **Run once** for the Processes and Subprocesses in Frends. This will execute the Process with the Manual Trigger commonly available in Processes.

## Step by Step Tutorial Available

If you prefer more visual or interactive guidance on how to run Processes manually in Frends, you can find a step-by-step walkthrough from your own environment's home page, under Onboarding by selecting "Tutorial 1, Step 4: Running the Process" tutorial.

## Requirements

To run a Process manually or automatically through Triggers, an Agent is required in the Agent Group the Process is deployed to. Agents are what actually perform the actions defined within Processes, so in addition to Environment and Agent Group, you will also need an Agent on a server or computer to run Processes.

Frends at a minimum comes with Development Environment with a Cloud Agent set up, so it's not required to have your own Agents running to follow this guide, but for other purposes than light testing or development, it's recommended to set up your own Agent as well.

Having a Manual Trigger in Process is *not* required. In case there is no Manual Trigger in a Process, an implicit Manual Trigger with no parameters will be used to trigger the Process. However, if the Process expects some values from an API Trigger for example, the values cannot be provided and the Process execution will likely fail.

## How to run Process once

In order to run a Process manually, head over to Process list and select the Agent Group you would like to execute the Process in.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2Fg76P6ncOASFLI0OTFGdv%2Fimage.png?alt=media&amp;token=dc5386a5-26bc-4803-a13b-0d00834f14eb" alt="Use the Agent Group selection in Process list to change displayed Agent Group and its Processes."><figcaption><p>Use the Agent Group selection in Process list to change displayed Agent Group and its Processes.</p></figcaption></figure>

When correct Agent Group is selected, find your Process from the Process list and click on the ellipsis button to open Process actions.

You can then select **Run once** to launch the Process.&#x20;

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FjlCcqT5AliolhwW5dhE9%2Fscreenshot-rocks%20(47).png?alt=media&amp;token=72af0bcf-bd4b-4516-bc35-065b08bbbc00" alt="Picture highlighting the Run once option in Process actions."><figcaption><p>Run once option is the first on the Process actions list.</p></figcaption></figure>

In case there are any parameters defined in the Process's Manual Trigger, the values will be prompted from the user before starting the Process. If there are no parameters defined, the Process will launch immediately.

Once the Process has started execution, you can go ahead and open the Process Instances for the Process to see what is being done within the Process execution.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FViiJvuC1Cxpyuw3aeU0n%2Fimage.png?alt=media&amp;token=c480c40f-0832-4ff9-801f-1ca5322a48c7" alt="Picture shows an example of parameters being prompted in a modal dialog."><figcaption><p>Example of parameters being prompted for manual execution. </p></figcaption></figure>

</details>

### Viewing Process Instance Results

After execution, navigate to Process Instances to see the results.

<details>

<summary>How to View Process Instances</summary>

In order to see what happened during integration flow execution, Frends has a view called Process Instance.&#x20;

## Step by Step Tutorial Available

If you prefer more visual or interactive guidance on how to view Process logs with Frends, you can find a step-by-step walkthrough from your own environment's home page, under Onboarding by selecting  "Tutorial 2b, Step 2: Process Logs" tour.&#x20;

## Accessing process instances

The Process Instances are accessible through Process list by selecting **Show Process instances**. You can also access the Process Instance list by clicking on **Last execution** or **Instance counts per day** columns from the Process list.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FFuqc3HwJmENeMhBXl1lY%2Fscreenshot-rocks%20(38).png?alt=media&amp;token=450ebc25-f5de-45ce-8b81-32028f86f73e" alt="How to access Process Instances from Process List."><figcaption><p>How to access Process Instances from Process list.</p></figcaption></figure>

Then selecting any of the Process Instances on the Process Instance list will take you to the chosen execution's Instance view.&#x20;

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2Fxbt8lgeer0st1tPh0Hd9%2Fscreenshot-rocks%20(39).png?alt=media&amp;token=4207f3c2-3502-4646-baa8-977dbb08f4c1" alt="A view of the Process Instance list with filters."><figcaption><p>Process Instance list view.</p></figcaption></figure>

## Viewing Multiple Processes' Instances at once

In order to see Instances for multiple Processes at once, you can use the bulk actions for Processes. Simply select the wanted (or all) Processes using the checkboxes in Process List view, select **Actions** from the top of the list, and finally select **Show Process Instances** from the menu.&#x20;

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2F4mwu8rRcUe5YlUL6su6I%2Fimage.png?alt=media&amp;token=8395adfe-a4b6-4d98-b3a3-9548d04cb678" alt=""><figcaption><p>Opening Process Instance List view for multiple Processes.</p></figcaption></figure>

Opening the Process Instance list this way allows you to view and filter multiple Processes' Instances at once, showing for example the lifecycle of a specific Order ID through multiple Processes in one view.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2F84NeCYjCZgvo22lY0RrE%2Fscreenshot-rocks%20-%202026-05-29T123900.213.png?alt=media&amp;token=05f0ae2c-03a3-47eb-aac3-d31ba91d68ab" alt=""><figcaption><p>Process Instance List showing executions for multiple Processes.</p></figcaption></figure>

## Process Instance list filters

In the Process Instance list, you can filter the shown Instances using time period and the state of the Process Instance. The search also supports searching for results and values promoted from the Process execution using SQL wildcards.&#x20;

The Instance list is automatically refreshed by default, to show the current state of the executions in almost real time. In case there are a lot of executions happening, setting the **Auto refresh** to Off might help in focusing on the earlier executions.

## Process Instance view usage

From the Process Instance view it is possible to see what happened at each stage of the execution, shape by shape.&#x20;

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FYt66yHm33mzY4sSGHXbl%2Fscreenshot-rocks%20(40).png?alt=media&amp;token=fd5ff31d-8977-4027-a0e5-52146391c152" alt="Example process execution view"><figcaption><p>Example Process Instance view.</p></figcaption></figure>

From the view, it's possible to click on the Process elements to see details of that part of the Process. Depending on logging settings in the Process as well as in the Agent Group, some details of the execution might not be always visible.

Functionality in the Process Instance view is similar to Process Editor view, but instead of allowing editing the Process and shape details, it shows what happened during the execution.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FgZ97vUcQrikZdBUpG1av%2Fscreenshot-rocks%20(41).png?alt=media&amp;token=a6ccf669-30d4-457b-af30-6f57ab77986e" alt="Process execution view with HTTP Request Task selected."><figcaption><p>Process Instance view with HTTP Request Task selected. </p></figcaption></figure>

Common information shown for each shape are:

* **Start time**, when the execution of chosen shape was started
* **Duration**, how long the execution took for that shape
* **Task** or **Expression**, what was executed
* **Result**, showing what was the result of the execution

If extended logging is enabled for the Process or Agent Group (**Log everything** in Log settings), the input parameters are also logged and shown here. Because extended logging has some impact on performance, this level of logging is recommended to be used only temporarily. The Log settings provide an easy way to set Log everything for only a specified duration.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FHb1UEmyXaTTAAMP9JtqY%2Fscreenshot-rocks%20(42).png?alt=media&amp;token=46232f97-e8c6-404b-90e4-d4dbef510f7c" alt="Extended parameter logging is available when Log Everything option is selected."><figcaption><p>Extended information shown for the executed Task, when "Log everything" is set.</p></figcaption></figure>

It's also possible that log settings were adjusted so that **Only errors** are logged, or **Skip logging result and parameters** is enabled for some elements in the Process. In these situations details for successful shape executions are not logged. This is useful for production use, when there can be many and more executions and as long as there are no errors, most details of the executions are not needed.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FsZF6QBAxJRkOlneBJAuP%2Fscreenshot-rocks%20(43).png?alt=media&amp;token=e436afeb-575f-42be-810d-7ab97067bd60" alt="If Errors Only log level is selected, nothing but errors and basic details are logged for executions."><figcaption><p>No data shown for the Process execution with "Only errors" log level set.</p></figcaption></figure>

</details>

### Adjusting Log Levels for Testing

The amount of detail available in a Process Instance depends on the log level set for the Process or its Agent Group. The **Default** level logs the result of each shape and is sufficient for most testing. **Log everything** additionally logs all input parameters and does not truncate large values, providing the fullest picture during development. **Only errors** skips all successful step details and only logs information when an exception occurs.

For testing, **Log everything** gives the most visibility. You can enable it with a time limit — for example, two hours — after which it automatically reverts to the default. This prevents verbose logging from being left on unintentionally.

### Using Promoted Values

Promoted values surface specific data from a Process directly in the Process Instance list without requiring you to open each execution. When a shape is configured to promote its result, the value appears as a searchable column in the list. This is helpful when running repeated test executions and tracking a specific identifier or value across them.

Promoted values are always logged regardless of the current log level, even when the Agent Group is set to Only errors. This makes them a reliable debugging aid in any environment.

### Skip Logging for Sensitive Data

When a shape handles sensitive data such as passwords, authentication tokens, or personally identifiable information, you can configure it to skip logging its result and parameters. Each shape includes a **Skip logging result and parameters** toggle option under **Advanced settings**.

This option, when enabled, prevents that data from being written to Process Instances. When testing Processes that handle sensitive data, consider using anonymised or dummy values so that full logging can be enabled without exposing real credentials or personal data.

### Interpreting Process Test Results

A green Process Instance status indicates a successful execution. A red status means the Process ended with an unhandled error. Click on the failed shape to read the error message and, where available, the stack trace, which typically points directly to the cause.

When a Process completes without errors but produces unexpected results, use the logged Task outputs to trace the data through each step. Compare the input to each shape with its output to identify where a transformation or mapping is producing the wrong value. If no data is shown for a shape, it is likely the log level is set to Only errors and the shape completed without errors. Switching temporarily to Log everything will make all step details visible on the next test run.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/guides/development/how-to-test-processes-and-tasks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
