compare コマンドを使用した回帰テスト

[アーティクル]
03/25/2024

PQTest の compare コマンドは、コネクタの機能とコマンドテキストの生成を詳しく評価できる、回帰テスト用の優れたツールです。その幅広い用途を説明するために、以降のセクションではさまざまなシナリオに合わせたいろいろな例を紹介します。

基本的なクエリ

最も簡単なテスト方法は、.query.pq ファイルに単一のクエリ式を追加し、compare コマンドを使ってこのファイルを実行することです。 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 - 出力ファイルが存在する場合にクエリファイルに対して 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": "Passed",
        "SerializedSource": null,
        "SourceError": null,
        "OutputError": null
      }
    ],
    "Status": "Passed",
    "Type": "PQTest.Expression"
  }
]

パラメータークエリを使用したテスト

パラメータークエリは、ランタイム時にテストクエリと組み合わされて、最初に実行されるクエリです。この機能を使用すると、PQ/テストクエリファイルをパラメータークエリファイルとテストクエリファイルの 2 つに分割できます。

パラメーターおよびテストクエリ形式を使用した非依存型データソーステスト

この機能が役立つユースケースの例として挙げられるのは、データソースに依存しないテストスイートの作成です。パラメータークエリを使用してデータソースからデータを取得し、テストクエリを汎用 M にすることができます。別のコネクタのテストを実行する場合は、その特定のデータソースを指すようにパラメータークエリを追加または更新するだけです。

パラメータークエリを使用する場合の主な違いは、テストクエリが別の形式に従う点です。数式ではなく、パラメータークエリから返されるテーブルを表す 1 つの入力パラメーターを受け取る 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 コマンドの使用時は、診断チャネルをサブスクライブすることで、追加の診断情報を評価できます。 compare コマンドを実行すると、PQTest は、イベントが発生したサブスクライブされているチャネルごとに .diagnostics ファイルを出力します。それ以降の実行では、診断イベントと、.pqout に似たその .diagnostics ファイルが比較されます。

例 5 - クエリフォールディングを検証するために ODBC (Open Database Connectivity) 診断チャネルをサブスクライブする

次の例では、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

クエリがフォールディングされ、次の ODBC コマンドテキストが .diagnostics ファイルに生成されています。

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

設定ファイルの使用

compare コマンドのコマンドライン入力パラメーターは、JSON 設定ファイルを使用して渡すこともできます。 JSON には次のオプションがあります。

オプション	Type	説明
ExtensionPaths	array	コネクタファイル (mez/pqx) を指すパスの配列。
FailOnMissingOutputFile	[bool]	compare で PQOut ファイルを生成せず、ファイルが存在しない場合は失敗します。
FailOnFoldingFailure	[bool]	クエリフォールディングエラーがスローされた場合、比較は失敗します。
ParameterQueryFilePath	string	M 式を含むクエリファイル。ランタイム時にテストクエリファイルと組み合わされます。一般的なユースケースは、複数のテストクエリのデータを取得する M 式を指定するための単一のパラメータークエリファイルを用意することです。
QueryFilePath	string	テストする M 式 (.pq) を含むクエリファイル。
TrxReportPath	string	TRX (Visual Studio テスト結果ファイル) の結果ファイルと、指定したパス内の各テストの個別の JSON ファイルを生成します。
DiagnosticChannels	array	テスト実行にアタッチする診断チャネルの名前 (クエリフォールディングステートメントをキャプチャするための 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 - テストバッテリーを実行する

test という名前のフォルダーに次のファイルがあるとします。

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 - テストバッテリーの実行時にテストを無視する

test という名前のフォルダーに次のファイルがあるとします。

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

次のコマンドを実行してテストバッテリーを実行すると、contoso.testa.query.pq ファイルと contoso.testc.query.pq ファイルは実行されますが、contoso.testb.query.pq.ignore は無視されます。

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

次の方法で共有

compare コマンドを使用した回帰テスト

基本的なクエリ

例 1 - 出力ファイルが存在しない場合にクエリファイルに対して compare コマンドを実行する

例 2 - 出力ファイルが存在せず、FailOnMissingOutputFile フラグが設定されている場合にクエリファイルに対して compare コマンドを実行する

例 3 - 出力ファイルが存在する場合にクエリファイルに対して compare コマンドを実行する

パラメータークエリを使用したテスト

パラメーターおよびテストクエリ形式を使用した非依存型データソーステスト

例 4 - compare コマンドでパラメータークエリとテストクエリの両方を使用する

診断の比較

例 5 - クエリフォールディングを検証するために ODBC (Open Database Connectivity) 診断チャネルをサブスクライブする

設定ファイルの使用

例 6 - コマンドライン引数の代わりに設定ファイルを使用する

compare コマンドを使用したテストバッテリー

例 7 - テストバッテリーを実行する

テストバッテリーの実行時にテストを無視する

例 8 - テストバッテリーの実行時にテストを無視する

フィードバック

その他のリソース

次の方法で共有

compare コマンドを使用した回帰テスト

基本的なクエリ

例 1 - 出力ファイルが存在しない場合にクエリ ファイルに対して compare コマンドを実行する

例 2 - 出力ファイルが存在せず、FailOnMissingOutputFile フラグが設定されている場合にクエリ ファイルに対して compare コマンドを実行する

例 3 - 出力ファイルが存在する場合にクエリ ファイルに対して compare コマンドを実行する

パラメーター クエリを使用したテスト

パラメーターおよびテスト クエリ形式を使用した非依存型データ ソース テスト

例 4 - compare コマンドでパラメーター クエリとテスト クエリの両方を使用する

診断の比較

例 5 - クエリ フォールディングを検証するために ODBC (Open Database Connectivity) 診断チャネルをサブスクライブする

設定ファイルの使用

例 6 - コマンド ライン引数の代わりに設定ファイルを使用する

compare コマンドを使用したテスト バッテリー

例 7 - テスト バッテリーを実行する

テスト バッテリーの実行時にテストを無視する

例 8 - テスト バッテリーの実行時にテストを無視する

フィードバック

その他のリソース

例 1 - 出力ファイルが存在しない場合にクエリファイルに対して compare コマンドを実行する

例 2 - 出力ファイルが存在せず、FailOnMissingOutputFile フラグが設定されている場合にクエリファイルに対して compare コマンドを実行する

例 3 - 出力ファイルが存在する場合にクエリファイルに対して compare コマンドを実行する

パラメータークエリを使用したテスト

パラメーターおよびテストクエリ形式を使用した非依存型データソーステスト

例 4 - compare コマンドでパラメータークエリとテストクエリの両方を使用する

例 5 - クエリフォールディングを検証するために ODBC (Open Database Connectivity) 診断チャネルをサブスクライブする

例 6 - コマンドライン引数の代わりに設定ファイルを使用する

compare コマンドを使用したテストバッテリー

例 7 - テストバッテリーを実行する

テストバッテリーの実行時にテストを無視する

例 8 - テストバッテリーの実行時にテストを無視する