Regressionstest med run-compe-kommandoen

PQTest run-compe-kommandoen er et kraftfuldt værktøj til regressionstest, som gør det muligt for dig grundigt at evaluere connectorens funktioner og genereringen af kommandoteksten. For at illustrere dens alsidighed giver de følgende afsnit forskellige eksempler tilpasset forskellige scenarier.

Testinddataformater

Kommandoen run-compare understøtter to testinputformater:

• Udtryksformat: Et enkelt M-udtryk (for eksempel et let udtryk eller funktionskald). Dette format er det simpleste format og er egnet til de fleste testscenarier.
• Sektionsdokumentformat: Et M-sektionsdokument , der indeholder en eller flere sektionsmedlemmer. Dette format er nyttigt til tests, der kræver hjælpefunktioner, delte værdier eller mere komplekse opsætninger.

Når en testfil bruger udtryksformatet, konverterer PQTest den automatisk til et sektionsdokument internt før evaluering. Du kan også skrive dit testinput direkte som et sektionsdokument.

Eksempel på udtryksformat

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

Eksempel på sektionsdokumentformat

section Test;

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

Når en parameterforespørgsel leveres, tilføjes parameterforespørgslen som et sektionsmedlem til sektionsdokumentet. Parameterforespørgslen evalueres som en del af samme sektion, hvilket gør det muligt for testforespørgslen at referere direkte til den.

Grundlæggende forespørgsler

Den simpleste form for test er at tilføje et enkelt forespørgselsudtryk til en .query.pq fil, som du kan udføre ved hjælp af kommandoen run-verce . PQTest evaluerer udtrykket og genererer en .pqout (output)fil med samme navn. For eventuelle efterfølgende kørsler sammenligner den outputtet genereret fra evalueringen af .query.pq filen med .pqout (output)filen med samme navn og returnerer outputtet af evalueringen.

Eksempel 1 - Kør run-compere-kommandoen for en forespørgselsfil, når en outputfil ikke eksisterer

Følgende eksempel udfører en enkelt forespørgselstestfil ved hjælp af det angivne Power Query-filtypenavn og genererer outputfil, der skal sammenlignes.

<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 - Kør run-compere-kommandoen for en forespørgselsfil, når en outputfil ikke eksisterer, og FailOnMissingOutputFile-flaget er sat

<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 - Kørsel af run-compe-kommandoen for en forespørgselsfil med en outputfil til stede

Følgende eksempel udfører en enkelt forespørgselstestfil ved hjælp af det angivne Power Query-filtypenavn, sammenligner den med outputfilen 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"
  }
]

Test med parameterforespørgsel

Parameterforespørgsel er en forespørgsel, der kombineres med en testforespørgsel på kørselstidspunktet, hvor parameterforespørgslen kører først. Denne funktionalitet lader dig opdele filen ".query.pq" i to dele: parameterforespørgselsfilen og testforespørgselsfilen.

Test af agnostisk datakilde med parameter- og testforespørgselsformat

Et eksempel på en use case, hvor denne funktionalitet ville være nyttig, er at oprette en agnostisk testpakke til datakilder. Du kan bruge din parameterforespørgsel til at hente data fra datakilden og lade testforespørgslen være generisk M. Hvis du vil køre testene for en anden connector, behøver du kun at tilføje/opdatere parameterforespørgslen, så den peger på den specifikke datakilde.

En vigtig forskel ved brug af en parameterforespørgsel er, at testforespørgslen følger et andet format. I stedet for at være et formeludtryk skal det være en M-funktion, der tager én inputparameter, som repræsenterer den tabel, der returneres fra parameterforespørgslen.

Når en parameterforespørgsel leveres, tilføjes parameterforespørgslen som et sektionsmedlem til slutningen af testens sektionsdokument. Test- og parameterinputtene evalueres derefter sammen som et enkelt Mashup-sektionsdokument.

Lad os sige, at du har følgende testforespørgsel:

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 parameterforespørgsel, skal du opdele dem på følgende måde:

Parameterforespørgsel:

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

Testforespørgsel:

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

Eksempel 4 - Brug af både parameterforespørgsel og testforespørgsel med run-compare 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 af diagnosticering

Ekstra diagnostisk information kan evalueres, når man bruger run-compere-kommandoen ved at abonnere på en diagnostisk kanal. Når kommandoen run-compare køres, udleverer PQTest en .diagnostics fil for hver abonneret kanal, der havde en hændelse. For efterfølgende kørsler sammenligner den diagnostiske hændelse med sin .diagnostics fil, ligesom .pqout.

Eksempel 5 – Abonnement på ODBC-diagnosticeringskanalen (Open Database Connectivity) for at validere forespørgselsdelegering

I følgende eksempel kan du se, hvordan du abonnerer på ODBC-kanalen, som registrerer sql, der genereres af ODBC-driveren, når forespørgselsdelegering bruges.

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

ODBC-diagnosticeringskanalen kan bruges til at bekræfte, at en forespørgsel foldes, og at den genererer den korrekte 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

Forespørgslen foldes nu 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`"
  }
]

Brug af en indstillingsfil

Enhver kommandolinje-inputparameter for run-compere-kommandoen kan også sendes via en JSON-indstillingsfil. JSON kan have følgende indstillinger:

Hvis der angives både kommandolinjeinput og indstillinger, prioriteres kommandolinjeinputtet.

Eksempel 6 – Brug af indstillingsfilen i stedet for kommandolinjeargumenter

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

Kommandoen svarer til 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 test, der evaluerer flere aspekter af din kode. Placer forespørgselsfilerne i den samme mappe, så PQTest nemt kan finde dem. I stedet for at overføre et bestemt testfilnavn skal du angive mappestien, og PQTest udfører alle .query.pq-testforespørgselsfilerne i et enkelt gennemløb.

Eksempel 7 – Kørsel af et batteri af test

Hvis der antages en mappe med navnet test, der indeholder følgende filer:

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

Hele testbatteriet kan køres på følgende kommandolinje:

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

Ignorerer test, når du kører et batteri af test

En test kan ignoreres, når du kører et batteri af test, ved at ændre filtypenavnet for .query.pq-filen til .query.pq.ignore.

Eksempel 8 – Ignorerer en test, når der køres et batteri af test

Hvis der antages en mappe med navnet test, der indeholder følgende filer:

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

Filerne contoso.testa.query.pq og contoso.testc.query.pq køres, men contoso.testb.query.pq.ignore ignoreres, når følgende kommando udføres for at køre testbatteriet:

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

Filtreringstests

Muligheden --testFilter giver dig mulighed for selektivt at inkludere eller udelukke testfiler, når du kører testbatterier. Denne mulighed bruger glob-mønstre til at matche filstier og kan specificeres flere gange for at skabe komplekse filtreringsregler.

Inklusionsfiltre

Angiv, hvilke filer der skal inkluderes i testkørslen ved brug af standard glob-mønstre.

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

Udelukkelsesfiltre

Angiv, hvilke filer der skal udelukkes fra testkørslen ved at bruge præfikset ! til at angive udelukkelsesmønstre.

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

Flere filtre

Flere --testFilter muligheder kan kombineres for at skabe kompleks filtreringslogik:

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

Filteradfærd

• Implicit inklusion: Når der ikke er angivet inklusionsfiltre, **/*.query.pq anvendes automatisk.
• Kasus-insensitiv: Alle mønstre matcher kasus-insensitivt.
• Rækkefølgeuafhængig: Rækkefølgen af filtre påvirker ikke resultatet.
• Stiformat: Brug fremadrettet skråstreger (/) i mønstre for kompatibilitet på tværs af platforme.

Eksempler på glob-mønstre

Visning af testfiler uden udførelse

Muligheden --listOnly giver dig mulighed for at forhåndsvise, hvilke testfiler der ville blive udført med run-compe-kommandoen uden faktisk at køre testene. Denne mulighed er nyttig til at verificere testopdagelse og filteradfærd.

Eksempel 9 - Listelse af 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"
        }
    ]
}

Outputtet indeholder følgende felter:

• SourcePath: QueryFilePath-værdien, der blev givet til kommandoen (from -q option).
• TestFilters: En liste over alle TestFilter-værdier, der blev anvendt (fra --testFilter muligheder).
• Tester: Et array af testfilobjekter, hvor hvert objekt indeholder:
  • Test: Filnavnet på testfilen.
  • RelativePath: Stien relativt til basistestmappen specificeret af -q.
  • AbsolutePath: Den fulde absolute-sti til testfilen.

Kombinering med testfiltre

Muligheden --listOnly respekterer alle --testFilter muligheder og giver dig mulighed for at forhåndsvise effekten af dine filtre:

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

Håndtering af mellemtestresultater

Kommandoen run-compare genererer mellemliggende filer under testkørselen, inklusive faktiske testoutputfiler (.pqout) og diagnostiske filer (.diagnostics). Som standard oprettes disse filer midlertidigt med en datobaseret undermappestruktur og bliver automatisk ryddet op efter testkørslen.

Du kan kontrollere denne adfærd ved hjælp af to muligheder:

• --intermediateTestResultsFolder | -itrf: Specificerer en brugerdefineret mappesti til lagring af mellemliggende testresultater.
• --persistIntermediateTestResults | -pitr: Beholder de mellemliggende resultater efter testudførelsen er afsluttet.

Eksempel 10 - Brug af en brugerdefineret mellemliggende mappe og vedvarende resultater

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

Mellemliggende mappestruktur

Når du angiver en mellemliggende testresultatmappe, opretter PQTest en datobaseret undermappestruktur til at organisere testresultater:

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

Oprydningsadfærd

Oprydningsadfærden afhænger af, om du angiver en mellemliggende mappe, og om du bruger persist-flaget: