使用 compare 命令进行回归测试

2025-04-10

PQTest 比较命令是用于回归测试的强大工具，可用于全面评估连接器的功能和生成命令文本。为了说明其多功能性，后续部分将提供针对不同方案定制的各种示例。

基本查询

最简单的测试形式是将单个查询表达式添加到 .query.pq 文件，可以使用比较命令执行该文件。 PQTest 计算表达式并生成具有相同名称的 .pqout（输出）文件。对于任何后续运行，它将从 .query.pq 文件的计算生成的输出与具有相同名称的 pqout（输出）文件进行比较，并返回计算的输出。

示例 1 - 当输出文件不存在时，为查询文件运行 compare 命令

以下示例使用指定的 Power Query 扩展执行单个查询测试文件，并生成要比较的输出文件。

<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"
  }
]

示例 2 - 当输出文件不存在且已设置 FailOnMissingOutputFile 标志时，为查询文件运行 compare 命令

<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"
  }
]

示例 3 - 对查询文件和现有输出文件运行比较命令

以下示例使用指定的 Power Query 扩展执行单个查询测试文件，将其与输出文件进行比较并返回结果。

<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"
  }
]

使用参数查询进行测试

参数查询是一种查询，它在运行时与测试查询结合使用，并且参数查询会优先执行。此功能允许将 PQ/test 查询文件拆分为两个部分：参数查询文件和测试查询文件。

具有参数和测试查询格式的不可知数据源测试

此功能非常有用的用例示例是创建与数据源无关的测试套件。可以使用参数查询从数据源中检索数据，并使测试查询为通用 M。如果要为另一个连接器运行测试，只需添加/更新参数查询以指向该特定数据源。

使用参数查询时的主要区别在于测试查询采用不同的格式。它不是公式表达式，而是采用一个输入参数的 M 函数，它表示从参数查询返回的表。

假设你有以下测试查询：

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

若要将其转换为测试和参数查询，需要按如下所示对其进行拆分：

参数查询：

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

测试查询：

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

示例 4 - 将参数查询和测试查询与 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"
  }
]

比较诊断

通过订阅诊断通道，可以使用比较命令评估额外的诊断信息。运行 compare 命令时，PQTest 会为具有事件的每个订阅通道输出一个 .diagnostics 文件。对于任何后续运行，它将诊断事件与其 .diagnostics 文件进行比较，类似于 .pqout。

示例 5 - 订阅 ODBC（开放数据库连接）诊断通道以验证查询折叠

以下示例演示如何订阅 ODBC 通道，该通道在使用查询折叠时捕获 ODBC 驱动程序生成的任何 SQL。

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

ODBC 诊断通道可用于验证查询是否正在折叠，以及它是否生成正确的 SQL。

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

查询现在折叠并生成 .diagnostics 文件中的以下 ODBC 命令文本：

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

使用设置文件

比较命令的任何命令行输入参数也可以通过 JSON 设置文件传递。 JSON 可以具有以下选项：

选项	类型	说明
ExtensionPaths	数组	指向连接器文件的路径数组（mez/pqx）。
在缺少输出文件时失败	布尔	比较不会生成 PQOut 文件，如果不存在，则失败。
FailOnFoldingFailure	布尔	如果引发查询折叠错误，则 Compare 失败。
ParameterQueryFilePath	字符串	包含 M 表达式的查询文件，该表达式在运行时与测试查询文件组合在一起。常见的用例是有一个参数查询文件来指定 M 表达式来检索多个测试查询的数据。
QueryFilePath	字符串	包含要测试的 M 表达式（.pq）的查询文件。
TrxReportPath	字符串	为给定路径中的每个测试生成 TRX （Visual Studio 测试结果文件）结果文件和单独的 JSON 文件。
DiagnosticChannels	数组	要附加到测试运行中的诊断通道的名称（例如用于捕获查询折叠语句的 Odbc）。

如果提供了命令行输入和设置选项，则命令行输入优先。

示例 6 - 使用设置文件而不是命令行参数

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

上述命令等效于以下命令：

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

其中 settings.json 是以下 JSON 文件：

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

使用 compare 命令测试电池

测试套件是一组测试，用于评估代码的多个方面。将查询文件放在同一文件夹中，以便 PQTest 可以轻松找到它们。不需要传递特定的测试文件名，只需指定文件夹路径，PQTest 就会在一次执行中运行所有 .query.pq 测试查询文件。

示例 7 - 进行一系列测试

假设名为测试的文件夹包含以下文件：

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

可以使用以下命令行运行整个测试电池：

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

在运行一系列测试时忽略某些测试

在执行一系列测试时，通过将 .query.pq 文件的扩展名更改为 .query.pq.ignore，可以忽略某个测试。

示例 8 - 运行一组测试时忽略某项测试