Test de régression avec la commande run-compare

La commande run-compare PQTest est un outil puissant pour les tests de régression, ce qui vous permet d’évaluer soigneusement les fonctions du connecteur et la génération de texte de commande. Pour illustrer sa polyvalence, les sections suivantes fournissent différents exemples adaptés à différents scénarios.

Tester les formats d’entrée

La commande run-compare prend en charge deux formats d’entrée de test :

• Format d’expression : expression M unique (par exemple, une expression ou un let appel de fonction). Ce format est le format le plus simple et convient à la plupart des scénarios de test.
• Format du document de section : document de section M qui contient un ou plusieurs membres de section. Ce format est utile pour les tests qui nécessitent des fonctions d’assistance, des valeurs partagées ou des configurations plus complexes.

Lorsqu’un fichier de test utilise le format d’expression, PQTest le convertit automatiquement en document de section en interne avant l’évaluation. Vous pouvez également écrire votre entrée de test directement en tant que document de section.

Exemple de format d’expression

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

Exemple de format de document de section

section Test;

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

Lorsqu’une requête de paramètre est fournie, la requête de paramètre est ajoutée en tant que membre de section au document de section. La requête de paramètre est évaluée dans le cadre de la même section, ce qui permet à la requête de test de la référencer directement.

Requêtes de base

La forme de test la plus simple consiste à ajouter une expression de requête unique à un .query.pq fichier, que vous pouvez exécuter à l’aide de la commande run-compare . PQTest évalue l’expression et génère un .pqout fichier (sortie) portant le même nom. Pour toutes les exécutions suivantes, elle compare la sortie générée à partir de l’évaluation du .query.pq fichier avec le .pqout fichier (sortie) portant le même nom et retourne la sortie de l’évaluation.

Exemple 1 : exécution de la commande run-compare pour un fichier de requête lorsqu’un fichier de sortie n’existe pas

L’exemple suivant exécute un fichier de test de requête unique à l’aide de l’extension Power Query spécifiée et génère le fichier de sortie à comparer.

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

Exemple 2 : Exécution de la commande run-compare pour un fichier de requête lorsqu’un fichier de sortie n’existe pas et que l’indicateur FailOnMissingOutputFile est défini

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

Exemple 3 : exécution de la commande run-compare pour un fichier de requête avec un fichier de sortie présent

L’exemple suivant exécute un fichier de test de requête unique à l’aide de l’extension Power Query spécifiée, le compare au fichier de sortie et retourne le résultat.

<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 avec la requête de paramètre

La requête de paramètre est une requête combinée à une requête de test au moment de l’exécution, avec la requête de paramètre en cours d’exécution en premier. Cette fonctionnalité vous permet de fractionner le fichier .query.pq en deux parties : le fichier de requête de paramètre et le fichier de requête de test.

Test de source de données agnostique avec format de requête paramétrique et de test

Un exemple de cas d’usage dans lequel cette fonctionnalité serait utile consiste à créer une suite de tests indépendant de source de données. Vous pouvez utiliser votre requête de paramètre pour récupérer des données à partir de la source de données et avoir la requête de test M générique. Si vous souhaitez exécuter les tests d’un autre connecteur, vous devez uniquement ajouter/mettre à jour la requête de paramètre pour pointer vers cette source de données spécifique.

Une différence clé lors de l’utilisation d’une requête de paramètre est que la requête de test suit un format différent. Au lieu d’être une expression de formule, il doit s’agir d’une fonction M qui accepte un paramètre d’entrée, qui représente la table retournée par la requête de paramètre.

Lorsqu’une requête de paramètre est fournie, la requête de paramètre est ajoutée en tant que membre de section à la fin du document de section du test. Les entrées de test et de paramètre sont ensuite évaluées ensemble en tant que document de section Mashup unique.

Supposons que vous ayez la requête de test suivante :

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

Pour la convertir en requête de test et de paramètre, vous devez les fractionner comme suit :

Requête de paramètre :

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

Requête de test :

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

Exemple 4 - Utilisation de la requête de paramètre et de la requête de test avec la commande 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"
  }
]

Comparaison des diagnostics

Des informations de diagnostic supplémentaires peuvent être évaluées lors de l’utilisation de la commande run-compare en s’abonnant à un canal de diagnostic. Lorsque la commande run-compare est exécutée, PQTest génère un .diagnostics fichier pour chaque canal abonné ayant un événement. Pour toutes les exécutions suivantes, elle compare l’événement de diagnostic à son .diagnostics fichier, similaire à .pqout.

Exemple 5 : Abonnement au canal de diagnostic ODBC (Open Database Connectivity) pour valider le pliage des requêtes

L’exemple suivant montre comment s’abonner au canal ODBC, qui capture n’importe quel SQL généré par le pilote ODBC lors de l’utilisation du pliage des requêtes.

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

Le canal de diagnostic ODBC peut être utilisé pour vérifier qu'une requête se replie et qu'elle génère le SQL correct.

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 requête se plie et génère désormais le texte de commande ODBC suivant dans le .diagnostics fichier :

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

Utilisation d’un fichier de paramètres

Tout paramètre d’entrée de ligne de commande pour la commande run-compare peut également être transmis via un fichier de paramètres JSON. Le json peut avoir les options suivantes :

Dans le cas où l’option d’entrée de ligne de commande et de paramètres est fournie, l’entrée de ligne de commande est hiérarchisée.

Exemple 6 : utilisation du fichier de paramètres au lieu des arguments de ligne de commande

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

La commande équivaut à la commande suivante :

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

Où settings.json est le fichier JSON suivant :

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

Tester les batteries avec la commande run-compare

Une batterie de tests est une collection de tests qui évaluent plusieurs aspects de votre code. Placez les fichiers de requête dans le même dossier afin que PQTest puisse les localiser facilement. Au lieu de passer un nom de fichier de test spécifique, spécifiez le chemin du dossier et PQTest exécute tous les fichiers de requête de test .query.pq dans un seul passage.

Exemple 7 - Exécution d’une batterie de tests

En supposant qu’un dossier nommé test contient les fichiers suivants :

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

La batterie de test entière peut être exécutée à l’aide de la ligne de commande suivante :

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

Ignorer les tests lors de l’exécution d’une batterie de tests

Un test peut être ignoré lors de l’exécution d’une batterie de tests en modifiant l’extension du fichier .query.pq en .query.pq.ignore.

Exemple 8 - Ignorer un test lors de l’exécution d’une batterie de tests

En supposant qu’un dossier nommé test contient les fichiers suivants :

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

Les fichiers contoso.testa.query.pq et contoso.testc.query.pq sont exécutés, mais contoso.testb.query.pq.ignore est ignoré lorsque la commande suivante est exécutée pour exécuter la batterie de test :

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

Tests de filtrage

L’option --testFilter vous permet d’inclure ou d’exclure sélectivement des fichiers de test lors de l’exécution de batteries de test. Cette option utilise des modèles glob pour faire correspondre les chemins d’accès aux fichiers et peut être spécifiée plusieurs fois pour créer des règles de filtrage complexes.

Filtres d’inclusion

Spécifiez les fichiers à inclure dans l’exécution de test à l’aide de modèles glob standard.

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

Filtres d’exclusion

Spécifiez les fichiers à exclure de la série de tests à l’aide du ! préfixe pour indiquer les modèles d’exclusion.

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

Filtres multiples

Plusieurs --testFilter options peuvent être combinées pour créer une logique de filtrage complexe :

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

Comportement de filtre

• Inclusion implicite : lorsqu’aucun filtre d’inclusion n’est spécifié, **/*.query.pq il est appliqué automatiquement.
• Insensible à la casse : tous les modèles correspondent indifféremment à la casse.
• Indépendant de l’ordre : l’ordre des filtres n’affecte pas le résultat.
• Format du chemin d’accès : utilisez des barres obliques (/) dans des modèles pour la compatibilité entre plateformes.

Exemples de modèles Glob

Liste des fichiers de test sans exécution

L’option --listOnly vous permet d’afficher un aperçu des fichiers de test qui seraient exécutés par la commande run-compare sans exécuter réellement les tests. Cette option est utile pour vérifier le comportement de détection et de filtre des tests.

Exemple 9 - Liste des fichiers de 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"
        }
    ]
}

La sortie contient les champs suivants :

• SourcePath : la valeur QueryFilePath fournie à la commande (à partir de l’option -q).
• TestFilters : liste de toutes les valeurs TestFilter qui ont été appliquées (à partir d’options --testFilter ).
• Tests : tableau d’objets de fichier de test, où chaque objet contient :
  • Test : nom de fichier du fichier de test.
  • RelativePath : chemin relatif au répertoire de test de base spécifié par -q.
  • AbsolutePath : chemin absolu complet du fichier de test.

Combinaison avec des filtres de test

L’option --listOnly respecte toutes les --testFilter options, ce qui vous permet d’afficher un aperçu de l’effet de vos filtres :

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

Gestion des résultats de test intermédiaires

La commande run-compare génère des fichiers intermédiaires pendant l’exécution du test, y compris les fichiers de sortie de test réels (.pqout) et les fichiers de diagnostic (.diagnostics). Par défaut, ces fichiers sont créés à un emplacement temporaire avec une structure de sous-dossier basée sur des dates et sont automatiquement nettoyés une fois l’exécution du test terminée.

Vous pouvez contrôler ce comportement à l’aide de deux options :

• --intermediateTestResultsFolder | -itrf: spécifie un chemin d’accès de dossier personnalisé pour stocker les résultats de test intermédiaires.
• --persistIntermediateTestResults | -pitr: conserve les résultats intermédiaires une fois l’exécution du test terminée.

Exemple 10 : utilisation d’un dossier intermédiaire personnalisé et de résultats persistants

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

Structure de dossiers intermédiaire

Lorsque vous spécifiez un dossier de résultats de test intermédiaire, PQTest crée une structure de sous-dossier basée sur des dates pour organiser les résultats des tests :

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

Comportement de nettoyage

Le comportement de nettoyage dépend de la spécification d’un dossier intermédiaire et de l’utilisation de l’indicateur persistant :