# On unit test event

Unit test event triggers run a pipeline when a unit test session ends. Filter by branch, test suite, and session status to publish only after tests pass or to react to failures.

Unit test event triggers let you run a pipeline when a [unit test](/docs/tests/unit-tests.md) session ends. Buddy starts all pipelines whose trigger matches the session's branch, test suite, and status - for example, publish an artifact only after the suite passes, or open a ticket when it fails.

There is one unit test event type:

- **Unit Tests: Session ended** - triggered when a test session finishes, regardless of its result. Use **Statuses** to narrow it down.

## Configure trigger

1. Open your pipeline and go to the **Workflow** tab.
2. Click **+** in the **Triggers** section and select **Session ended** in the **Unit Tests** group.

   ![Unit Tests group in the trigger dropdown](/docs/pipelines/triggering-pipelines/triggering-pipelines-unit-tests-dropdown.png 640x767)

3. Set the **Suite**, **Branch**, and **Session statuses** the trigger should react to.
4. Click **Apply changes**.

The trigger appears in the **Triggers** section with the selected suite, branch, and statuses:

![Unit tests trigger in the pipeline workflow](/docs/pipelines/triggering-pipelines/triggering-pipelines-unit-tests-trigger.png 640x603)

## Filters

Each filter is a list. The trigger fires when the session matches at least one entry in every list.

![Unit tests trigger filters: suite, branch, and session statuses](/docs/pipelines/triggering-pipelines/triggering-pipelines-unit-tests-filters.png 640x603)

- **Suite** - the [test suites](/docs/tests/unit-tests/setup-and-reporters.md) that should start the pipeline. Pick them from the list, tick **All suites**, or switch to **Wildcard** and type a pattern; `*` matches any suite. Suites are matched by their **ID**, shown next to the name in the suite's settings, not by the display name.
- **Branch** - branches the test session was reported for. Pick them from the list, tick **All branches**, or switch to **Wildcard**, e.g. `release/*`.
- **Session statuses** - session results that fire the trigger: **Error**, **Successful**, **Skipped**.

## YAML

The event type is `UT_SESSION_ENDED`. The `suites` list takes suite **IDs** (e.g. `api_tests`), not display names - you can find the ID in the suite's settings, next to its name:

```yaml
- pipeline: "Deploy to production"
  refs:
    - "refs/heads/master"
  events:
    - type: "UT_SESSION_ENDED"
      branches:
        - "master"
      suites:
        - "api_tests"
      statuses:
        - "SUCCESSFUL"
  actions:
    - action: "Upload build"
      type: "FTP"
      target: "prod-server"
      local_path: "dist/"
      remote_path: "/var/www/app"
    - action: "Restart service"
      type: "SSH_COMMAND"
      target: "prod-server"
      commands:
        - "systemctl restart app"
```

Every filter accepts several values and wildcards. This pipeline reacts to any suite on any branch, but only when the session failed or was skipped, and posts a message to Slack:

```yaml
- pipeline: "Tests failed"
  refs:
    - "*"
  events:
    - type: "UT_SESSION_ENDED"
      branches:
        - "*"
      suites:
        - "*"
      statuses:
        - "ERROR"
        - "SKIPPED"
  actions:
    - action: "Notify team"
      type: "SLACK"
      integration: "slack"
      channel: "C0123456789"
      content: "Unit tests failed on $BUDDY_RUN_BRANCH"
```

<Hint type="info">
The test session itself is produced by another pipeline that runs the [unit tests action](/docs/tests/unit-tests/pipeline-integration.md) or by uploading results with [`bdy tests unit upload`](/docs/cli/tests/unit/upload.md). The trigger reacts to the session, not to the pipeline that ran the tests.
</Hint>

## See also

- [Unit Tests](/docs/tests/unit-tests.md)
- [Unit Tests in Pipeline](/docs/tests/unit-tests/pipeline-integration.md)
- [On sandbox event](/docs/pipelines/introduction/triggering-pipelines/on-sandbox-event.md)
- [On artifact event](/docs/pipelines/introduction/triggering-pipelines/on-artifact-event.md)
- [On environment event](/docs/pipelines/introduction/triggering-pipelines/on-environment-event.md)
- [Trigger pipeline action](/docs/pipelines/introduction/triggering-pipelines/trigger-pipeline-action.md)


---
Original source: https://buddy.works/docs/pipelines/introduction/triggering-pipelines/on-unit-test-event