Test di regressione con il comando run-compare

Il comando PQTest run-compare è uno strumento potente per i test di regressione, consentendo di valutare accuratamente le funzioni del connettore e la generazione di testo del comando. Per illustrare la versatilità, le sezioni successive forniscono vari esempi personalizzati per diversi scenari.

Formati di test di input

Il comando run-compare supporta due formati di input di test:

• Formato espressione: una singola espressione M, ad esempio una chiamata a un'espressione o a una let funzione. Questo formato è il formato più semplice ed è adatto per la maggior parte degli scenari di test.
• Formato documento sezione: documento di sezione M che contiene uno o più membri di sezione. Questo formato è utile per i test che richiedono funzioni helper, valori condivisi o configurazioni più complesse.

Quando un file di test usa il formato di espressione, PQTest lo converte automaticamente in un documento di sezione internamente prima della valutazione. È anche possibile scrivere l'input di test direttamente come documento di sezione.

Esempio di formato di espressione

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

Esempio di formato del documento di sezione

section Test;

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

Quando viene fornita una query di parametri, la query del parametro viene aggiunta come membro di sezione al documento della sezione. La query del parametro viene valutata come parte della stessa sezione, consentendo alla query di test di farvi riferimento direttamente.

Ricerche di base

La forma più semplice di test consiste nell'aggiungere una singola espressione di query a un .query.pq file, che è possibile eseguire usando il comando run-compare . PQTest valuta l'espressione e genera un .pqout file (output) con lo stesso nome. Per le esecuzioni successive, confronta l'output generato dalla valutazione del .query.pq file con il .pqout file (output) con lo stesso nome e restituisce l'output della valutazione.

Esempio 1 - Esecuzione del comando run-compare per un file di query quando un file di output non esiste

L'esempio seguente esegue un singolo file di test di query usando l'estensione di Power Query specificata e genera il file di output da confrontare.

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

Esempio 2 - Esecuzione del comando run-compare per un file di query quando un file di output non esiste e viene impostato il flag FailOnMissingOutputFile

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

Esempio 3 - Esecuzione del comando run-compare per un file di query con un file di output presente

L'esempio seguente esegue un singolo file di test di query usando l'estensione di Power Query specificata, lo confronta con il file di output e restituisce il risultato.

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

Test con query sui parametri

La query sui parametri è una query combinata con una query di test in fase di esecuzione, con la query del parametro in esecuzione per prima. Questa funzionalità consente di suddividere il file ".query.pq" in due parti: il file di query dei parametri e il file di query di test.

Test dell'origine dati indipendente con parametro e formato di query di test

Un esempio di caso d'uso in cui questa funzionalità sarebbe utile consiste nel creare un gruppo di test indipendente dall'origine dati. È possibile usare la query del parametro per recuperare i dati dall'origine dati e fare in modo che la query di test sia generica M. Se si desidera eseguire i test per un altro connettore, è sufficiente aggiungere/aggiornare la query del parametro in modo che punti a tale origine dati specifica.

Una differenza fondamentale quando si usa una query di parametri è che la query di test segue un formato diverso. Anziché essere un'espressione di formula, deve essere una funzione M che accetta un parametro di input, che rappresenta la tabella restituita dalla query del parametro.

Quando viene specificata una query di parametri, la query del parametro viene aggiunta come membro di sezione alla fine del documento della sezione del test. Gli input di test e parametri vengono quindi valutati insieme come singolo documento di sezione Mashup.

Supponiamo di avere la seguente query di test:

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

Per convertirlo in una query di test e di parametri, è necessario suddividerli nel modo seguente:

Query dei parametri

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

Query di test:

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

Esempio 4- Uso di query di parametri e query di test con il comando 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"
  }
]

Confronto delle diagnosi

È possibile valutare informazioni di diagnostica aggiuntive quando si usa il comando run-compare sottoscrivendo un canale di diagnostica. Quando viene eseguito il comando run-compare , PQTest restituisce un .diagnostics file per ogni canale sottoscritto con un evento. Per tutte le esecuzioni successive, confronta l'evento diagnostico con il file .diagnostics relativo, simile a .pqout.

Esempio 5 : sottoscrizione al canale di diagnostica ODBC (Open Database Connectivity) per convalidare la riduzione delle query

Nell'esempio seguente viene illustrato come sottoscrivere il canale ODBC, che acquisisce qualsiasi SQL generato dal driver ODBC quando viene usata la riduzione delle query.

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

Il canale di diagnostica ODBC può essere usato per verificare che una query sia piegata e che generi il codice SQL corretto.

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

La query ora si comprime e genera il testo del comando ODBC seguente nel file .diagnostics:

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

Uso di un file di impostazioni

Qualsiasi parametro di input della riga di comando per il comando run-compare può essere passato anche tramite un file di impostazioni JSON. Il codice JSON può avere le opzioni seguenti:

Nel caso in cui siano disponibili sia l'opzione input della riga di comando che l'opzione delle impostazioni, l'input della riga di comando è prioritario.

Esempio 6 - Uso del file delle impostazioni anziché degli argomenti della riga di comando

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

Il comando equivale al comando seguente:

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

Dove settings.json è il file JSON seguente:

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

Testare le batterie con il comando run-compare

Una batteria di test è una raccolta di test che valutano più aspetti del codice. Posizionare i file di query nella stessa cartella in modo che PQTest possa individuarli facilmente. Anziché passare un nome file di test specifico, specificare il percorso della cartella e PQTest esegue tutti i file di query di test .query.pq in un singolo passaggio.

Esempio 7 - Esecuzione di una batteria di test

Supponendo che una cartella denominata test contenga i file seguenti:

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

L'intera batteria di test può essere eseguita usando la riga di comando seguente:

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

Ignorare i test durante l'esecuzione di una batteria di test

Un test può essere ignorato quando si esegue una batteria di test modificando l'estensione del file .query.pq in .query.pq.ignore.

Esempio 8 - Ignorare un test durante l'esecuzione di una batteria di test

Supponendo che una cartella denominata test contenga i file seguenti:

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

I file contoso.testa.query.pq e contoso.testc.query.pq vengono eseguiti, ma contoso.testb.query.pq.ignore viene ignorato quando viene eseguito il comando seguente per eseguire la batteria di test:

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

Filtro dei test

L'opzione --testFilter consente di includere o escludere in modo selettivo i file di test durante l'esecuzione di batterie di test. Questa opzione usa modelli GLOB per trovare le corrispondenze con i percorsi dei file e può essere specificata più volte per creare regole di filtro complesse.

Filtri di inclusione

Specificare i file da includere nell'esecuzione del test usando modelli GLOB standard.

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

Filtri di esclusione

Specificare i file da escludere dall'esecuzione del test usando il prefisso per indicare i ! modelli di esclusione.

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

Filtri multipli

È possibile combinare più --testFilter opzioni per creare una logica di filtro complessa:

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

Comportamento del filtro

• Inclusione implicita: quando non vengono specificati filtri di inclusione, **/*.query.pq viene applicato automaticamente.
• Senza distinzione tra maiuscole e minuscole: tutti i modelli corrispondono senza distinzione tra maiuscole e minuscole.
• Indipendente dall'ordine: l'ordine dei filtri non influisce sul risultato.
• Formato percorso: usare le barre oblique (/) nei pattern per la compatibilità multipiattaforma.

Esempi di modelli Glob

Elenco dei file di test senza esecuzione

L'opzione --listOnly consente di visualizzare in anteprima i file di test che verrebbero eseguiti dal comando run-compare senza eseguire effettivamente i test. Questa opzione è utile per verificare il comportamento di individuazione e filtro dei test.

Esempio 9 - Elenco dei file di test

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

L'output contiene i campi seguenti:

• SourcePath: valore di QueryFilePath fornito al comando (dall'opzione -q ).
• TestFilters: elenco di tutti i valori TestFilter applicati (dalle --testFilter opzioni).
• Test: matrice di oggetti file di test, in cui ogni oggetto contiene:
  • Test: nome file del file di test.
  • RelativePath: percorso relativo alla directory di test di base specificata da -q.
  • AbsolutePath: percorso assoluto completo del file di test.

Combinazione con i filtri di test

L'opzione --listOnly rispetta tutte le --testFilter opzioni, consentendo di visualizzare in anteprima l'effetto dei filtri:

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

Gestione dei risultati intermedi dei test

Il comando run-compare genera file intermedi durante l'esecuzione dei test, inclusi i file di output dei test effettivi (.pqout) e i file di diagnostica (.diagnostics). Per impostazione predefinita, questi file vengono creati in un percorso temporaneo con una struttura di sottocartella basata su data e vengono puliti automaticamente al termine dell'esecuzione del test.

È possibile controllare questo comportamento usando due opzioni:

• --intermediateTestResultsFolder | -itrf: specifica un percorso di cartella personalizzato per l'archiviazione dei risultati intermedi del test.
• --persistIntermediateTestResults | -pitr: mantiene i risultati intermedi al termine dell'esecuzione del test.

Esempio 10- Uso di una cartella intermedia personalizzata e salvataggio permanente dei risultati

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

Struttura di cartelle intermedia

Quando si specifica una cartella dei risultati del test intermedio, PQTest crea una struttura di sottocartella basata su data per organizzare i risultati del test:

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

Comportamento di pulizia

Il comportamento di pulizia dipende dal fatto che si specifichi una cartella intermedia e se si usa il flag di salvataggio permanente: