---
id: test--flow-test
title: "Flow test case"
summary: "Defines one test case in a **Test** flow. When the test flow runs, every Flow test case component is started in turn; it triggers the components connected to it, waits until they have finished, and the test passes or fails depending on whether an exception was thrown."
audience: user
keywords: "starter pin, test to start, executetest, successonexception"
---
# Flow test case

Defines one test case in a **Test** flow. When the test flow runs, every Flow test case component is started in turn; it triggers the components connected to it, waits until they have finished, and the test passes or fails depending on whether an exception was thrown.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Starter pin | start | - | Called by the test runner. Leave it unconnected. |
| Test to start | output | `Viaducta.Plugins.FlowTest.Types.TestPluginData` | Starts the test: emits `TestPluginData { TestName }` with the component name. Connect the components that make up the test. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `ExecuteTest` | boolean | `true` | `false` skips the test: nothing is emitted. |
| `SuccessOnException` | boolean | `false` | `true` turns the expectation around: the test is successful when the tested components throw (negative tests); an exception is then not reported as a failure. |

## Behaviour

- Only flows of kind Test run test cases. The runner finds all Flow test case components and runs them **one after another**; other start components of the flow are not started. A test flow without Flow test case components reports "There are no test flow components in the flow that can be started directly".
- The test name is the **component name**; name each test case meaningfully. It is also put into the metadata (`TestInfo.TestName`) so downstream components and logs know which test is running.
- The component sends `TestPluginData` on `Test to start` and waits until the whole downstream chain has finished. While waiting it shows the elapsed time ("Time:... ms") as status; time is not counted while the flow is paused in the debugger.
- Result: the test **fails** if any downstream component throws an exception (unless `SuccessOnException` is `true`), otherwise it **passes**. The results are collected by the test runner and shown in the designer when all tests have finished; the flow then stops.

## Notes

- Assertions are made by throwing: put a C# script (or another plugin that fails on bad data) at the end of the chain that checks the result and throws an exception when it is wrong.
- Components that hand work to background tasks or listeners (servers, timers) may finish "successfully" before their work is done; test request/response logic with clients and direct calls.
- Each test case should prepare its own data (e.g. a script or a database writer at the start of the chain), since all tests run in the same flow instance one after the other.

## Example

```json
{ "ExecuteTest": true, "SuccessOnException": false }
```

**Flow test case** "Order total is calculated" → C# script (build test order) → Data mapper (component under test) → C# script (throw if `Total` != 150)