Pruebas de regresión con el comando run-compare

El comando run-compare de PQTest es una herramienta eficaz para las pruebas de regresión, lo que le permite evaluar exhaustivamente las funciones del conector y la generación de texto del comando. Para ilustrar su versatilidad, las secciones posteriores proporcionan varios ejemplos adaptados a diferentes escenarios.

Formatos de entrada de prueba

El comando run-compare admite dos formatos de entrada de prueba:

• Formato de expresión: expresión M única (por ejemplo, una let expresión o invocación de función). Este formato es el formato más sencillo y es adecuado para la mayoría de los escenarios de prueba.
• Formato de documento de sección: M documento de sección que contiene uno o varios miembros de sección. Este formato es útil para las pruebas que requieren funciones auxiliares, valores compartidos o configuraciones más complejas.

Cuando un archivo de prueba usa el formato de expresión, PQTest lo convierte automáticamente en un documento de sección internamente antes de la evaluación. También puede escribir la entrada de prueba directamente como un documento en secciones.

Ejemplo de formato de expresión

let
    Source = Contoso.Contents("TestEndpoint"),
    Result = Table.RowCount(Source)
in
    Result

Ejemplo de formato de documento de sección

section Test;

shared Helper = (x) => x + 1;
shared Query = let
    Source = Contoso.Contents("TestEndpoint"),
    Result = Helper(Table.RowCount(Source))
in
    Result;

Cuando se proporciona una consulta de parámetros, la consulta de parámetros se agrega como miembro de sección al documento de sección. La consulta de parámetros se evalúa como parte de la misma sección, lo que permite que la consulta de prueba haga referencia a ella directamente.

Consultas básicas

La forma más sencilla de realizar pruebas es agregar una expresión de consulta única a un .query.pq archivo, que puede ejecutar mediante el comando run-compare . PQTest evalúa la expresión y genera un .pqout archivo (salida) con el mismo nombre. Para las ejecuciones posteriores, compara la salida generada a partir de la evaluación del archivo .query.pq con el archivo .pqout del mismo nombre y devuelve la salida de la evaluación.

Ejemplo 1: Ejecución del comando run-compare para un archivo de consulta cuando no existe un archivo de salida

En el ejemplo siguiente se ejecuta un único archivo de prueba de consulta mediante la extensión de Power Query especificada y se genera un archivo de salida que se va a comparar.

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q contoso.query.pq

[
  {
    "Details": "Contoso.Contents(\"TestEndpoint\")",
    "EndTime": "2025-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2025-12-11T18:04:11.1532388+00:00",
    "Output": [
      {
        "SourceFilePath": "contoso.query.pq",
        "OutputFilePath": "contoso.query.pqout",
        "Status": "Output File Generated",
        "SerializedSource": null,
        "SourceError": null,
        "OutputError": null
      }
    ],
    "Status": "Passed",
    "Type": "PQTest.Expression"
  }
]

Ejemplo 2: ejecución del comando run-compare para un archivo de consulta cuando no existe un archivo de salida y se establece la marca FailOnMissingOutputFile

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q contoso.query.pq -fomof

[
  {
    "Details": "Contoso.Contents(\"TestEndpoint\")",
    "EndTime": "2025-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2025-12-11T18:04:11.1532388+00:00",
    "Output": [
      {
        "SourceFilePath": "contoso.query.pq",
        "OutputFilePath": "contoso.query.pqout",
        "Status": "Missing Output File",
        "SerializedSource": "Output of contoso.query.pq",
        "SourceError": null,
        "OutputError": null
      }
    ],
    "Status": "Failed",
    "Type": "PQTest.Expression"
  }
]

Ejemplo 3: Ejecución del comando run-compare para un archivo de consulta con un archivo de salida presente

En el ejemplo siguiente se ejecuta un único archivo de prueba de consulta mediante la extensión de Power Query especificada, se compara con el archivo de salida y se devuelve el resultado.

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q contoso.query.pq

