Regresjonstesting med run-compe-kommandoen

PQTest run-compe-kommandoen er et kraftig verktøy for regresjonstesting, som gjør det mulig å grundig evaluere funksjonene til koblingen og genereringen av kommandotekst. For å illustrere dens allsidighet gir de påfølgende seksjonene ulike eksempler tilpasset ulike scenarioer.

Testinndataformater

Kommandoen run-compare støtter to testinndataformater:

• Uttrykksformat: Et enkelt M-uttrykk (for eksempel et let uttrykk eller funksjonskall). Dette formatet er det enkleste formatet og egner seg for de fleste testscenarier.
• Seksjonsdokumentformat: Et M-seksjonsdokument som inneholder ett eller flere seksjonselementer. Dette formatet er nyttig for tester som krever hjelpefunksjoner, delte verdier eller mer komplekse oppsett.

Når en testfil bruker uttrykksformatet, konverterer PQTest den automatisk til et seksjonsdokument internt før evaluering. Du kan også skrive testinput direkte som et seksjonsdokument.

Uttrykksformateksempel

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

Eksempel på seksjonsdokumentformat

section Test;

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

Når en parameterspørring er gitt, legges parameterspørringen til som et seksjonsmedlem i seksjonsdokumentet. Parameterspørringen evalueres som en del av samme seksjon, slik at testspørringen kan referere direkte til den.

Grunnleggende spørringer

Den enkleste formen for testing er å legge til ett enkelt spørringsuttrykk i en .query.pq fil, som du kan utføre med run-compe-kommandoen . PQTest evaluerer uttrykket og genererer en .pqout (output)fil med samme navn. For eventuelle påfølgende kjøringer sammenligner den utdataene generert fra evalueringen av .query.pq filen med .pqout (ut)filen med samme navn og returnerer utdataene fra evalueringen.

Eksempel 1 - Kjøre run-compe-kommandoen for en spørringsfil når en utdatafil ikke eksisterer

Følgende eksempel utfører en enkelt spørringstestfil ved hjelp av den angitte Power Query-filtypen og genererer utdatafil for å sammenligne.

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

Eksempel 2 - Kjører run-compe-kommandoen for en spørringsfil når en utdatafil ikke eksisterer og FailOnMissingOutputFile-flagget er satt

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

Eksempel 3 - Kjøre run-compere-kommandoen for en spørringsfil med en utdatafil til stede

Følgende eksempel kjører en enkelt spørringstestfil ved hjelp av den angitte Power Query-filtypen, sammenligner den med utdatafilen og returnerer resultatet.

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

Testing med parameterspørring

Parameterspørring er en spørring som kombineres med en testspørring under kjøring, og parameterspørringen kjører først. Denne funksjonaliteten lar deg dele ".query.pq"-filen i to deler: parameterspørringsfilen og testspørringsfilen.

Agnostisk datakildetesting med parameter- og testspørringsformat

Et eksempel på et brukstilfelle der denne funksjonaliteten vil være nyttig, er å opprette en datakildeagnostisk testserie. Du kan bruke parameterspørringen din til å hente data fra datakilden, og ha testspørringen generisk M. Hvis du ønsker å kjøre testene for en annen connector, trenger du bare å legge til/oppdatere parameterspørringen slik at den peker på den spesifikke datakilden.

En viktig forskjell når du bruker en parameterspørring, er at testspørringen følger et annet format. I stedet for å være et formeluttrykk, må det være en M-funksjon som tar én inndataparameter, som representerer tabellen som returneres fra parameterspørringen.

Når en parameterspørring er tilgjengelig, legges parameterspørringen til som et seksjonsmedlem på slutten av testens seksjonsdokument. Test- og parameterinputene evalueres deretter sammen som et enkelt mashup-seksjonsdokument.

La oss si at du har følgende testspørsmål:

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

Hvis du vil konvertere den til en test- og parameterspørring, må du dele dem på følgende måte:

Parameterspørring:

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

Testspørring:

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

Eksempel 4 - Bruk av både parameterspørring og testspørring med run-compe-kommandoen

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

Sammenligning av diagnostikk

Ekstra diagnostisk informasjon kan evalueres ved bruk av run-compe-kommandoen ved å abonnere på en diagnostisk kanal. Når kommandoen run-compare kjøres, gir PQTest ut en .diagnostics fil for hver abonnert kanal som hadde en hendelse. For påfølgende kjøringer sammenligner den diagnostiske hendelsen med sin .diagnostics fil, på samme måte som .pqout.

Eksempel 5 – Abonner på diagnosekanalen ODBC (Open Database Connectivity) for å validere spørringsdelegering

Eksemplet nedenfor viser hvordan du abonnerer på ODBC-kanalen, som registrerer sql-en som genereres av ODBC-driveren når spørringsdelegering brukes.

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

ODBC-diagnosekanalen kan brukes til å bekrefte at en spørring brettes og at den genererer riktig 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

Spørringen brettes nå og genererer følgende ODBC-kommandotekst i filen .diagnostics :

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

Bruke en innstillingsfil

Enhver kommandolinjeparameter for run-compere-kommandoen kan også sendes via en JSON-innstillingsfil. JSON kan ha følgende alternativer:

I tilfelle både kommandolinjeinndata og innstillinger er angitt, prioriteres kommandolinjeinndataene.

Eksempel 6 – Bruke innstillingsfil i stedet for kommandolinjeargumenter

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

Kommandoen tilsvarer følgende kommando:

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

Hvor settings.json er følgende JSON-fil:

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

Testbatterier med run-compare kommando

Et testbatteri er en samling tester som evaluerer flere aspekter av koden. Plasser spørringsfilene i samme mappe, slik at PQTest enkelt kan finne dem. I stedet for å sende et bestemt testfilnavn, angir du mappebanen, og PQTest utfører alle .query.pq-testspørringsfilene i ett enkelt pass.

Eksempel 7 – Kjøre et batteri av tester

Forutsatt at en mappe med navnet test som inneholder følgende filer:

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

Hele testbatteriet kan kjøres ved hjelp av følgende kommandolinje:

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

Ignorerer tester når du kjører et batteri av tester

En test kan ignoreres når du kjører et batteri av tester ved å endre utvidelsen av .query.pq-filen til .query.pq.ignore.

Eksempel 8 – Ignorerer en test når du kjører et batteri av tester

Forutsatt at en mappe med navnet test som inneholder følgende filer:

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

Contoso.testa.query.pq- og contoso.testc.query.pq-filene kjøres, men contoso.testb.query.pq.ignore ignoreres når følgende kommando utføres for å kjøre testbatteriet:

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

Filtreringstester

Alternativet --testFilter lar deg selektivt inkludere eller ekskludere testfiler når du kjører testbatterier. Dette alternativet bruker glob-mønstre for å matche filstier og kan spesifiseres flere ganger for å lage komplekse filtreringsregler.

Inklusjonsfiltre

Spesifiser hvilke filer som skal inkluderes i testkjøringen ved bruk av standard glob-mønstre.

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

Eksklusjonsfiltre

Spesifiser hvilke filer som skal utelukkes fra testkjøringen ved å bruke prefikset ! for å angi eksklusjonsmønstre.

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

Flere filtre

Flere --testFilter alternativer kan kombineres for å lage kompleks filtreringslogikk:

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

Filteroppførsel

• Implisitt inkludering: Når ingen inklusjonsfiltre er spesifisert, **/*.query.pq anvendes automatisk.
• Små og små bokstaver: Alle mønstre stemmer overens med små og små bokstaver.
• Rekkefølgeuavhengig: Rekkefølgen på filtrene påvirker ikke resultatet.
• Stiformat: Bruk fremoverskråstreker (/) i mønstre for plattformuavhengig kompatibilitet.

Eksempler på glob-mønstre

Listing av testfiler uten kjøring

Alternativet --listOnly lar deg forhåndsvise hvilke testfiler som ville blitt kjørt med run-compe-kommandoen uten å faktisk kjøre testene. Dette alternativet er nyttig for å verifisere testoppdagelse og filteradferd.

Eksempel 9 - Listing av testfiler

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

Utdataene inneholder følgende felt:

• SourcePath: QueryFilePath-verdien som ble gitt til kommandoen (fra -q alternativet).
• TestFilters: En liste over alle TestFilter-verdier som ble brukt (fra --testFilter alternativer).
• Tester: Et array av testfilobjekter, hvor hvert objekt inneholder:
  • Test: Filnavnet på testfilen.
  • RelativePath: Stien relativt til basistestkatalogen spesifisert av -q.
  • AbsolutePath: Den fullstendige Absolute-stien til testfilen.

Kombinasjon med testfiltre

Alternativet --listOnly respekterer alle --testFilter alternativer, slik at du kan forhåndsvise effekten av filtrene dine:

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

Håndtering av mellomtestresultater

Kommandoen run-compare genererer mellomliggende filer under testkjøringen, inkludert faktiske testutdata (.pqout) og diagnostikkfiler (.diagnostics). Som standard opprettes disse filene på et midlertidig sted med en datobasert undermappestruktur og ryddes automatisk etter at testkjøringen er fullført.

Du kan kontrollere denne oppførselen ved hjelp av to alternativer:

• --intermediateTestResultsFolder | -itrf: Spesifiserer en egendefinert mappesti for lagring av mellomliggende testresultater.
• --persistIntermediateTestResults | -pitr: Beholder mellomresultatene etter at testutførelsen er fullført.

Eksempel 10 - Bruker en egendefinert mellomliggende mappe og vedvarende resultater

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

Mellomliggende mappestruktur

Når du spesifiserer en mellomliggende testresultatmappe, lager PQTest en datobasert undermappestruktur for å organisere testresultatene:

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

Oppryddingsatferd

Oppryddingsoppførselen avhenger av om du spesifiserer en mellomliggende mappe og om du bruker persist-flagget: