Teste de regressão com o comando compare

2025-03-28

O comando PQTest comparar é uma poderosa ferramenta para testes de regressão, permitindo avaliar completamente as funções do conector e a geração de texto de comando. Para ilustrar sua versatilidade, as seções subsequentes fornecerão uma variedade de exemplos adaptados a cenários diferentes.

Consultas básicas

A forma mais simples de teste é adicionar uma única expressão de consulta a um arquivo .query.pq, que você pode executar usando o comando comparar. O PQTest avalia a expressão e gera um arquivo .pqout (saída) com o mesmo nome. Para quaisquer execuções subsequentes, ele compara a saída gerada da avaliação do arquivo .query.pq com o arquivo pqout (saída) com o mesmo nome e retorna a saída da avaliação.

Exemplo 1 – Executando o comando de comparação para um arquivo de consulta quando um arquivo de saída não existe

O exemplo a seguir executa um único arquivo de teste de consulta usando a extensão do Power Query especificada e gera um arquivo de saída a ser comparado.

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

[
  {
    "Details": "Contoso.Contents(\"TestEndpoint\")",
    "EndTime": "2020-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2020-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"
  }
]

Exemplo 2 – Executar o comando compare para um arquivo de consulta quando um arquivo de saída não existir e o sinalizador FailOnMissingOutputFile estiver definido

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

[
  {
    "Details": "Contoso.Contents(\"TestEndpoint\")",
    "EndTime": "2020-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2020-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"
  }
]

Exemplo 3 – Executar o comando compare para um arquivo de consulta com um arquivo de saída presente

O exemplo a seguir executa um único arquivo de teste de consulta usando a extensão do Power Query especificada, compara-o com o arquivo de saída e retorna o resultado.

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

[
  {
    "Details": "Contoso.Contents(\"TestEndpoint\")",
    "EndTime": "2020-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2020-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"
  }
]

Teste com consulta de parâmetro

A consulta de parâmetro é uma consulta que é combinada com uma consulta de teste durante o tempo de execução, com a consulta de parâmetro sendo executada primeiro. Essa funcionalidade permite dividir o arquivo de consulta PQ/teste em duas partes: o arquivo de consulta de parâmetro e o arquivo de consulta de teste.

Teste de fonte de dados independente com formato de consulta de parâmetro e teste

Um exemplo de um caso de uso em que essa funcionalidade seria útil é criar um conjunto de testes independente de fonte de dados. Você pode usar a consulta de parâmetro para recuperar dados da fonte de dados e fazer com que a consulta de teste seja genérica M. Se você quiser executar os testes para outro conector, só precisará adicionar/atualizar a consulta de parâmetro para apontar para essa fonte de dados específica.

Uma diferença importante ao usar uma consulta de parâmetro é que a consulta de teste segue um formato diferente. Em vez de ser uma expressão de fórmula, ela deve ser uma função M que usa um parâmetro de entrada, que representa a tabela retornada da consulta de parâmetro.

Digamos que você tenha a seguinte consulta de teste:

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

Para convertê-lo em um teste e uma consulta de parâmetro, você precisa dividi-los da seguinte maneira:

Consulta de parâmetro:

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 teste:

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

Exemplo 4 – Usando consulta de parâmetro e consulta de teste com comando compare

<Path to PQTest.exe>.\PQTest.exe 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": "2020-12-11T18:04:14.8991822+00:00",
    "Method": "Compare.TestFiles",
    "Name": "contoso.query.pq",
    "StartTime": "2020-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"
  }
]

Comparando diagnósticos

Informações extras de diagnóstico podem ser avaliadas ao usar o comando comparar assinando um canal de diagnóstico. Quando o comando comparar é executado, o PQTest gera um arquivo .diagnostics para cada canal assinado que teve um evento. Para as execuções seguintes, ele compara o evento de diagnóstico com o arquivo .diagnostics, semelhante ao .pqout.

Exemplo 5 – Como assinar o canal de diagnóstico do ODBC para validar a dobragem de consultas

O exemplo a seguir mostra como assinar o canal do ODBC, que captura qualquer SQL gerado pelo driver ODBC quando a dobragem de consultas é usada.

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

O canal de diagnóstico do ODBC pode ser usado para verificar se uma consulta está sendo dobrada e se está gerando o SQL correto.

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

A consulta agora dobra e gera o seguinte texto de comando do ODBC no arquivo .diagnostics:

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

Usando um arquivo de configurações

Qualquer parâmetro de entrada de linha de comando para o comando comparar também pode ser passado por meio de um arquivo de configurações JSON. O JSON pode ter as seguintes opções:

Opção	Tipo	Descrição
ExtensionPaths	array	Matriz de caminhos que apontam para o arquivo do conector (mez/pqx).
FailOnMissingOutputFile	bool	O "Compare" não gera um arquivo PQOut e falha se ele não existir.
FailOnFoldingFailure	bool	A comparação falhará se um erro de dobragem de consultas for gerado.
ParameterQueryFilePath	string	Arquivo de consulta que contém expressões M, que é combinado em runtime com o arquivo de consulta de teste. Um caso de uso comum é ter um único arquivo de consulta de parâmetro para especificar uma expressão M para recuperar os dados de várias consultas de teste.
QueryFilePath	string	Arquivo de consulta que contém a expressão M (.pq) a ser testada.
TrxReportPath	string	Gera um arquivo de resultados TRX (Arquivo de Resultados de Teste do Visual Studio) e arquivos JSON separados para cada teste em um determinado caminho.
DiagnosticChannels	array	Nome dos canais de diagnóstico a serem conectados à execução de teste (por exemplo, ODBC para capturar instruções da dobragem de consultas).

No caso de serem fornecidos tanto a entrada de linha de comando quanto as opções de configuração, a entrada de linha de comando é priorizada.

Exemplo 6 – Usando o arquivo de configurações em vez de argumentos de linha de comando

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

O comando acima é equivalente ao seguinte comando:

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

Onde settings.json é o seguinte arquivo JSON:

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

Testar baterias com comando compare

Uma bateria de teste é uma coleção de testes que avaliam vários aspectos do seu código. Coloque os arquivos de consulta na mesma pasta para que o PQTest possa localizá-los facilmente. Em vez de passar um nome de arquivo de teste específico, especifique o caminho da pasta e o PQTest executa todos os arquivos de consulta de teste .query.pq em uma única passagem.

Exemplo 7 – Executar uma bateria de testes

Supondo que uma pasta nomeada teste contenha os seguintes arquivos:

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

Toda a bateria de teste pode ser executada usando a seguinte linha de comando:

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

Como ignorar testes ao executar uma bateria de testes

Um teste pode ser ignorado ao executar uma bateria de testes alterando a extensão do arquivo .query.pq para .query.pq.ignore.

Exemplo 8 – Ignorando um teste ao executar uma bateria de testes