[
  {
    "Details": "Contoso.Contents(\"TestEndpoint\")",
    "EndTime": "2025-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2025-12-11T18:04:11.1532388+00:00",
    "Output": [
      {
        "SourceFilePath": "contoso.query.pq",
        "OutputFilePath": "contoso.query.pqout",
        "Status": "Passed",
        "SerializedSource": null,
        "SourceError": null,
        "OutputError": null
      }
    ],
    "Status": "Passed",
    "Type": "PQTest.Expression"
  }
]

Prueba con consulta de parámetros

La consulta de parámetros es una consulta que se combina con una consulta de prueba en tiempo de ejecución, con la consulta de parámetros que se ejecuta primero. Esta funcionalidad le permite dividir el archivo ".query.pq" en dos partes: el archivo de consulta de parámetros y el archivo de consulta de prueba.

Pruebas de orígenes de datos independientes con parámetros y formato de consulta de prueba

Un ejemplo de caso de uso en el que esta funcionalidad sería útil es crear un conjunto de pruebas independiente del origen de datos. Puede usar la consulta de parámetros para recuperar datos del origen de datos y hacer que la consulta de prueba sea M genérica. Si desea ejecutar las pruebas para otro conector, solo tiene que agregar o actualizar la consulta de parámetros para que apunte a ese origen de datos específico.

Una diferencia clave al usar una consulta de parámetros es que la consulta de prueba sigue un formato diferente. En lugar de ser una expresión de fórmula, debe ser una función M que toma un parámetro de entrada, que representa la tabla devuelta desde la consulta de parámetros.

Cuando se proporciona una consulta de parámetros, la consulta de parámetros se agrega como miembro de sección al final del documento de sección de la prueba. Las entradas de prueba y de parámetro se evalúan conjuntamente como un único documento de la sección Mashup.

Supongamos que tienes la siguiente consulta de prueba:

let
    Source = Snowflake.Databases("...", "..."),
    Database = Source{[Name="...",Kind="Database"]}[Data],
    SelectColumns = Table.RemoveColumns(Database, { "Data" })
in
    SelectColumns

Para convertirlo en una consulta de prueba y parámetros, debe dividirlos de la siguiente manera:

Consulta de parámetros:

let
    Source = Snowflake.Databases("...", "..."),
    Database = Source{[Name="...",Kind="Database"]}[Data],
    Schema = Database{[Name="...",Kind="Schema"]}[Data],
    Taxi_Table = Schema{[Name="...",Kind="Table"]}[Data]
in
    Taxi_Table

Consulta de prueba:

(Source) => let
    SelectColumns = Table.RemoveColumns(Source, { "VendorID" })
in
    SelectColumns

Ejemplo 4: Uso de la consulta de parámetros y la consulta de prueba con el comando run-compare

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q contoso.query.pq -pa contoso.parameter.pq

[
  {
    "Details": "(Source) => let\r\n    Schemas = Table.RemoveColumns(Source, { \"Data\" })\r\nin\r\n    Schemas",
    "EndTime": "2025-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2025-12-11T18:04:11.1532388+00:00",
    "Output": [
      {
        "SourceFilePath": "contoso.query.pq",
        "OutputFilePath": "contoso.query.pqout",
        "Status": "Passed",
        "SerializedSource": null,
        "SourceError": null,
        "OutputError": null
      }
    ],
    "Status": "Passed",
    "Type": "PQTest.Expression"
  }
]

Comparación de diagnósticos

Se puede evaluar información de diagnóstico adicional al usar el comando run-compare mediante la suscripción a un canal de diagnóstico. Cuando se ejecuta el comando run-compare , PQTest genera un .diagnostics archivo para cada canal suscrito que tenía un evento. En el caso de las ejecuciones posteriores, compara el diagnóstico con su archivo .diagnostics, similar a .pqout.

Ejemplo 5: suscripción al canal de diagnóstico ODBC (conectividad abierta de base de datos) para validar el plegado de consultas

