# API de búsqueda de casos de prueba

> Búsqueda cross-suite de casos de prueba con texto libre q y filtros personalizados cf.

El endpoint de búsqueda devuelve casos de prueba de todas las suites de un proyecto en una sola solicitud — sin cursor, sin carga lazy del árbol. Está diseñado para la barra de filtros del repositorio pero disponible para cualquier integrador que necesite acceso cross-suite.

## Búsqueda

`GET /api/v1/projects/{projectId}/test-cases/search`

`{projectId}` es el **código** del proyecto (por ejemplo `ACME`).

### Parámetros de consulta

| Parámetro      | Notas                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`            | Coincidencia de subcadena aplicada según `scope`. Los valores en blanco se ignoran.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scope`        | `all` (por defecto), `cases` o `suites`. Con `cases`, `q` coincide con `title` O `display_id`. Con `suites`, `q` coincide con el nombre de la suite padre y devuelve sus casos (los casos sin suite nunca coinciden). Con `all`, ambos predicados se unen con OR. No tiene efecto sin un `q` no vacío. Los valores desconocidos devuelven `422 validation_failed`.                                                                                                                                                        |
| `cf`           | Repetible. Cada entrada es `<fieldUlid>:<value[,value…]>`. Filtra campos personalizados de entidad `test_case`. Los campos basados en opciones aceptan ULIDs de opciones; `checkbox` acepta `true`/`false`; `user_picker` acepta un ULID de usuario. El token `empty` coincide con casos sin fila almacenada para ese campo. Las entradas se combinan con AND entre campos; los valores dentro de una entrada se combinan con OR. Un campo inválido, tipo no soportado u opción foránea devuelve `422 validation_failed`. |
| `reviewStatus` | Estados de revisión separados por comas: `not_reviewed`, `in_review`, `approved`. Solo coinciden los casos con alguno de ellos. Un valor desconocido devuelve `422 validation_failed`.                                                                                                                                                                                                                                                                                                                                    |
| `limit`        | Entero 1–200, por defecto 50. Los valores fuera de rango devuelven `422 validation_failed`.                                                                                                                                                                                                                                                                                                                                                                                                                               |

### Respuesta

```json
{
  "items": [...],
  "total": 42
}
```

`items` contiene objetos completos de casos de prueba (mismo formato que el endpoint de detalle, incluyendo `suiteUlid`, `customFieldValues` y `reviewStatus`), ordenados por ULID ascendente. Los casos archivados se excluyen.

`total` es el conteo total de coincidencias independientemente del `limit`. Cuando `total` supera `items.length`, la UI muestra un aviso de límite invitando a refinar el filtro.

### Ejemplo

```bash
curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://app.probara.net/api/v1/projects/ACME/test-cases/search?q=login&cf=<priorityFieldUlid>:<highOptionUlid>"
```