Regressietests met de opdracht run-compare

De opdracht PQTest run-compare is een krachtig hulpprogramma voor regressietests, zodat u de functies van de connector en het genereren van opdrachttekst grondig kunt evalueren. Om zijn veelzijdigheid te illustreren, bieden de volgende secties verschillende voorbeelden die zijn afgestemd op verschillende scenario's.

Invoerindelingen testen

De opdracht run-compare ondersteunt twee testinvoerindelingen:

• Expressie-indeling: één M-expressie (bijvoorbeeld een let expressie of functie-aanroep). Deze indeling is de eenvoudigste indeling en is geschikt voor de meeste testscenario's.
• Indeling van sectiedocument: een M-sectiedocument met een of meer sectieleden. Deze indeling is handig voor tests waarvoor helperfuncties, gedeelde waarden of complexere instellingen nodig zijn.

Wanneer een testbestand de expressie-indeling gebruikt, converteert PQTest het automatisch intern naar een sectiedocument vóór de evaluatie. U kunt uw testinvoer ook rechtstreeks schrijven als een sectiedocument.

Voorbeeld van expressie-indeling

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

Voorbeeld van sectiedocumentindeling

section Test;

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

Wanneer er een parameterquery wordt opgegeven, wordt de parameterquery toegevoegd als sectielid aan het sectiedocument. De parameterquery wordt geëvalueerd als onderdeel van dezelfde sectie, zodat de testquery er rechtstreeks naar kan verwijzen.

Basisqueries

De eenvoudigste vorm van testen is het toevoegen van één query-expressie aan een .query.pq bestand, dat u kunt uitvoeren met behulp van de opdracht run-compare . PQTest evalueert de expressie en genereert een .pqout (uitvoer)-bestand met dezelfde naam. Voor eventuele volgende uitvoeringen wordt de uitvoer die is gegenereerd op basis van de evaluatie van .query.pq vergeleken met het .pqout-bestand met dezelfde naam en wordt de uitvoer van de evaluatie geretourneerd.

Voorbeeld 1: run-compare-opdracht uitvoeren voor een querybestand wanneer er geen uitvoerbestand bestaat

In het volgende voorbeeld wordt één querytestbestand uitgevoerd met behulp van de opgegeven Power Query-extensie en wordt een uitvoerbestand gegenereerd om te vergelijken.

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

Voorbeeld 2: uitvoeren van opdracht uitvoeren-vergelijken voor een querybestand wanneer er geen uitvoerbestand bestaat en failOnMissingOutputFile vlag is ingesteld

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

Voorbeeld 3 - De run-compare-opdracht uitvoeren voor een querybestand met een aanwezig uitvoerbestand

In het volgende voorbeeld wordt één querytestbestand uitgevoerd met behulp van de opgegeven Power Query-extensie, wordt het vergeleken met het uitvoerbestand en wordt het resultaat geretourneerd.

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

Testen met parameterquery

Parameterquery is een query die wordt gecombineerd met een testquery tijdens runtime, waarbij de parameterquery eerst wordt uitgevoerd. Met deze functionaliteit kunt u het bestand .query.pq splitsen in twee delen: het parameterquerybestand en het testquerybestand.

Agnostische gegevensbrontests met parameter- en testquery-indeling

Een voorbeeld van een use-case waarbij deze functionaliteit nuttig is, is het maken van een gegevensbronagnostisch testpakket. U kunt de parameterquery gebruiken om gegevens op te halen uit de gegevensbron en de testquery algemeen M te laten zijn. Als u de tests voor een andere connector wilt uitvoeren, hoeft u alleen de parameterquery toe te voegen/bij te werken om naar die specifieke gegevensbron te verwijzen.

Een belangrijk verschil bij het gebruik van een parameterquery is dat de testquery een andere indeling volgt. In plaats van een formule-expressie te zijn, moet het een M-functie zijn die één invoerparameter gebruikt, die de tabel vertegenwoordigt die wordt geretourneerd door de parameterquery.

Wanneer er een parameterquery wordt opgegeven, wordt de parameterquery toegevoegd als sectielid aan het einde van het sectiedocument van de test. De test- en parameterinvoer worden vervolgens samen geëvalueerd als één Mashup-sectiedocument.

Stel dat u de volgende testquery hebt:

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

Als u deze wilt converteren naar een test- en parameterquery, moet u deze als volgt splitsen:

Parameterquery:

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

Testquery:

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

Voorbeeld 4: zowel parameterquery als testquery gebruiken met de run-compare-opdracht

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

Diagnostische gegevens vergelijken

Extra diagnostische gegevens kunnen worden geëvalueerd wanneer u de opdracht run-compare gebruikt door u te abonneren op een diagnostisch kanaal. Wanneer de opdracht run-compare wordt uitgevoerd, voert PQTest een .diagnostics bestand uit voor elk geabonneerd kanaal met een gebeurtenis. Voor eventuele volgende uitvoeringen wordt de diagnostische gebeurtenis vergeleken met het .diagnostics bijbehorende bestand, vergelijkbaar met .pqout.

Voorbeeld 5: abonneren op het diagnostische ODBC-kanaal (Open Database Connectivity) om query folding te valideren

In het volgende voorbeeld ziet u hoe u zich abonneert op het ODBC-kanaal, dat sql vastlegt die door het ODBC-stuurprogramma wordt gegenereerd wanneer query folding wordt gebruikt.

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

Het diagnostische ODBC-kanaal kan worden gebruikt om te controleren of een query wordt gevouwen en of de juiste SQL wordt gegenereerd.

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

De query wordt nu gevouwen en genereert de volgende ODBC-opdrachttekst in het .diagnostics bestand:

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

Een instellingenbestand gebruiken

Elke opdrachtregelinvoerparameter voor de opdracht run-compare kan ook worden doorgegeven via een JSON-instellingenbestand. De JSON kan de volgende opties hebben:

In het geval dat zowel opdrachtregelinvoer als instellingenoptie worden opgegeven, krijgt de opdrachtregelinvoer prioriteit.

Voorbeeld 6: het instellingenbestand gebruiken in plaats van opdrachtregelargumenten

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

De opdracht is gelijk aan de volgende opdracht:

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

Waar settings.json het volgende JSON-bestand is:

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

Batterijen testen met run-compare opdracht

Een testbatterij is een verzameling tests die meerdere aspecten van uw code evalueren. Plaats de querybestanden in dezelfde map, zodat PQTest ze gemakkelijk kan vinden. In plaats van een specifieke testbestandsnaam door te geven, geeft u het mappad op en voert PQTest alle .query.pq-testquerybestanden in één wachtwoord uit.

Voorbeeld 7: Een batterij van tests uitvoeren

Ervan uitgaande dat er een map is met de naam 'test', die de volgende bestanden bevat:

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

De volledige testbatterij kan worden uitgevoerd met behulp van de volgende opdrachtregel:

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

Tests negeren bij het uitvoeren van een batterij van tests

Een test kan worden genegeerd bij het uitvoeren van een batterij van tests door de extensie van het .query.pq-bestand te wijzigen in .query.pq.ignore.

Voorbeeld 8: een test negeren bij het uitvoeren van een batterij van tests

Ervan uitgaande dat er een map is met de naam 'test', die de volgende bestanden bevat:

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

De bestanden contoso.testa.query.pq en contoso.testc.query.pq worden uitgevoerd, maar contoso.testb.query.pq.ignore wordt genegeerd wanneer de volgende commando wordt uitgevoerd om de testbatterij uit te voeren.

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

Tests voor filteren

Met de --testFilter optie kunt u selectief testbestanden opnemen of uitsluiten bij het uitvoeren van testbatterijen. Deze optie maakt gebruik van glob-patronen om bestandspaden te vinden en kan meerdere keren worden opgegeven om complexe filterregels te maken.

Insluitingsfilters

Geef op welke bestanden in de testuitvoering moeten worden opgenomen met behulp van standaard globpatronen.

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

Uitsluitingsfilters

Geef op welke bestanden moeten worden uitgesloten van de testuitvoering met behulp van het ! voorvoegsel om uitsluitingspatronen aan te geven.

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

Meerdere filters

Meerdere --testFilter opties kunnen worden gecombineerd om complexe filterlogica te maken:

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

Filtergedrag

• Impliciete opname: wanneer er geen insluitingsfilters worden opgegeven, **/*.query.pq wordt automatisch toegepast.
• Niet-hoofdlettergevoelig: alle patronen komen ongeacht hoofdletters overeen.
• Volgorde onafhankelijk: De volgorde van filters heeft geen invloed op het resultaat.
• Padindeling: Gebruik schuine strepen (/) in patronen voor platformonafhankelijke compatibiliteit.

Voorbeelden van glob-patroon

Testbestanden weergeven zonder uitvoering

Met de --listOnly optie kunt u een voorbeeld bekijken van welke testbestanden door de opdracht run-compare worden uitgevoerd zonder de tests daadwerkelijk uit te voeren. Deze optie is handig voor het verifiëren van testdetectie en filtergedrag.

Voorbeeld 9: Testbestanden vermelden

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

De uitvoer bevat de volgende velden:

• SourcePath: de QueryFilePath-waarde die is opgegeven voor de opdracht (van -q optie).
• TestFilters: een lijst met alle TestFilter-waarden die zijn toegepast (uit --testFilter opties).
• Tests: Een matrix van testbestandsobjecten, waarin elk object het volgende bevat:
  • Test: De bestandsnaam van het testbestand.
  • RelativePath: het pad ten opzichte van de basistestmap die is opgegeven door -q.
  • AbsolutePath: het volledige absolute pad naar het testbestand.

Combineren met testfilters

De --listOnly optie respecteert alle --testFilter opties, zodat u een voorbeeld van het effect van uw filters kunt bekijken:

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

Tussenliggende testresultaten beheren

Met de opdracht run-compare worden tussenliggende bestanden gegenereerd tijdens het uitvoeren van de test, inclusief werkelijke testuitvoerbestanden (.pqout) en diagnostische bestanden (.diagnostics). Deze bestanden worden standaard gemaakt op een tijdelijke locatie met een datumgebaseerde submapstructuur en worden automatisch opgeschoond nadat de testuitvoering is voltooid.

U kunt dit gedrag beheren met behulp van twee opties:

• --intermediateTestResultsFolder | -itrf: Hiermee geeft u een aangepast mappad voor het opslaan van tussenliggende testresultaten.
• --persistIntermediateTestResults | -pitr: Bewaart de tussenliggende resultaten nadat de testuitvoering is voltooid.

Voorbeeld 10: een aangepaste tussenliggende map gebruiken en de resultaten behouden

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

Intermediaire mapstructuur

Wanneer u een map met tussenliggende testresultaten opgeeft, maakt PQTest een op datum gebaseerde submapstructuur om testresultaten te organiseren:

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

Opschoningsgedrag

Het opschoongedrag is afhankelijk van of u een tussenliggende map opgeeft en of u de persistente vlag gebruikt: