Source: https://docs.debitura.com/developer-concepts/test-cases

# Test Cases

Create cases in production without triggering real collection activity by setting `IsTest: true`.

<a id="how-it-works"></a>

## How It Works

When you create a case with `IsTest: true`, Debitura validates and persists it as test data. Test cases suppress real collection routing and production email effects, but deliberate test behavior still occurs: test-mode webhooks and timeline events let you exercise an integration end to end. Test cases cannot be converted to production cases.

The behavior diverges after creation depending on which API you are using:

<a id="customer-api"></a>

### Customer API

-   **May be assigned through normal partner matching** — test classification suppresses production effects; it does not guarantee that `collectionPartner` is empty
-   **Visible in your own case listing by default** — no opt-in needed; creditors own their test data and see it alongside production cases
-   No emails sent to debtor, creditor, or partners

<a id="collection-partner-api"></a>

### Collection Partner API

-   **Self-assigned to the managing partner** (routing isolation) — test cases you submit are automatically assigned to your own partner account. They never escape into the global routing pipeline or appear on any other partner's work queue.
-   **Hidden from `GET /cases` by default** — opt in with `?includeTestCases=true` to include test cases the caller owns. This keeps production work queues clean during integration development.
-   **Direct-by-ID endpoints work without the opt-in** — if you created the case, these work on it directly without `?includeTestCases=true`:
    -   `GET /cases/{id}` and `GET /cases/case-reference/{caseReference}`
    -   `POST /cases/{id}/start` and `POST /cases/{id}/close`
    -   `GET /cases/{id}/chats` and `PUT /cases/{id}/fees`
-   No emails or notifications fire to creditors or debtors

<a id="listing-test-cases-on-the-collection-partner-api"></a>

#### Listing test cases on the Collection Partner API

```http
GET /cases?includeTestCases=true
XApiKey: YOUR_API_KEY
```

Returns your normal case list plus any test cases where you are the collection partner. Combine with other filters as needed:

```http
GET /cases?includeTestCases=true&statuses=Active&pageSize=50
XApiKey: YOUR_API_KEY
```

<a id="example"></a>

## Example

```http
POST /cases
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "isTest": true,
  "currencyCode": "USD",
  "amountToRecover": 1500.00,
  "date": "2025-08-01",
  "debtor": {
    "type": "Company",
    "name": "Test Company Ltd",
    "address": "123 Test Street",
    "city": "London",
    "countryAlpha2": "GB"
  }
}
```

<a id="tagging-test-cases"></a>

## Tagging Test Cases

Use the `tag` field to attach a label to a test case at creation time. Tags scope cleanup — you can delete all cases sharing the same tag with a single `DELETE /test/cases?tag=...` call. This is the recommended pattern for CI pipelines where parallel runs must not interfere with each other's cleanup.

```text
suite-run-{uuid}
```

The tag field is supported on both `POST /cases` (Customer API) and `POST /managed-cases` (Collection Partner API).

```http
POST /cases
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "isTest": true,
  "tag": "suite-run-a3f9c12e",
  "currencyCode": "USD",
  "amountToRecover": 1500.00,
  "date": "2025-08-01",
  "debtor": {
    "type": "Company",
    "name": "Test Company Ltd",
    "address": "123 Test Street",
    "city": "London",
    "countryAlpha2": "GB"
  }
}
```

<a id="identifying-test-cases"></a>

## Identifying Test Cases

In API responses, test cases include `"isTestCase": true`:

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isTestCase": true,
  "lifecycle": "Active"
}
```

Use the `isTestCase` field to filter test data in your application.

<a id="advancing-test-cases"></a>

## Advancing Test Cases

Use `POST /test/cases/{id}/advance` to jump a test case to a known lifecycle state synchronously. This is the fastest way to drive a case through your integration without waiting for real business processes to run.

```http
POST /test/cases/{id}/advance
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "to": "Closed:Paid",
  "amount": 1500.00
}
```

Valid `to` values are `Active`, `Closed:Paid` (requires `amount`), and `Closed:NoPayment`. The advance endpoint fires real webhooks and timeline events. See [CI Testing](https://docs.debitura.com/developer-concepts/webhooks/ci-testing.md#step-2--drive) for the full response shape, all guards, and the advance-state caveat.

<a id="cleanup"></a>

## Cleanup

Test cases support two hard-delete operations that cascade to related case data (including payments, chats, files, timeline entries, and webhook delivery records). The separately persisted webhook-event history returned by `GET /webhooks/events` is not deleted.

<a id="delete-by-tag"></a>

### Delete by tag

```http
DELETE /test/cases?tag=suite-run-a3f9c12e
XApiKey: YOUR_API_KEY
```

Deletes all test cases with this tag. Returns `204 No Content`. Idempotent — returns `204` even if no cases match the tag. Both endpoints reject the request if any matched case has `Classification == Production` — live cases are never affected.

<a id="delete-a-single-case"></a>

### Delete a single case

```http
DELETE /test/cases/{id}
XApiKey: YOUR_API_KEY
```

note

These are hard deletes — the case and all related records are permanently removed, not soft-deleted. Do not use the same tag across runs you want to keep.

Debitura may also periodically clean up old test cases. Do not rely on test cases persisting indefinitely.

<a id="applies-to"></a>

## Applies To

-   [Customer API](https://docs.debitura.com/api/customer.md) - `POST /cases` with `isTest: true`
-   [Collection Partner API](https://docs.debitura.com/api/collection-partner.md) - `POST /managed-cases` with `isTest: true`; list with `GET /cases?includeTestCases=true`

* * *

For a complete CI test loop guide, see [CI Testing](https://docs.debitura.com/developer-concepts/webhooks/ci-testing.md).