Microsoft. Testing.Platform (MTP)-CLI-Optionsreferenz

Dieser Artikel enthält einen zentralen Einstiegspunkt für MTP-Befehlszeilenoptionen.

Important

Plattformoptionen stehen von MTP selbst zur Verfügung. Erweiterungsoptionen sind nur verfügbar, wenn jede Zieltestanwendung das Erweiterungspaket registriert, das sie bereitstellt. Fügen Sie das Paket direkt hinzu, oder verwenden Sie eine Test-SDK-Konfiguration oder ein Profil, die es enthält. Wenn eine Testanwendung die Erweiterung nicht registriert, schlägt die Ausführung mit Dem Exitcode 5 fehl, da die Option nicht erkannt wird.

Plattformoptionen

• @

  Gibt den Namen der Antwortdatei an. Der Name der Antwortdatei muss dem `@`-Zeichen, ohne Leerzeichen zwischen dem `@`-Zeichen und dem Namen der Antwortdatei, direkt folgen.

  Optionen in einer Antwortdatei werden so interpretiert, als ob sie an dieser Stelle in der Befehlszeile vorhanden wären. Sie können das umgekehrte Schrägstrichzeichen \ nicht verwenden, um Linien zu verketten. Die Verwendung einer Antwortdatei ist bei sehr langen Befehlen hilfreich, die die Terminalgrenzen überschreiten können. Sie können eine Antwortdatei mit Inline-Befehlszeilenargumenten kombinieren. Beispiel:

  ./TestExecutable.exe @"filter.rsp" --timeout 10s
  

  wobei filter.rsp den folgenden Inhalt haben kann:

  --filter "A very long filter"
  

  Alternativ können Sie mit einer einzelnen RSP-Datei wie folgt sowohl Timeout als auch Filter angeben:

  ./TestExecutable.exe @"arguments.rsp"
  

  --filter "A very long filter" --timeout 10s
  

  Hinweis

  Bei Verwendung dotnet testdes SDK-Befehlszeilenparsers wird ein Token-pro-Line-Ansatz verwendet, bei dem jede Zeile in der Antwortdatei als einzelnes Token behandelt wird. In diesem Fall muss jedes Argument in einer separaten Zeile stehen:

  --filter
  A very long filter
  --timeout
  10s
  

• --config-file

  Gibt eine testconfig.json-Datei an.

• --debug

  Hält die Testausführung beim Start an, damit Sie einen Debugger an den Testprozess anfügen können. Entspricht dem Festlegen der TESTINGPLATFORM_WAIT_ATTACH_DEBUGGERUmgebungsvariablen auf 1. Wird auf Browserplattformen nicht unterstützt.

  Hinweis

  Diese Option ist ab Version 1.9.0 in MTP verfügbar. Sie ersetzt die vorherige --debug-wait-attach Option (eingeführt in MTP 1.6.0); der alte Name wurde entfernt und darf nicht mehr verwendet werden.

• --diagnostic

  Aktiviert die Diagnoseprotokollierung. Die Standardprotokollebene ist Trace. Für jede Testquelle schreibt MTP <asm>_<tfm>_<arch>_<timestamp>.diag. Wenn ein Zeitstempel kollidiert, fügt MTP einen Prozess- und Leistungsindikatorsuffix hinzu, anstatt die vorhandene Datei zu überschreiben.

• --diagnostic-synchronous-write

  Zwingt den integrierten Dateilogger, Protokolle synchron zu schreiben. Nützlich für Szenarien, in denen keine Protokolleinträge verloren gehen sollen (bei Prozessabsturz). Dadurch wird die Testausführung verlangsamt.

  Hinweis

  Verfügbar in MTP ab Version 2.0.0. Sie ersetzt die vorherige --diagnostic-filelogger-synchronouswrite Option, die in MTP 2.0.0 entfernt wurde.

• --diagnostic-output-directory

  Das Ausgabeverzeichnis der Diagnoseprotokollierung. Wird es nicht angegeben, wird die Datei im Standardverzeichnis TestResults generiert.

• --diagnostic-file-prefix

  Das Präfix für den Namen der Protokolldatei. Der Standardwert lautet <asm>_<tfm>_<arch>.

  Hinweis

  Verfügbar in MTP ab Version 2.0.0. Sie ersetzt die vorherige --diagnostic-output-fileprefix Option, die in MTP 2.0.0 entfernt wurde.

• --diagnostic-verbosity

  Definiert den Ausführlichkeitsgrad, wenn die Option --diagnostic verwendet wird. Verfügbare Werte sind Trace, Debug, Information, Warning, Error oder Critical.

• --enable-dynamic-extensions

  Aktiviert das Laden von Erweiterungen, die von *.testingplatformextensions.json Manifestdateien neben der Testanwendung deklariert werden. Dynamische Erweiterungen sind standardmäßig deaktiviert. Sicherheitsanforderungen und das Manifestschema finden Sie unter "Dynamisches Laden von Erweiterungen".

  Hinweis

  Diese Option ist ab Version 2.4.0 in MTP verfügbar.

• --exit-on-process-exit

  Beenden Sie den Testprozess, wenn ein abhängiger Prozess beendet wird. Die PID muss angegeben werden.

• --filter-uid

  Filtert die auszuführenden Tests anhand ihrer Testknoten-UIDs. Akzeptiert eine oder mehrere UIDs.

  Framework-Autoren müssen TestNodeUidListFilter für die Ermittlung und Ausführung berücksichtigen. Anleitungen zur Implementierung finden Sie unter Anforderungsfilter berücksichtigen.

  Hinweis

  Diese Option ist ab Version 1.8.0 in MTP verfügbar. Ab MTP 2.3.0 können Sie --filter-uid nicht mit --treenode-filter kombinieren; die Angabe beider Optionen führt bei der Befehlszeilenvalidierung zu einem Fehler mit dem Exitcode InvalidCommandLine.

• --help

  Gibt eine Beschreibung zur Verwendung des Befehls aus.

• --ignore-exit-code

  Erlaubt, dass einige Nicht-Null-Exitcodes ignoriert werden und stattdessen als 0 zurückgegeben werden. Weitere Informationen finden Sie im Abschnitt Ignorieren spezifischer Exitcodes.

• --info

  Zeigt erweiterte Informationen zur .NET Testanwendung an, z. B.:

  • Die Plattform.
  • Zur Umgebung.
  • Jeder registrierte Kommandozeilenanbieter, wie z. B. name, version, description und options.
  • Jedes registrierte Tool, wie z. B. seine command, name, version, description und alle Kommandozeilen-Anbieter.

  Dieses Feature wird verwendet, um Erweiterungen zu verstehen, die dieselbe Befehlszeilenoption registrieren, oder um die Änderungen bei den verfügbaren Optionen zwischen mehreren Versionen einer Erweiterung (oder der Plattform) zu ermitteln.

• --list-tests

  Listet die verfügbaren Tests auf, ohne sie auszuführen. Verwendet optional ein Argument, das das Ausgabeformat steuert: text (Standard, lesbar) oder json.

  Strukturierte Metadaten und ein Beispiel finden Sie unter Discover-Tests im JSON-Format.

  Hinweis

  Das json Ausgabeformat ist ab Version 2.3.0 in MTP verfügbar.

• --maximum-failed-tests

  Gibt eine positive maximale Anzahl von Testfehlern an. Wenn die Fehleranzahl das Maximum erreicht, fordert MTP einen ordnungsgemäßen Stopp an und gibt Exit-Code 13zurück. Tests, die bereits ausgeführt werden, können abgeschlossen werden, sodass die endgültige Fehleranzahl das Maximum überschreiten kann. Weitere Informationen finden Sie unter MTP-Exitcodes.

  Frameworkautoren müssen IGracefulStopTestExecutionCapability implementieren und registrieren und den Optionsanbieter mit AddMaximumFailedTestsService registrieren. Die Funktionsdokumentation enthält Implementierungs- und Registrierungsbeispiele. Testautoren müssen die Funktion nicht implementieren, wenn ihr Framework die Option bereits unterstützt.

  Hinweis

  Dieses Feature ist ab Version 1.5 in MTP verfügbar.

• --minimum-expected-tests

  Gibt eine positive Mindestanzahl von Tests an, die ausgeführt werden müssen. Wenn die Ausführung weniger Tests ausführt, einschließlich Null, wird sie mit Code 9beendet. Ein explizites Minimum ersetzt --zero-tests-policy.

  Mit dotnet test gilt diese Option für den gesamten Durchlauf, wenn sie vor -- angegeben wird, und für jedes Testmodul, wenn sie nach -- angegeben wird. Weitere Informationen finden Sie unter "Gesamte Ausführung" und "Mindestwerte pro Modul".

  Hinweis

  --minimum-expected-tests 0 ist ungültig. Verwenden Sie --ignore-exit-code 8, um den Exitcode von zero-tests zu unterdrücken.

• --no-banner

  Deaktiviert das Startbanner, die Copyrightnachricht und das Telemetriebanner. Derselbe Effekt kann durch die TESTINGPLATFORM_NOBANNER Variablen oder DOTNET_NOLOGOumgebungsvariablen erreicht werden.

• --results-directory

  Gibt das Verzeichnis an, in dem MTP Testergebnisse platziert. Wenn das Verzeichnis nicht vorhanden ist, wird es erstellt. Der Standardwert liegt TestResults im Arbeitsverzeichnis von MTP. Wenn Sie eine Testanwendung direkt starten, wird das Arbeitsverzeichnis standardmäßig auf das Verzeichnis festgelegt, das die Testanwendung enthält.

  Mit dotnet test richtet sich die Standardeinstellung nach den SDK- und MTP-Versionen. Informationen zu dem gemeinsam genutzten aufrufrelativen Stamm, den Versionsanforderungen und den Artefaktlayoutüberschreibungen finden Sie unter „Ergebnisse und Artefakte“.

  Um mehrere Testanwendungen zu isolieren, übergeben Sie die SDK-Option --results-directory-layout per-module vor --. Diese Option gehört zum SDK, nicht zum MTP-Kern und ist nicht verfügbar, wenn Sie eine Testanwendung direkt starten.

• --server

  Startet die Testanwendung im JSON-RPC Servermodus für die Editor-, IDE- oder Toolintegration. Lassen Sie den Wert aus oder verwenden Sie jsonrpc. Informationen zu einem unterstützten Client, der nur als Quelle fungiert, finden Sie unter MTP-Servermodus.

  Important

  Der dotnettestcli Wert und die zugehörigen Transportargumente sind intern für die .NET SDK-Integration. Übergeben Sie sie nicht manuell.

• --show-slowest-tests

  Zeigt die angeforderte Anzahl der langsamsten Tests in der Terminalzusammenfassung an. Wenn eine Ausführung mehrere Testmodule enthält, meldet MTP die langsamsten Tests für jedes Modul.

  Hinweis

  Diese Option ist ab Version 2.4.0 in MTP verfügbar.

• --timeout

  Eine globale Zeitüberschreitung für die Testausführung. Nimmt ein Argument als Zeichenfolge im Format <value>[h|m|s] an, wobei <value> ein Float ist.

• --treenode-filter

  Filtert die auszuführenden Tests mithilfe eines Baumfilterausdrucks. Baumfilter bieten für anspruchsvolle Szenarien flexiblere Abgleichmöglichkeiten als --filter.

  Hinweis

  Ab MTP 2.3.0 können Sie --treenode-filter nicht mit --filter-uid kombinieren; die Angabe beider Optionen führt bei der Befehlszeilenvalidierung zu einem Fehler mit dem Exitcode InvalidCommandLine.

• --zero-tests-policy

  Steuert, ob eine Ausführung, die keine Tests ausführt, weil jeder Test übersprungen wurde, als Fehler behandelt wird. Gültige Werte sind allow-skipped (Standard) und strict. Mit allow-skipped ist eine vollständig übersprungene Ausführung erfolgreich. Bei strict, schlägt es mit Exit-Code 8fehl. Ein expliziter --minimum-expected-tests Wert ersetzt diese Richtlinie und verwendet Exitcode 9 , wenn das Minimum nicht erfüllt ist.

  Hinweis

  Diese Option ist ab Version 2.3.0 in MTP verfügbar. Übergeben Sie mit dotnet test die Option nach --, um sie an jedes Testmodul weiterzuleiten. Wenn Sie kein globales Minimum festlegen, bestimmt das .NET 11 SDK die vollständige Nulltestbewertung separat. Weitere Informationen finden Sie unter "Gesamte Ausführung" und "Mindestwerte pro Modul".

Tests als JSON erkennen

Ab MTP 2.3.0 verwenden Sie --list-tests json, um Tests als maschinenlesbares JSON-Dokument zu erkennen, anstatt die für Menschen lesbare Liste zu analysieren:

dotnet Contoso.MyTests.dll --list-tests json --no-banner

Führen Sie die kompilierte Testanwendung anstelle eines Befehls aus, der auch die Buildausgabe schreibt. Erfassen Sie die Standardausgabe getrennt vom Standardfehler, und überprüfen Sie den Prozessausgangscode, bevor Sie das Dokument nutzen. Geben Sie Startmeldungen für Anwendungen und Erweiterungen in maschinenlesbaren Modi nicht auf der Standardausgabe aus.

Kombinieren Sie die Ermittlung nicht mit reinen Ausführungsoptionen wie --report-trx. Wenn testconfig.json diese Optionen aktiviert, verwenden Sie --config-file mit einer separaten Ermittlungskonfiguration, die diese Optionen auslässt.

Das Dokument enthält ein schemaVersion Array und ein tests Array. Jeder Test enthält uid und displayName. Optionale Felder enthalten type, location, traits und properties, wenn das Test-Framework die entsprechenden Metadaten bereitstellt. Beispielsweise kann ein Test mit einer Environment Eigenschaft folgendes erzeugen:

{
  "schemaVersion": 1,
  "tests": [
    {
      "uid": "<test-uid>",
      "displayName": "ConnectToService",
      "traits": [
        { "key": "Environment", "value": "Staging" }
      ]
    }
  ]
}

Sowohl properties als auch traits verwenden Arrays von Schlüssel-Wert-Einträgen, nicht JSON-Objekte. Gehen Sie nicht davon aus, dass Schlüssel eindeutig sind. Traits stellen öffentliche TestMetadataProperty Werte dar, einschließlich MSTest-Kategorien und benutzerdefinierter TestProperty Werte. Das properties Array enthält serialisierbare Zeichenfolgeneigenschaften, die von der Plattform- oder Kompatibilitätsebene bereitgestellt werden. Es exportiert nicht jede im Speicher vorhandene Eigenschaft, und sein interner SerializableKeyValuePairStringProperty-Typ ist keine API, die für externe Frameworks oder Erweiterungen bestimmt ist.

Verwenden Sie die ermittelten UIDs mit --filter-uid, um ausgewählte Tests auszuführen. Verwenden Sie für einen typierten .NET Client mit Discovery, Ausführung, Abbruch und Liveupdates den MTP-Servermodus.

Erweiterungsoptionen nach Szenario

Verwenden Sie die folgende Tabelle, um das Paket und die Optionen der einzelnen Erweiterungen zu finden. Ein Test-SDK-Profil kann ein Paket anstelle eines direkten Paketverweises bereitstellen.

Scenario	Erforderliche Komponente	Funktionsdokumentation
Erfassung der Code-Abdeckung	Microsoft.Testing.Extensions.CodeCoverage oder coverlet.MTP	Codeabdeckung
Sammeln von Daten eines Absturzes oder von Blockaden	Microsoft.Testing.Extensions.CrashDump oder Microsoft.Testing.Extensions.HangDump	Daten eines Absturzes oder von Blockaden
Generieren von Testberichten	Das Erweiterungspaket für das ausgewählte Format, z. B. Microsoft.Testing.Extensions.TrxReport	Testberichte
Anpassen der Terminalausgabe	MTP Core (kein zusätzliches Paket)	Terminalausgabe
Wiederholen fehlgeschlagener Tests	Microsoft.Testing.Extensions.Retry	Wiederholen.

Entdecken von Optionen in Ihrer Test-App

Führen Sie Ihr Testprogramm mit --help aus, oder führen Sie dotnet test --help im MTP-Modus aus, um die für Ihren aktuellen Erweiterungssatz verfügbaren Optionen aufzulisten.

Ab MTP 2.4 schlägt ein unbekannter Optionsfehler einen eindeutig übereinstimmenden Optionsnamen vor, wenn eins verfügbar ist. Wenn die Option zu einer bekannten Microsoft bereitgestellten Erweiterung gehört, die die Testanwendung nicht registriert hat, identifiziert der Fehler auch das NuGet-Paket, das die Option bereitstellt.

Für eine erweiterte Diagnose von registrierten Anbietern und Optionen führen Sie --info aus.

Registriertes Tool ausführen

Einige Erweiterungen registrieren Befehle, die Artefakte verarbeiten, anstatt Tests auszuführen. Übergeben Sie den Befehlsnamen als erstes Positionsargument der Testanwendung. Die TRX-Erweiterung stellt z. B. ms-trxcompare und merge-trx bereit.

Führen Sie die Anwendung mit --info aus, um registrierte Tools und ihre Befehlszeilenoptionen aufzulisten. Diese Befehle gehören zur Testanwendung; sie sind keine dotnet tool Befehle.

Siehe auch

• MTP-Übersicht
• MTP-Features
• Testen mit dotnet test