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

PQTest run-compare コマンドは回帰テスト用の強力なツールであり、コネクタの機能とコマンド テキストの生成を十分に評価できます。 その多様性を説明するために、以降のセクションでは、さまざまなシナリオに合わせて調整されたさまざまな例を示します。

テスト入力形式

run-compare コマンドは、次の 2 つのテスト入力形式をサポートしています。

• 式の形式: 単一の M 式 ( let 式や関数呼び出しなど)。 この形式は最も簡単な形式であり、ほとんどのテスト シナリオに適しています。
• セクション ドキュメント形式: 1 つ以上のセクション メンバーを含む M セクション ドキュメント 。 この形式は、ヘルパー関数、共有値、またはより複雑な設定を必要とするテストに役立ちます。

テスト ファイルで式形式が使用されている場合、PQTest は評価前に内部的にセクション ドキュメントに自動的に変換します。 テスト入力をセクション ドキュメントとして直接記述することもできます。

式フォーマットの例

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

セクション ドキュメント形式の例

section Test;

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

パラメーター クエリを指定すると、パラメーター クエリがセクション ドキュメントのセクション メンバーとして追加されます。 パラメーター クエリは同じセクションの一部として評価され、テスト クエリで直接参照できるようになります。

基本的なクエリ

テストの最も簡単な形式は、 .query.pq ファイルに単一のクエリ式を追加することです。これは、 run-compare コマンドを使用して実行できます。 PQTest は式を評価し、同じ名前の .pqout (出力) ファイルを生成します。 後続の実行では、 .query.pq ファイルの評価から生成された出力と、同じ名前の .pqout (出力) ファイルが比較され、評価の出力が返されます。

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

次の例では、指定した Power Query 拡張機能を使用して 1 つのクエリ テスト ファイルを実行し、比較する出力ファイルを生成します。

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

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

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

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

次の例では、指定した Power Query 拡張機能を使用して 1 つのクエリ テスト ファイルを実行し、出力ファイルと比較して結果を返します。

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

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

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

特定のデータ ソースに依存しない形で、パラメーターおよびテスト クエリ形式を使用したテスト

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

パラメーター クエリを使用する場合の主な違いは、テスト クエリが別の形式に従う点です。 数式ではなく、パラメーター クエリから返されるテーブルを表す 1 つの入力パラメーターを受け取る M 関数である必要があります。

パラメーター クエリを指定すると、パラメーター クエリがセクション メンバーとしてテストのセクション ドキュメントの末尾に追加されます。 テスト入力とパラメーター入力は、1 つの Mashup セクション ドキュメントとしてまとめて評価されます。

次のテスト クエリがあるとします。

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

診断の比較

run-compare コマンドを使用する場合は、診断チャネルをサブスクライブすることで、追加の診断情報を評価できます。 run-compare コマンドを実行すると、PQTest は、イベントを持つサブスクライブされたチャネルごとに.diagnostics ファイルを出力します。 それ以降の実行では、診断イベントとその .diagnostics ファイルが比較されます ( .pqoutと同様)。

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

次の例では、ODBC チャネルをサブスクライブする方法を示します。このチャネルは、クエリ フォールディングが使用されるときに ODBC ドライバーによって生成されたすべての SQL をキャプチャします。

<Path to PQTest.exe>.\PQTest.exe run-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`"
  }
]

設定ファイルの使用

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

コマンド ライン入力と設定オプションの両方が指定されている場合は、コマンド ライン入力が優先されます。

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

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

このコマンドは、次のコマンドと同じです。

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

ここで settings.json は次の JSON ファイルです。

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

run-compare コマンドを使用してバッテリをテストする

テスト バッテリーは、コードの複数の側面を評価するテストのコレクションです。 PQTest で簡単に検索できるように、クエリ ファイルを同じフォルダーに配置します。 特定のテスト ファイル名を渡す代わりに、フォルダー パスを指定し、PQTest はすべての .query.pq テスト クエリ ファイルを 1 回のパスで実行します。

例 7 - 一連のテストを実行する

次のファイルを含む test という名前のフォルダーを想定します。

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

テスト バッテリ全体は、次のコマンド ラインを使用して実行できます。

<Path to PQTest.exe>.\PQTest.exe run-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.exe run-compare -e contoso.mez -q .\test

テストのフィルタリングプロセス

--testFilter オプションを使用すると、テスト バッテリの実行時にテスト ファイルを選択的に含めたり除外したりできます。 このオプションでは、glob パターンを使用してファイル パスを照合し、複数回指定して複雑なフィルター処理規則を作成できます。

包含フィルター

標準の glob パターンを使用して、テスト実行に含めるファイルを指定します。

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

除外フィルター

除外パターンを示す ! プレフィックスを使用して、テスト実行から除外するファイルを指定します。

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

複数のフィルター

複数の --testFilter オプションを組み合わせて、複雑なフィルター処理ロジックを作成できます。

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

フィルターの動作

• 暗黙的包含: 包含フィルターが指定されていない場合、 **/*.query.pq が自動的に適用されます。
• 大文字と小文字を区別しない: すべてのパターンで大文字と小文字が区別されません。
• 順序に依存しない: フィルターの順序は結果に影響しません。
• パス形式: クロスプラットフォーム互換性のためにパターンではフォワードスラッシュ (/) を使用します。

Glob パターンの例

実行せずにテスト ファイルを一覧表示する

--listOnly オプションを使用すると、実際にテストを実行することなく、run-compare コマンドによって実行されるテスト ファイルをプレビューできます。 このオプションは、テストの検出とフィルターの動作を確認する場合に役立ちます。

例 9 - テスト ファイルの一覧表示

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

出力には、次のフィールドが含まれています。

• SourcePath: コマンドに指定された QueryFilePath 値 ( -q オプションから)。
• TestFilters: ( --testFilter オプションから) 適用されたすべての TestFilter 値の一覧。
• テスト: テスト ファイル オブジェクトの配列。各オブジェクトには次のものが含まれます。
  • テスト: テスト ファイルのファイル名。
  • RelativePath: -qによって指定された基本テスト ディレクトリに対する相対パス。
  • AbsolutePath: テスト ファイルへの完全な絶対パス。

テスト フィルターとの組み合わせ

--listOnly オプションでは、すべての--testFilterオプションが考慮されるため、フィルターの効果をプレビューできます。

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

中間テスト結果の管理

run-compare コマンドは、実際のテスト出力ファイル (.pqout) や診断ファイル (.diagnostics) など、テストの実行中に中間ファイルを生成します。 既定では、これらのファイルは日付ベースのサブフォルダー構造を持つ一時的な場所に作成され、テストの実行が完了した後に自動的にクリーンアップされます。

この動作は、次の 2 つのオプションを使用して制御できます。

• --intermediateTestResultsFolder | -itrf: 中間テスト結果を格納するためのカスタム フォルダー パスを指定します。
• --persistIntermediateTestResults | -pitr: テストの実行が完了した後も中間結果を保持します。

例 10 - カスタム中間フォルダーの使用と結果の永続化

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

中間フォルダー構造

中間テスト結果フォルダーを指定すると、PQTest によって、テスト結果を整理するための日付ベースのサブフォルダー構造が作成されます。

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

クリーンアップの動作

クリーンアップの動作は、中間フォルダーを指定するかどうかと、永続化フラグを使用するかどうかによって異なります。