API de matriz de cobertura

El endpoint de matriz de cobertura devuelve el estado del resultado más reciente para cada caso de prueba de un proyecto, desglosado por entorno. Cada fila representa un caso de prueba; cada celda dentro de la fila representa el resultado más reciente registrado para ese caso en uno de los entornos del proyecto.

El endpoint es de solo lectura — no emite eventos de auditoría ni realiza cambios de estado.

Todas las peticiones requieren una sesión autenticada (token de API o cookie) con membresía mínima de viewer en la organización del proyecto. Un projectId que pertenezca a otra organización devuelve 404 not_found.

Obtener la matriz de cobertura

GET/api/v1/projects/{projectId}/coverage-matrix

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

Parámetros de consulta

Parámetro	Por defecto	Notas
page	1	Número de página (base 1)
pageSize	50	Filas por página (mínimo 1, máximo 200)
suiteUlid	—	Lista opcional de ULIDs de suite, separados por comas. Cuando se indica, solo se devuelven los casos de prueba que pertenezcan a alguna de las suites listadas (semántica OR). Un único ULID se comporta de forma idéntica al comportamiento anterior. Los ULIDs desconocidos o de otro proyecto se ignoran silenciosamente; si todos los ULIDs son desconocidos, el resultado es una página vacía con total = 0. Un ULID con formato inválido (no es un Crockford base32 de 26 caracteres válido) devuelve 422 validation_failed.
status	—	Filtro opcional por estado derivado más reciente, separado por comas. Valores aceptados: passed, failed, blocked, skipped, untested, none. none selecciona las filas con al menos una celda vacía (un caso nunca ejecutado en ningún entorno). Los valores se combinan con OR. Un token desconocido devuelve 422 validation_failed.
q	—	Consulta de búsqueda de texto opcional. Cuando no está vacío (tras eliminar espacios), restringe las filas a los casos cuyos campos de texto (seleccionados por searchBy) contengan q como subcadena sin distinción de mayúsculas. Los caracteres % y _ en q se tratan literalmente. Un valor vacío o compuesto solo de espacios se considera ausente (sin filtro de texto).
searchBy	all	Controla qué campo se busca cuando q no está vacío. Valores aceptados: all (por defecto), title, id. Consulta la tabla de valores de searchBy. Un valor desconocido devuelve 422 validation_failed.

Respuesta

200 con la siguiente forma:

{
  "columns": [ ... ],
  "rows": {
    "items": [ ... ],
    "page": 1,
    "pageSize": 50,
    "total": 120
  }
}

columns

Un array de objetos de entorno, uno por cada entorno activo del proyecto, en orden de creación. Son los encabezados de columna de la matriz.

Campo	Tipo	Notas
environmentId	string (ULID)	El ULID del entorno
name	string	Nombre para mostrar (por ejemplo Staging)
slug	string	Identificador seguro para URLs (por ejemplo staging)

Los entornos eliminados de forma lógica nunca se incluyen.

rows.items

Un array paginado de filas de casos de prueba. Cada fila contiene los siguientes campos:

Campo	Tipo	Notas
testCaseId	string (ULID)	El ULID del caso de prueba
caseNumber	number	Número de caso legible dentro del proyecto
title	string	Título del caso de prueba
suite	object | null	La suite a la que pertenece el caso ({ ulid, name }), o null si no tiene asignación
cells	array	Una celda por columna, en el mismo orden que columns

Cada entrada de cells:

Campo	Tipo	Notas
environmentId	string (ULID)	Corresponde al columns[i].environmentId equivalente
status	string | null	Estado del resultado más reciente para este caso en este entorno, o null si no existe ningún resultado
executedAt	number | null	Milisegundos desde epoch Unix del resultado más reciente, o null
runUlid	string (ULID) | null	La ejecución que produjo el resultado más reciente, o null

Un status null significa que el caso de prueba nunca se ejecutó en ese entorno — es una celda vacía, distinta de un resultado con estado untested. cells.length siempre es igual a columns.length.

Valores de estado

Valor	Significado
passed	El resultado más reciente es satisfactorio
failed	El resultado más reciente es fallido
blocked	El resultado más reciente está bloqueado
skipped	El resultado más reciente fue omitido
untested	El caso fue marcado explícitamente como no probado en el resultado más reciente
null	No hay ningún resultado registrado en este entorno (celda vacía)

Valores de searchBy

Valor	Columnas buscadas
all (por defecto)	title del caso o ID visible (#<caseNumber>) — combinados con OR
title	Solo el title del caso
id	Solo el ID visible — el formato #<caseNumber> que aparece en la UI

Cuando q está ausente o vacío, searchBy no tiene efecto.

total en la respuesta siempre refleja el conteo de filas tras aplicar todos los filtros activos (suite + estado + texto).

Desempate

Cuando dos resultados para el mismo par (caso de prueba, entorno) comparten la misma marca de tiempo executedAt, prevalece el resultado con el ID interno mayor.

Los resultados de ejecuciones sin entorno asignado (environment_id IS NULL) nunca se incluyen en ninguna celda.

Errores

Estado	Código	Condición
404	not_found	projectId no existe o pertenece a otra organización
422	validation_failed	pageSize fuera de rango, token de status desconocido, ULID con formato inválido en suiteUlid, valor de searchBy desconocido

Ejemplos

Filtrar por dos suites y buscar por título:

curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://probara.net/api/v1/projects/ACME/coverage-matrix?suiteUlid=01JAAAA...,01JBBBB...&q=login&searchBy=title"

Filtrar por estado con paginación:

curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://probara.net/api/v1/projects/ACME/coverage-matrix?pageSize=20&status=failed,none"

Fragmento de respuesta:

{
  "columns": [
    { "environmentId": "01JAAAA...", "name": "Staging", "slug": "staging" },
    { "environmentId": "01JBBBB...", "name": "Production", "slug": "production" }
  ],
  "rows": {
    "items": [
      {
        "testCaseId": "01JCCCC...",
        "caseNumber": 1,
        "title": "Inicio de sesión con credenciales válidas",
        "suite": { "ulid": "01JDDDD...", "name": "Autenticación" },
        "cells": [
          {
            "environmentId": "01JAAAA...",
            "status": "failed",
            "executedAt": 1718700000000,
            "runUlid": "01JEEEE..."
          },
          { "environmentId": "01JBBBB...", "status": null, "executedAt": null, "runUlid": null }
        ]
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 3
  }
}

Páginas relacionadas

• API de entornos — lista los entornos que aparecen como columnas en la matriz.
• Guía de la matriz de cobertura — explicación de la pantalla Coverage para usuarios.