> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/development-cycle/build-overview/canvas/test-cases.md).

# Test Cases

Discover how to build effective test scenarios for different integration cases.

A **Test Case** is a configuration that includes a defined set of inputs, conditions, and expected outcomes used to verify that a specific integration pipeline is working as intended. Test cases are especially useful for ensuring the quality of your integrations and documenting the expected behavior of your flows.

They allow you to:

* Simulate various input conditions.
* Mock step responses.
* Validate the output of the pipeline or of any step.
* Automatically compare actual and expected results.

## **Creating Test Cases**

1. In the Design toolbar on Canvas, click **Test Cases**, right below **Flow**.
2. In the **Test Cases** panel, click **Create new**.

{% stepper %}
{% step %}

### Document the test

When creating a test case, start by providing the following information:

* **Name:** A unique name to identify the test case later.
* **Description:** A brief explanation of the test case. Use this field to document the purpose or specific scenario being tested.
* **Group:** A group to organize the test case. Click **Create your first group** to start grouping your test cases or select an existing group to assign your test case.
  {% endstep %}

{% step %}

### **Define the conditions**

Then, you must configure the elements that define the test scenario:

#### **Payload**

The payload represents the input data for your test. When adding a payload, provide the following:

* **JSON:** The input data in JSON format. You can also reuse [payloads previously saved in the Execution Panel](https://docs.digibee.com/documentation/development-cycle/build-overview/canvas/execution-panel.md) of the pipeline by clicking **Load to edit**.
* **Name:** A name for the payload.
* **Description:** A short description explaining the context or purpose of the payload.

#### **Mock Response**

Mock responses let you replace a step's response with simulated data, so the step doesn't call the external system. The following steps receive the mocked data as the step's output, which is helpful when validating flows under different conditions. When adding a mock response, provide the following:

* **Step:** The step whose response you want to mock. Each step appears by name, with the connector type below.
* **JSON:** The simulated response, in JSON format.
* **Name:** A name for the mock response.
* **Description:** A brief explanation of the scenario represented by this mock.

To mock more steps, click **Add more mocks**.

#### **Expected Results**

The expected result defines the output the flow should produce after execution. It is used to validate the execution by comparing the actual result with the expected one through configurable conditions and operators.

Start by providing the following information:

* **Name:** A name to identify the assertion in the test results. Use a descriptive name, such as `Shipping fee calculated`, so you can tell the assertions apart when reviewing the results.
* **Description:** A brief explanation of what is being validated.
* **Step:** The output the assertion validates. Keep **Pipeline output**, the default option, to validate the final output of the pipeline, or select a step to validate the output of that step. The list includes every step on the Canvas, including steps inside **For Each**, **Choice**, and **Block Execution**. You can add more than one assertion to the same step.

After that, add one or more conditions. Configure the following fields:

* **JSONPath:** The JSONPath expression that points to the field to be evaluated in the selected output.
* **Operator:** The comparison operator used to validate the result. The available options are:
  * **Equals, Not Equals:** Checks whether the returned value is equal to or different from the expected value.
  * **Greater Than, Greater Than Or Equal:** Checks whether the returned value is greater than or greater than or equal to the expected value.
  * **Less Than, Less Than Or Equal:** Checks whether the returned value is less than or less than or equal to the expected value.
  * **Is True, Is False:** Validates whether the returned value is a boolean set to `true` or `false`.
  * **Is Null, Not Null:** Validates whether the returned value is `null` or defined.
  * **In, Not In:** Validates whether the returned value belongs to or does not belong to a defined set of values.
  * **Is Empty, Is Not Empty:** Checks whether the returned value is empty or contains at least one value, element, or property.
  * **Contains, Not Contains:** Checks whether the returned value includes or does not include the expected content.
* **Value:** The expected value to be compared. This can be a Simple Value or a JSON Object. Use the toggle in the field to switch between formats.

{% hint style="info" %}
Some operators perform state checks and don’t require a value, such as **Is True**, **Is False**, **Is Null**, **Not Null**, **Is Empty**, and **Is Not Empty**.
{% endhint %}

To add more conditions, click **Add condition**. The conditions are grouped, and you can combine them using the following logical operators:

* `AND`
* `OR`

After you save the expected result, it appears in the test case's side sheet with the name and icon of the step it validates. If it validates the final output, it appears as **Pipeline output**. The expected result stays linked to its step even if you rename the step. To add more expected results to the test case, click **Add a new assertion**.

If you remove the step from the pipeline, the expected result shows the warning **Step not found in the pipeline**. To fix it, edit the expected result and select another step or **Pipeline output**, or remove the expected result.
{% endstep %}

{% step %}

### **Save the test**

Once all required information has been provided, click **Save**.

{% hint style="info" %}
The test case must contain at least the name and the expected result to be saved.
{% endhint %}

The test case then appears in the **Test Cases** panel, on the left side. Click a test case to open it, or click the three-dots icon to:

* **Edit:** Modify the test case settings.
* **Remove:** Delete the test case.
* **Duplicate:** Make a copy of the test case.
* **Single Run:** Execute the test case.
* **Open execution:** See information about the test case result. Only available after the test case is executed.
  {% endstep %}
  {% endstepper %}

## **Running Test Cases**

Running test cases allows you to validate your flow and quickly identify differences between the expected and actual results. You can execute one or multiple test cases at a time, depending on what you want to verify.

### **How to execute one test case**

To execute one test case:

1. Ensure the flow is connected to a trigger. If the flow isn't connected, the test case won't run.
2. In the **Test Cases** panel, find the test case you want to run, click the three dots, and select **Single Run**.
3. The Platform runs the test, compares the actual output with the expected result, and opens the results in the **Test Case Panel**.

### **How to execute multiple test cases**

To execute multiple test cases:

1. Ensure the flow is connected to a trigger. If the flow isn't connected, the test cases won't run.
2. In the **Test Cases** panel, select the checkbox next to each test case you want to execute, or click **Select all**.
3. On the **Execution Panel**, click **Play (n)**, where **"n"** indicates the number of selected test cases.
4. The Platform runs the tests, compares the actual output with the expected result, and opens the results in the **Test Case Panel**.

## **Reviewing test results**

After you run one or more test cases, the panel at the bottom of the Canvas shows a switch between **Execution Panel** and **Test Case Panel**. **Test Case Panel** opens automatically and shows the whole run in one place.

The panel starts with a summary of the run, for example `12 test cases · 5 passed · 7 failed`. Below it, each test case that ran appears in its own row, in the same order as the **Test Cases** panel. Each row shows:

* The status of the test case: **Success** or **Fail**. A test case succeeds only if all its assertions pass.
* The test case name.
* The number of assertions that passed out of the total.
* The list of assertions, with the status of each one. When an assertion fails, the message compares the expected and the actual values.

Some assertions need extra attention:

* **Assertions on steps that didn't run:** If the target step isn't executed, for example because the flow followed another path in a **Choice** or stopped at an error before reaching it, the assertion is marked as **Step ‘VIP Branch’ was not executed** and the test case fails.
* **Assertions on steps that run more than once:** When the target step is inside a loop, such as a **For Each**, every execution must pass. If any execution fails, the message shows how many failed and the actual value of the first failure, for example: `1 of 3 executions failed. First failure on execution 2: expected != '0' but got '0'`.

Failed rows start expanded, and passed rows start collapsed. Each row also offers two actions:

* **View execution:** Switches to **Execution Panel** and shows the Input and Output of that test case in the **Results** tab.
* **Edit:** Opens the test case configuration.

### **Inspecting each execution**

Each test case in a run has its own execution. To see the Input and Output of a test case in the **Results** tab, select it in the execution selector at the top of the **Execution Panel**, or click the three dots next to it in the **Test Cases** panel and select **View execution**. The selector starts on the first failed test case.

The **Logs** and **Messages** tabs show the data of the whole run, not only of the selected test case, and are available only for the latest run.

## **Examples of Test Cases**

The following examples illustrate different types of test cases you can create to validate your flow.

### **Scenario: Add default birth date**

* **Use case:** You want to ensure that a default birth date is added when the input JSON is missing.
* **Objective:** Use the **Transformer (JOLT) V2** to add a default `"birthDate": "01/01/1970"` field when it’s not present in the input.

#### **Pipeline overview**

This pipeline uses a single connector:

* [**Transformer (JOLT) V2**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/jolt-v2.md)**:** Adds a default birth date if it’s missing from the input payload.

We’ll test this transformation using a test case with a sample input that lacks the `birthDate` field.

#### **Step 1: Configure the Transformer JOLT (V2)**

We’ll use the `default` operation to add a field when it doesn't already exist.

**JOLT specification:**

```json
[    
 {
   "operation": "default",
   "spec": {
     "customer": {
       "birthDate": "01/01/1970"
     }
   }
 }
]
```

This spec checks if `birthDate` exists under `customer`. If not, it adds it with the default value `”01/01/1970”`.

#### **Step 2: Create the Test Case**

We'll simulate a payload that contains only the name and SSN, and verify that the Transformer (JOLT) V2 connector adds the default birth date.

* **Payload:**

```json
{
 "customer": {
   "name": "Customer Default",
   "ssn": "123-45-6789"
 }
}
```

* **Mock response:** *(Leave empty for this example)*
* **Expected result:**
  * **Step:** Pipeline output
  * **JSONPath:** `$.customer`
  * **Value:**

```json
{
   "name": "Customer Default",
   "ssn": "123-45-6789",
   "birthDate": "01/01/1970"
}
```

#### **Result validation**

After running the test case, the output is as follows:

```json
{
  "customer": {
    "name": "Customer Default",
    "ssn": "123-45-6789",
    "birthDate": "01/01/1970"
  }
}
```

This confirms that the test passed:

* The **Transformer (JOLT) V2** applied the `default` operation as expected.
* Since the original input didn’t include a `birthDate`, the field was added with the default value `”01/01/1970”`.

### **Scenario: Organize product catalog**

* **Use case:** You want to restructure product data returned from a database into a new format.
* **Objective:** Group product details under a `details` object and rename fields for better organization.

#### **Pipeline overview**

This pipeline uses the following connectors:

1. [**DB V2**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/structured-data/db-v2.md): Retrieves product data.
2. [**Transformer (JOLT) V2**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/tools/jolt-v2.md): Reorganizes and renames the fields using the `shift` operation.

As we don’t have access to the actual database, we’ll simulate it using a test case with a mocked DB response.

#### **Step 1: Configure the Transformer JOLT (V2)**

We’ll use a JOLT `shift` operation to map and reorganize the fields.

**JOLT specification:**

```json
[
  {
    "operation": "shift",
    "spec": {
      "product": {
        "id": "productId",
        "name": "details.name",
        "brand": "details.brand",
        "price": "details.pricing.amount",
        "currency": "details.pricing.currency",
        "stock": "details.availability"
      }
    }
  }
]
```

This spec renames `id` to `productId` and nests other fields under a `details` object.

#### **Step 2: Create the Test Case**

We'll simulate the database response and validate the transformation.

* **Payload:** *(Leave empty for this example)*
* **Mock response:**
  * **Step:** DB V2
  * **JSON:**

```json
{
  "product": {
    "id": "12345",
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "price": 699.99,
    "currency": "USD",
    "stock": 25
  }
}
```

* **Expected result:**
  * **Step:** Pipeline output
  * **JSONPath:** `$.details`
  * **Value:**

```json
{
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "pricing": {
      "amount": 699.99,
      "currency": "USD"
    },
    "availability": 25
  }
```

#### **Result validation**

After running the test case, the output is as follows:

```json
{
  "productId": "12345",
  "details": {
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "pricing": {
      "amount": 699.99,
      "currency": "USD"
    },
    "availability": 25
  }
}
```

This confirms that the test passed:

* The **Transformer (JOLT) V2** applied the specification correctly to restructure the input data.
* Fields were renamed and nested under the `details` object as intended.
* The `productId` field remained at the top level, while other attributes were grouped logically under `details`.


---

# 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.digibee.com/documentation/development-cycle/build-overview/canvas/test-cases.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.
