Referencia de Probara Query Language (PQL)

Probara Query Language (PQL) hace preguntas sobre tus datos de prueba. Una consulta indica una entidad, como casos o resultados, filtra sus filas con WHERE, y puede agruparlas y agregarlas. Escribe PQL en Consultas o envíalo a la API de PQL.

Inicio rápido

1. Indica la entidad: FROM cases.
2. Filtra las filas: WHERE priority = "High".
3. Elige el tamaño de página: LIMIT 50.

FROM cases WHERE priority = "High" AND status = "Active" ORDER BY title LIMIT 50

Los ejemplos usan los nombres en inglés de las opciones predeterminadas, como High o Active. Si tu organización usa otros nombres, escribe los suyos.

Forma de la consulta

Reglas:

• Las palabras clave, los nombres de función, de entidad y de campo no distinguen mayúsculas de minúsculas.
• Un comentario de línea empieza con --.
• Los saltos de línea y los espacios extra no importan.
• Una consulta con SELECT y un agregado devuelve filas agrupadas. Cualquier otra consulta devuelve filas.
• Un elemento de SELECT que no está agregado debe aparecer en GROUP BY.

Literales

Notas:

• Los valores de texto deben ir entre comillas. title = Login es un error, y title = "Login" funciona.
• Los nombres de hitos, suites, entornos, etiquetas y proyectos son texto. Ponlos entre comillas cuando tengan espacios: milestone = "Release 1.4".
• Los campos de duración fija, como runs.duration, aceptan solo m, h, d y w. Usa mo, q e y solo en el tiempo relativo.

Operadores

Los campos booleanos solo aceptan = y !=, así que escribe archived = true, no archived.

Entidades

Cada entidad tiene un id, que es su ID visible, y un project. Las tablas listan los campos que puedes usar. Un campo marcado como Opcional puede estar vacío, así que is empty se aplica a él. Un campo marcado como Historial admite was y changed.

Casos

Columnas predeterminadas: id, title, suite, priority, status.

Relaciones: results, runCases, defects, jira. Campos personalizados: cf[...].

Suites

Columnas predeterminadas: id, name, parent, cases.

Relaciones: cases.

Ejecuciones

Columnas predeterminadas: id, name, state, status, milestone, passRate.

Relaciones: results, runCases, defects. Campos personalizados: cf[...].

Casos de ejecución

Los casos de ejecución son los casos dentro de una ejecución, incluidos los que aún no se han probado. Columnas predeterminadas: run, case, status, assignee, elapsed.

Sin relaciones.

Un caso de ejecución de un caso parametrizado es una instancia: un caso con dos parámetros de tres valores cada uno tiene nueve casos de ejecución en una ejecución. Cuéntalos con count() sobre los casos de ejecución, y consulta Casos de prueba parametrizados.

Resultados

Columnas predeterminadas: id, run, case, status, executedBy, executed.

Sin relaciones. Campos personalizados: ninguno.

Defectos

Columnas predeterminadas: id, title, status, severity, priority, assignee.

Relaciones: cases, results. Campos personalizados: cf[...].

Hitos

Columnas predeterminadas: id, name, status, due.

Relaciones: runs, cases, defects.

Planes

Columnas predeterminadas: id, name, status, milestone.

Relaciones: runs, cases.

Pasos compartidos

Columnas predeterminadas: id, title, folder, updated.

Sin relaciones.

Campos personalizados

Los casos, las ejecuciones y los defectos tienen los campos personalizados de tu organización. Escribe el título del campo entre corchetes:

FROM cases WHERE cf["Risk"] = "High"

El título se compara sin distinguir mayúsculas y sin los espacios de los extremos. Un título que ningún campo personalizado de esa entidad tiene devuelve unknown_custom_field.

Rutas a registros relacionados

Los resultados y los casos de ejecución apuntan a una ejecución y a un caso. Accede a sus campos con una ruta de puntos:

FROM results WHERE run.environment = "staging" AND case.priority = "Critical" AND status = failed

Las rutas funcionan en WHERE y en GROUP BY, por ejemplo GROUP BY run.environment.

lastResult

lastResult es el resultado más reciente de un caso, por fecha de ejecución y después por ID. Está disponible en cases en el nivel superior de una consulta.

• lastResult.status lee el estado del resultado más reciente.
• lastResult(environment = "staging").status lee el resultado más reciente entre las ejecuciones que cumplen la condición. La condición usa campos de ejecución, como environment, milestone y plan.
• Un caso sin resultado coincidente no tiene valor, así que = no lo encuentra.

FROM cases WHERE lastResult(environment = "staging").status = failed ORDER BY title

lastResult no se puede comparar directamente, y no tiene historial.

Relaciones

exists y count miran los registros relacionados de cada fila.

FROM cases WHERE exists(results where status = failed)
FROM cases WHERE NOT exists(results)
FROM cases WHERE count(results where status = failed) >= 3

Reglas:

• Usa exists y count en WHERE. exists en HAVING devuelve relation_placement.
• Compara count(relación) con un número.
• Las subconsultas se anidan como máximo dos niveles. FROM suites WHERE exists(cases where exists(results where status = failed)) tiene dos niveles.
• Los registros relacionados cuentan solo en los proyectos a los que tienes acceso, y cada registro relacionado cuenta una vez.
• Los casos archivados se dejan fuera de una condición de registros relacionados sobre casos, salvo que la condición nombre archived. Ver Casos archivados.

Funciones