En el ejemplo siguiente se muestra cómo suscribirse al canal ODBC, que captura cualquier SQL generado por el controlador ODBC cuando se usa el plegado de consultas.

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q contoso.query.pq -dc "Odbc"

El canal de diagnóstico ODBC se puede usar para comprobar que una consulta está plegada y que está generando el SQL correcto.

let
    Source = AzureSpark.Tables("..."),
    T1 = Source{[Schema="default",Item="DATABASE"]}[Data],
    SelectColumns = Table.Group(T1, {}, {{"Maximum", each List.Max([number_column]), type number}}),
    FirstN = Table.FirstN(SelectColumns, 1)
in
    FirstN

La consulta ahora plega y genera el siguiente texto de comando ODBC en el .diagnostics archivo:

[
  {
    "Command": "DESCRIBE default.DATABASE;"
  },
  {
    "Command": "select top 1 max(`number_column`) as `C1` from `SPARK`.`default`.`DATABASE`"
  }
]

Uso de un archivo de configuración

Cualquier parámetro de entrada de línea de comandos para el comando run-compare también se puede pasar a través de un archivo de configuración JSON. Json puede tener las siguientes opciones:

En caso de que se proporcionen tanto la entrada en la línea de comandos como la opción de configuración, se da prioridad a la entrada en la línea de comandos.

Ejemplo 6: Uso del archivo de configuración en lugar de argumentos de la línea de comandos

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q contoso.query.pq -fomof

El comando es equivalente al siguiente comando:

<Path to PQTest.exe>.\PQTest.exe run-compare -sf settings.json

Donde settings.json es el siguiente archivo JSON:

{
  "ExtensionPaths": ["contoso.mez"],
  "QueryFilePath": "contoso.query.pq",
  "FailOnMissingOutputFile": true
}

Probar baterías con el comando run-compare

Una batería de prueba es una colección de pruebas que evalúan varios aspectos del código. Coloque los archivos de consulta en la misma carpeta para que PQTest pueda localizarlos fácilmente. En lugar de pasar un nombre de archivo de prueba específico, especifique la ruta de acceso de la carpeta y PQTest ejecuta todos los archivos de consulta de prueba .query.pq en un solo paso.

Ejemplo 7: Ejecución de una batería de pruebas

Suponiendo que una carpeta denominada test contenga los siguientes archivos:

• contoso.testa.query.pq
• contoso.testb.query.pq
• contoso.testc.query.pq

Toda la batería de prueba se puede ejecutar mediante la siguiente línea de comandos:

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test

Omitir pruebas al ejecutar una batería de pruebas

Se puede omitir una prueba al ejecutar una batería de pruebas cambiando la extensión del archivo .query.pq a .query.pq.ignore.

Ejemplo 8: Omitir una prueba al ejecutar una batería de pruebas

Suponiendo que una carpeta denominada test contenga los siguientes archivos:

• contoso.testa.query.pq
• contoso.testb.query.pq.ignore
• contoso.testc.query.pq

Los archivos contoso.testa.query.pq y contoso.testc.query.pq se ejecutan, pero contoso.testb.query.pq.ignore se omite cuando se ejecuta el siguiente comando para ejecutar la batería de prueba:

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test

Filtrado de pruebas

La --testFilter opción permite incluir o excluir de forma selectiva archivos de prueba al ejecutar baterías de prueba. Esta opción usa patrones globales para buscar coincidencias con las rutas de acceso de archivo y se puede especificar varias veces para crear reglas de filtrado complejas.

Filtros de inclusión

Especifique qué archivos incluir en la ejecución de la prueba usando patrones glob estándar.

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test --testFilter "Suite1/**/*.pq"

Filtros de exclusión

Especifique los archivos que se van a excluir de la ejecución de pruebas mediante el ! prefijo para indicar patrones de exclusión.

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test --testFilter "!BrokenTests/*"

Varios filtros

