Teste de regressão com o comando compare

Artigo
03/20/2024

O comando PQTest compare é uma ferramenta poderosa para testes de regressão, permitindo que você avalie minuciosamente 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 diferentes cenários.

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 compare. 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 a partir 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 compare 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 especificada do Power Query e gera o arquivo de saída para comparação.

<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 - Executando o comando compare para um arquivo de consulta quando um arquivo de saída não existe e o sinalizador FailOnMissingOutputFile está 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 - Executando 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 especificada do Power Query, 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âmetros

Consulta de parâmetro é uma consulta que é combinada com uma consulta de teste em 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 agnóstica com parâmetro e formato de consulta de teste

Um exemplo de um caso de uso em que essa funcionalidade seria útil é criar um conjunto de testes agnósticos de fonte de dados. Você pode usar sua consulta de parâmetro para recuperar dados da fonte de dados e fazer com que a consulta de teste seja M genérica. Se você quiser executar os testes para outro conector, você só precisa 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, 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 uma consulta de teste e parâmetro, você precisa dividi-los da seguinte maneira:

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

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

Exemplo 4 - Usando a consulta de parâmetro e a consulta de teste com o 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 adicionais de diagnóstico podem ser avaliadas ao usar o comando compare assinando um canal de diagnóstico. Quando o comando compare é executado, o PQTest gera um arquivo .diagnostics para cada canal inscrito que teve um evento. Para quaisquer execuções subsequentes, ele compara o evento de diagnóstico com seu arquivo .diagnostics, semelhante ao .pqout.

Exemplo 5 - Subscrever o canal de diagnóstico ODBC (Open Database Connectivity) para validar a dobragem da consulta

O exemplo a seguir mostra como se inscrever no canal ODBC, que captura qualquer SQL gerado pelo driver ODBC quando a dobragem de consulta é usada.

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

O canal de diagnóstico ODBC pode ser usado para verificar se uma consulta está dobrando 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 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 compare 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	Description
ExtensionPaths	matriz	Matriz de caminhos que apontam para o arquivo do conector (mez/pqx).
FailOnMissingOutputFile	booleano	Comparar não gera um arquivo PQOut e falha se ele não existir.
FailOnFoldingFailure	booleano	A comparação falhará se um erro de dobragem de consulta for lançado.
ParameterQueryFilePath	string	Arquivo de consulta que contém expressões M, que é combinado em tempo de execução 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 para várias consultas de teste.
QueryFilePath	string	Arquivo de consulta que contém expressão M (.pq) a ser testado.
TrxReportPath	string	Gera um arquivo de resultados TRX (Visual Studio Test Results File) e arquivos JSON separados para cada teste em um determinado caminho.
Canais de diagnóstico	matriz	Nome dos canais de diagnóstico a serem anexados à execução de teste (por exemplo, Odbc para capturar instruções de dobragem de consulta).

No caso em que a entrada de linha de comando e a opção de configurações são fornecidas, 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
}

Teste baterias com o comando compare

Uma bateria de teste é uma coleção de testes que avaliam vários aspetos do seu código. Coloque os arquivos de consulta na mesma pasta para que o PQTest possa localizá-los facilmente. Em vez de passar em 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 uma pasta chamada test que contém 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

Ignorando 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 - Ignorar um teste ao executar uma bateria de testes