passRate() cuenta así:

• En resultados, los resultados aprobados divididos entre todos los resultados.
• En ejecuciones, los casos aprobados divididos entre los casos aprobados, fallidos, bloqueados y omitidos. Es la misma cifra que runs.passRate.

SELECT bucket(executed, week) AS period, passRate() AS rate, count() AS results FROM results GROUP BY 1 ORDER BY 1

Tiempo y zonas horarias

Las fechas y los tiempos relativos se leen en la Zona horaria de tu perfil. Con Detectado automáticamente, se usa UTC. now, startOf, endOf, bucket y las comparaciones de fechas siguen esta zona.

El tiempo relativo admite todas las unidades: m, h, d, w, mo, q e y. Los campos de duración fija admiten m, h, d y w.

Reglas de agregación

• GROUP BY acepta campos, expresiones y posiciones, como GROUP BY 1. No acepta alias de SELECT. Repite la expresión, o usa su posición.
• HAVING filtra grupos con agregados, como HAVING count() > 5. No acepta alias, así que HAVING n > 5 falla.
• ORDER BY acepta alias (ORDER BY n DESC), posiciones contadas desde 1 (ORDER BY 2) y agregados (ORDER BY count() DESC). Los agregados necesitan un grupo, o un agregado en SELECT. Los campos de usuario y de etiquetas no se pueden ordenar.
• La agrupación funciona en campos de número, booleano, enumeración, opción, usuario, referencia y etiquetas. El texto y las fechas no se agrupan directamente. Agrupa una fecha con bucket().
• Las etiquetas y los campos de selección múltiple cuentan una fila en el grupo de cada uno de sus valores. Si agrupas dos de estos campos a la vez, hay un grupo por cada combinación, así que los grupos pueden sumar más que el número de filas.
• Sin valor. Las filas sin valor forman un grupo llamado Sin valor. Aparece primero.
• count(campo) cuenta las filas en las que el campo tiene valor.
• HAVING sobre una etiqueta o un campo de selección múltiple se rechaza. Filtra en WHERE.
• Sin GROUP BY, un agregado devuelve una fila para todas las filas que coinciden.
• Los intervalos de tiempo empiezan al inicio de la unidad en tu zona horaria. Los intervalos vacíos no se devuelven.
• Los selectores de fecha comparan por día local.
• Los grupos se muestran hasta 1.000 por página. El resultado lo indica cuando hay más.

Historial

El historial de cambios registra los cambios de algunos campos. Dos operadores lo leen:

• status was in_progress es verdadero cuando el valor es el actual, o era uno de los valores registrados en el historial.
• status changed es verdadero cuando el historial tiene al menos un cambio. Agrega modificadores para acotarlo:

Todos los modificadores que escribas deben cumplirse en el mismo cambio. t es una fecha o un tiempo relativo, que se lee en tu zona horaria.

FROM defects WHERE status changed from resolved to open after now(-14d)
FROM cases WHERE priority changed by currentUser() after now(-7d)

Campos con historial

El historial de cambios no está disponible para el estado de las ejecuciones, los movimientos entre hitos y suites, los campos personalizados (cf[...]) ni los campos vinculados. Una consulta que los use devuelve history_not_available.

Reglas:

• Usa was y changed en WHERE. En HAVING devuelven history_placement.
• El historial de cambios guarda registros durante la ventana de retención de historial de tu plan. Consulta Retención de datos.
• Los cambios hechos antes de que el registro fuera auditado no se conocen, así que un valor puede faltar en su historial.

Referencias con in query()

id in query("Nombre de la consulta") conserva las filas que devuelve una consulta guardada:

FROM cases WHERE id in query("Critical failures")

• La consulta guardada debe devolver la misma entidad, y en modo de filas.
• Se ignoran su ORDER BY y su LIMIT.
• Una consulta guardada puede referirse a otra hasta tres niveles de profundidad. Un ciclo se rechaza.
• Solo puedes referirte a consultas que puedes ver. Un nombre desconocido u oculto devuelve unknown_saved_query.

Casos archivados

Una consulta sobre casos deja fuera los casos archivados, salvo que la consulta nombre archived en su propio nivel. La misma regla se aplica a una condición de registros relacionados sobre casos, como exists(cases ...).

FROM cases WHERE title ~ "login"                 -- los casos archivados quedan fuera
FROM cases WHERE archived = true                 -- la condición decide

Una consulta sobre resultados es distinta. Archivar conserva el historial de ejecución de un caso, así que FROM results (y FROM runCases) incluye los resultados de los casos archivados. Para dejarlos fuera, indica que el caso está activo:

FROM results WHERE case.archived = false         -- los resultados de los casos archivados quedan fuera

Límites

Errores

Cada error tiene un código, un mensaje y el lugar de la consulta donde ocurre. A través de la API, cada error aparece en details.errors con el mismo código. Consulta Errores.

Errores de sintaxis

Nombres y funciones

Valores y operadores

Agregados, agrupación y paginación

Cuando el servidor todavía no admite una construcción, la consulta muestra Todavía no disponible en el editor, con la construcción indicada. Quita esa parte de la consulta por ahora.

Ejemplos resueltos

Cada ejemplo responde a una pregunta frecuente. Sustituye los nombres por tus suites, hitos y entornos.

Siguiente paso

• Escribe y ejecuta consultas en Consultas.
• Pon una consulta guardada en un dashboard en Dashboards.
• Envía consultas desde código con la API de PQL.