Se pueden combinar varias --testFilter opciones para crear lógica de filtrado compleja:

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test --testFilter "**/*.pq" --testFilter "!BrokenTests/*" --testFilter "!**/*donotrun*.pq"

Comportamiento de filtro

• Inclusión implícita: cuando no se especifica ningún filtro de inclusión, **/*.query.pq se aplica automáticamente.
• Sin distinción entre mayúsculas y minúsculas: todos los patrones coinciden sin considerar mayúsculas o minúsculas.
• Orden independiente: el orden de los filtros no afecta al resultado.
• Formato de ruta: use barras diagonales (/) en patrones para la compatibilidad multiplataforma.

Ejemplos de patrones de Glob

Enumeración de archivos de prueba sin ejecución

La --listOnly opción permite obtener una vista previa de los archivos de prueba que ejecutaría el comando run-compare sin ejecutar realmente las pruebas. Esta opción es útil para comprobar el comportamiento del filtro y la detección de pruebas.

Ejemplo 9: Enumeración de archivos de prueba

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test --listOnly

{
    "SourcePath": "C:\\MyProject\\test",
    "TestFilters": [],
    "Tests": [
        {
            "Test": "MyTest.query.pq",
            "RelativePath": "Suite1\\MyTest.query.pq",
            "AbsolutePath": "C:\\MyProject\\test\\Suite1\\MyTest.query.pq"
        },
        {
            "Test": "AnotherTest.query.pq",
            "RelativePath": "Suite2\\AnotherTest.query.pq",
            "AbsolutePath": "C:\\MyProject\\test\\Suite2\\AnotherTest.query.pq"
        }
    ]
}

La salida contiene los siguientes campos:

• SourcePath: el valor QueryFilePath que se proporcionó al comando (desde -q la opción).
• TestFilters: lista de todos los valores testFilter que se aplicaron (desde --testFilter opciones).
• Pruebas: matriz de objetos de archivo de prueba, donde cada objeto contiene:
  • Prueba: nombre de archivo del archivo de prueba.
  • RelativePath: ruta de acceso relativa al directorio de prueba base especificado por -q.
  • AbsolutePath: ruta de acceso absoluta completa al archivo de prueba.

Combinación con filtros de prueba

La --listOnly opción respeta todas las --testFilter opciones, lo que le permite obtener una vista previa del efecto de los filtros:

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test --testFilter "Suite1/**/*.pq" --listOnly

Administración de resultados intermedios de pruebas

El comando run-compare genera archivos intermedios durante la ejecución de pruebas, incluidos los archivos de salida de prueba reales (.pqout) y los archivos de diagnóstico (.diagnostics). De forma predeterminada, estos archivos se crean en una ubicación temporal con una estructura de subcarpeta basada en fecha y se limpian automáticamente una vez completada la ejecución de la prueba.

Puede controlar este comportamiento mediante dos opciones:

• --intermediateTestResultsFolder | -itrf: especifica una ruta de acceso de carpeta personalizada para almacenar los resultados intermedios de las pruebas.
• --persistIntermediateTestResults | -pitr: mantiene los resultados intermedios después de que se complete la ejecución de la prueba.

Ejemplo 10: Usar una carpeta intermedia personalizada y conservar los resultados

<Path to PQTest.exe>.\PQTest.exe run-compare -e contoso.mez -q .\test -itrf "C:\TestResults" -pitr

Estructura intermedia de carpetas

Al especificar una carpeta intermedia de resultados de pruebas, PQTest crea una estructura de subcarpeta basada en fechas para organizar los resultados de las pruebas:

<IntermediateTestResultsFolder>\
  └── YYYYMMDD_HHmmss_ffffff\
      ├── Test1.query.pqout
      ├── Test2.query.pqout
      ├── Test3.query.odbc.diagnostics
      └── ...

Comportamiento de limpieza

El comportamiento de limpieza depende de si especifica una carpeta intermedia y si usa la marca persistente: