Microsoft.Testing.Platform (MTP)-Konfigurationseinstellungen

MTP unterstützt die Verwendung von Konfigurationsdateien und Umgebungsvariablen zum Konfigurieren des Verhaltens der Testplattform. In diesem Artikel werden die Konfigurationseinstellungen beschrieben, die Sie zum Konfigurieren der Testplattform verwenden können.

testconfig.json

Die Testplattform verwendet eine Konfigurationsdatei mit dem Namen [appname].testconfig.json , um das Verhalten der Testplattform zu konfigurieren. Die testconfig.json Datei ist eine JSON-Datei, die Konfigurationseinstellungen für die Testplattform enthält.

Die dateitestconfig.json hat die folgende Struktur:

{
    "platformOptions": {
        "resultDirectory": "./TestResults"
    }
}

Die Plattform erkennt und lädt automatisch die [appname].testconfig.json Datei im Ausgabeverzeichnis des Testprojekts (in der Nähe der ausführbaren Datei).

Wenn Sie Microsoft.Testing.Platform.MSBuild verwenden, können Sie einfach eine testconfig.json Datei erstellen, die automatisch in [appname] umbenannt.testconfig.jsonund in das Ausgabeverzeichnis des Testprojekts verschoben wird.

Ab MTP 1.5 können Sie das Befehlszeilenargument --config-file verwenden, um den Pfad zum testconfig.jsonanzugeben. Diese Datei hat Vorrang vor der [appname]-.testconfig.json Datei.

Hinweis

Die [appname]-.testconfig.json Datei wird bei nachfolgenden Builds überschrieben.

Verwenden einer zentralisierten testconfig.json

Wenn Sie eine einzelne testconfig.json von mehreren Testprojekten gemeinsam nutzen möchten, können Sie sie an einem zentralen Ort ablegen und über --config-file angeben. Wenn MSBuild verfügbar ist (z. B. dotnet test oder dotnet run), können Sie die MSBuild-Eigenschaft TestingPlatformCommandLineArguments verwenden, um das Argument automatisch zu übergeben. Wenn Sie dies zu einem Directory.Build.props im Repositorystamm hinzufügen, wird sichergestellt, dass alle Testprojekte dieselbe Konfiguration verwenden:

<PropertyGroup>
  <TestingPlatformCommandLineArguments>
    $(TestingPlatformCommandLineArguments) --config-file $(MSBuildThisFileDirectory)testconfig.json
  </TestingPlatformCommandLineArguments>
</PropertyGroup>

Konfigurationsrangfolge

Wenn dieselbe Einstellung auf mehrere Arten angegeben werden kann, wertet MTP diese in der folgenden Reihenfolge aus (die erste Übereinstimmung zählt):

  1. Befehlszeilenargumente (z. B --results-directory. )
  2. Umgebungsvariablen
  3. einstellungen fürtestconfig.json
  4. Voreingestellte Standardwerte

Plattformoptionen

Der platformOptions Abschnitt der dateitestconfig.json konfiguriert das Kernverhalten der Testplattform. In der folgenden Tabelle sind alle unterstützten Plattformoptionen aufgeführt:

Eingabe Vorgabe Description
resultDirectory TestResults Das Verzeichnis, in dem die Testergebnisse platziert werden. Kann ein relativer Pfad (aufgelöst aus dem aktuellen Arbeitsverzeichnis) oder ein absoluter Pfad sein. Die --results-directory Befehlszeilenoption hat Vorrang.
exitProcessOnUnhandledException false Wenn auf true festgelegt, wird der Testhostprozess bei unbehandelten Ausnahmen sofort beendet, anstatt ein geordnetes Herunterfahren zu ermöglichen. Die TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION Umgebungsvariable (Werte 1 oder 0) hat Vorrang.

Hinweis

Für fortgeschrittene Szenarien stehen zusätzliche interne Plattformoptionen zur Verfügung (z. B. Named-Pipe-Timeouts für Test-Host-Controller). Diese Optionen sind für die Infrastrukturnutzung vorgesehen und werden hier nicht behandelt.

Beispiel:

{
  "platformOptions": {
    "resultDirectory": "../../TestResults",
    "exitProcessOnUnhandledException": false
  }
}

Umgebungsvariablen in testconfig.json

Hinweis

Verfügbar in MTP ab Version 2.3.0.

Der environmentVariables Abschnitt legt Umgebungsvariablen für den Testprozess fest, bevor er gestartet wird. Verwenden Sie Zeichenfolgenwerte für jede Variable.

{
  "environmentVariables": {
    "DOTNET_ENVIRONMENT": "Development",
    "FEATURE_FLAG": "true"
  }
}

CLI-Optionen in testconfig.json

Vor MTP 2.3.0 sind Erweiterungsfunktionen wie Crash-Dump, Hang-Dump, Wiederholung, TRX-Berichte und Codeabdeckung nicht über testconfig.json konfigurierbar. Diese Features werden ausschließlich über Befehlszeilenargumente konfiguriert.

Ab MTP 2.3.0 kann MTP CLI-Optionen von testconfig.json bis zu IConfigurationlesen. Diese Unterstützung umfasst Erweiterungsoptionen, sodass Sie JSON-Einträge für Optionen verwenden können, die Sie nicht für jede Ausführung an die Befehlszeile übergeben möchten. Befehlszeilenargumente haben weiterhin Vorrang.

Die Konfiguration installiert oder registriert keine Erweiterung. Jede Testanwendung muss auf das Paket verweisen, das eine Erweiterungsoption bereitstellt, entweder direkt oder über eine Test-SDK-Konfiguration oder ein Profil. Andernfalls bleibt die Option nicht erkannt, ob Sie sie in testconfig.json oder in der Befehlszeile platzieren.

Verwenden Sie das commandLineOptions Objekt für aktive Optionen. Lassen Sie das vorangestellte -- bei jedem Schlüssel weg. Verwenden Sie true für eine Option ohne Argument, und verwenden Sie false, um eine Option zu deaktivieren. Verwenden Sie für ein Argument eine Zeichenfolge oder Eine Zahl. Verwenden Sie für wiederholte oder mehrere Argumente ein Array:

{ "commandLineOptions": {
  "report-trx": true,
  "report-trx-filename": "results.trx",
  "filter-uid": ["test-1", "test-2"]
} }

MTP behandelt eine Zeichenfolge oder einen numerischen Skalar als das erste Argument einer Option mit Argument. Um ein boolesches Argument zu übergeben, verwenden Sie ein Array wie [true] oder [false]. Das Array unterscheidet das Argument von einem booleschen Anwesenheitswert.

MTP überprüft konfigurierte Einträge wie Befehlszeileneinträge. Unbekannte Optionen, ungültige Werte und Werte mit der falschen Arität schlagen bei der Überprüfung fehl. Eine explizite Befehlszeilenoption setzt den entsprechenden commandLineOptions Eintrag außer Kraft.

Bootstrap-only-Optionen werden ausgeführt, bevor die Konfiguration von MTP geladen wird. Setzen Sie nicht config-file, , diagnostic, diagnostic-output-directorydiagnostic-file-prefix, diagnostic-verbosity, , oder diagnostic-synchronous-writeenable-dynamic-extensions in commandLineOptions.

Standardeinstellungen für passive Befehlszeilenoptionen

Important

commandLineOptionDefaults ist in der MTP 2.4-Vorschau verfügbar.

Wird commandLineOptionDefaults verwendet, um ein Argument nur dann zur Verfügung zu stellen, wenn ein aktiviertes Feature diese Option anfordert und kein Wert mit höherer Priorität vorhanden ist. Ein passiver Standardwert aktiviert keine Option, registriert eine Erweiterung oder aktiviert ein Feature. Lassen Sie den vorangestellten -- bei jedem Schlüssel weg.

{ "commandLineOptionDefaults": {
  "report-trx-filename": "{asm}.trx",
  "show-test-results": ["failed", "skipped"]
} }

MTP löst einen Optionswert mithilfe der ersten Übereinstimmung in dieser Prioritätsreihenfolge auf:

  • Ein expliziter Befehlszeilenwert.
  • Ein aktiver commandLineOptions Eintrag.
  • Ein commandLineOptionDefaults Eintrag in testconfig.json.
  • Ein MSBuild-bereitgestellter Standardwert.

Fügen Sie für einen von MSBuild bereitgestellten Standard ein TestingPlatformCommandLineOptionDefault Element hinzu. Der Include Wert muss führende Bindestriche weglassen:

<TestingPlatformCommandLineOptionDefault Include="report-trx-filename"
                                         Value="{asm}.trx" />

Eine vollständige Referenz zu Befehlszeilenoptionen finden Sie in der MTP CLI-Optionsreferenz.

Testframework-spezifische Einstellungen

Testframeworks können ihre eigenen Konfigurationsabschnitte in der dateitestconfig.json definieren. Weitere Informationen finden Sie in der Dokumentation für Ihr Testframework:

Beispiel-testconfig.json

Das folgende Beispiel zeigt eine testconfig.json Datei, die Plattformoptionen und MSTest-Einstellungen konfiguriert:

{
  "platformOptions": {
    "resultDirectory": "./TestResults"
  },
  "mstest": {
    "parallelism": {
      "enabled": true,
      "workers": 4,
      "scope": "method"
    },
    "timeout": {
      "test": 30000
    },
    "execution": {
      "considerFixturesAsSpecialTests": true
    }
  }
}

Migrieren von .runsettings zu testconfig.json

Wenn Sie aus einer Runsettings-Datei migrieren, werden in der folgenden Tabelle allgemeine Einstellungen ihren testconfig.json Entsprechungen oder Alternativen zugeordnet:

.runsettings-Einstellung Äquivalent zu testconfig.json Hinweise
RunConfiguration/ResultsDirectory platformOptions.resultDirectory
RunConfiguration/MaxCpuCount Keine Entsprechung Die Parallelität auf Prozessebene wird durch dotnet test --max-parallel-test-modules oder die MSBuild-Option /m gesteuert.
MSTest/* mstest.* Siehe Konfigurieren von MSTest – testconfig.json.
xUnit/* xUnit.* Siehe xUnit.net testconfig.json.
LoggerRunSettings/Loggers CLI-Optionen Verwenden Sie die Option aus der installierten Berichtserweiterung. --report-trx erfordert beispielsweise Microsoft.Testing.Extensions.TrxReport. Ab MTP 2.3.0 kann MTP CLI-Optionen aus testconfig.jsonlesen. Siehe Testberichte.
DataCollectionRunSettings (Schuldzuweisung) CLI-Optionen Verwenden Sie --crashdump von Microsoft.Testing.Extensions.CrashDump oder --hangdump von Microsoft.Testing.Extensions.HangDump. Ab MTP 2.3.0 kann MTP CLI-Optionen aus testconfig.jsonlesen. Siehe Absturz- und Blockabbilder.
DataCollectionRunSettings (Abdeckung) CLI-Optionen Verwende --coverage von Microsoft.Testing.Extensions.CodeCoverage. Ab MTP 2.3.0 kann MTP CLI-Optionen aus testconfig.jsonlesen. Siehe Codeabdeckung.
TestRunParameters --test-parameter CLI Verwenden Sie --test-parameter key=value in der Befehlszeile.

MSBuild-Konfiguration

Important

TestingPlatformEnvironmentVariable ist in der MTP 2.4-Vorschau verfügbar.

Um eine Umgebungsvariable für den Testprozess InvokeTestingPlatform festzulegen, der gestartet wird, fügen Sie ein TestingPlatformEnvironmentVariable Element hinzu:

<TestingPlatformEnvironmentVariable Include="MY_OPTIONS"
                                    Value="first;second" />

Die Value Metadaten behalten Semikolons bei, anstatt sie in MSBuild-Elemente aufzuteilen. Deklarierte Werte überlagern die Umgebung, die der MSBuild-Prozess erbt. Ohne diese Elemente erbt der gestartete Prozess die Umgebung unverändert.

Umgebungsvariablen

Umgebungsvariablen können verwendet werden, um einige Laufzeitkonfigurationsinformationen bereitzustellen.

Hinweis

Umgebungsvariablen haben Vorrang vor Konfigurationseinstellungen in der dateitestconfig.json .

Umgebungsvariable TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION

Bei Festlegung auf 1, wird der Testhostprozess sofort bei unbehandelten Ausnahmen beendet. Wenn auf 0 festgelegt ermöglicht die Plattform das ordnungsgemäße Herunterfahren. Diese Einstellung hat Vorrang vor der platformOptions:exitProcessOnUnhandledException Konfiguration.

Umgebungsvariable TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT

Überschreibt das Standardtimeout (300 Sekunden), das für benannte Pipeverbindungen zwischen dem Testhostcontroller und dem Testhost verwendet wird. Der Wert muss eine TimeSpan-kompatible Zeichenfolge sein.

Umgebungsvariable TESTINGPLATFORM_UI_LANGUAGE

Ab MTP 1.5 legt diese Umgebungsvariable die Sprache der Plattform fest, um Nachrichten und Protokolle mithilfe eines Gebietsschemawerts wie en-us anzuzeigen. Diese Sprache hat Vorrang vor den Sprachen Visual Studio und .NET SDK. Die unterstützten Werte sind identisch mit denen für Visual Studio. Weitere Informationen finden Sie im Abschnitt zum Ändern der Sprache des Installationsprogramms in der Visual Studio-Installationsdokumentation.

Umgebungsvariable TESTINGPLATFORM_DIAGNOSTIC

Wenn auf 1 eingestellt, wird die Diagnoseprotokollierung aktiviert.

Umgebungsvariable TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY

Definiert die Ausführlichkeitsstufe, wenn die Diagnose aktiviert ist. Verfügbare Werte sind Trace, Debug, Information, Warning, Error oder Critical.

Umgebungsvariable TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY

Das Ausgabeverzeichnis der diagnostischen Protokollierung. Wenn nicht angegeben, wird die Datei im Standardverzeichnis TestResults generiert.

Umgebungsvariable TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX

Das Präfix für den Namen der Protokolldatei. Standardmäßig verwendet MTP <asm>_<tfm>_<arch> und hängt einen Zeitstempel an. Der resultierende Dateiname lautet <asm>_<tfm>_<arch>_<timestamp>.diag. Die Variable entspricht der --diagnostic-file-prefix Befehlszeilenoption.

Hinweis

Dieser Umgebungsvariablenname ist ab Version 2.3.0 in MTP verfügbar. Die Legacy-Umgebungsvariable TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, ist jedoch veraltet und kann in einer zukünftigen Hauptversion entfernt werden. Wenn beide Variablen festgelegt sind, hat TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX Vorrang.

Umgebungsvariable TESTINGPLATFORM_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. Entspricht der --diagnostic-synchronous-write Befehlszeilenoption.

Hinweis

Dieser Umgebungsvariablenname ist ab Version 2.3.0 in MTP verfügbar. Die Legacy-Umgebungsvariable TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, ist jedoch veraltet und kann in einer zukünftigen Hauptversion entfernt werden. Wenn beide Variablen festgelegt sind, hat TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE Vorrang.

Umgebungsvariable TESTINGPLATFORM_EXITCODE_IGNORE

Eine durch Semikolons getrennte Liste der zu ignorierenden Ausgangscodes. Wenn ein Exitcode ignoriert wird, gibt der Prozess stattdessen 0 zurück. Beispielsweise ignoriert TESTINGPLATFORM_EXITCODE_IGNORE=2;8 Testfehler und Szenarien, in denen keine Tests ausgeführt wurden.

Umgebungsvariable TESTINGPLATFORM_NOBANNER

Bei Festlegung auf 1 oder true, unterdrückt das Startbanner, die Copyright-Nachricht und das Telemetriebanner. Entspricht der --no-banner Befehlszeilenoption. Die Umgebungsvariable DOTNET_NOLOGO hat die gleiche Wirkung.

Umgebungsvariable NO_COLOR

Wenn ein beliebiger nicht leerer Wert gesetzt ist, wird jegliche ANSI-Farbausgabe unterdrückt. MTP hält sich an die NO_COLOR-Konvention.

Hinweis

Verfügbar in MTP ab Version 2.3.0.

Umgebungsvariable DOTNET_NOLOGO

Bei Festlegung auf 1 oder true, unterdrückt das Startbanner, die Copyright-Nachricht und das Telemetriebanner. Dies ist die Standard-.NET CLI-Umgebungsvariable und wird von MTP berücksichtigt. Siehe auch TESTINGPLATFORM_NOBANNER.

Umgebungsvariable TESTINGPLATFORM_PIPE_DIRECTORY

Ab MTP 2.4.0 überschreibt diese Variable das Verzeichnis, in dem MTP Unix-Domain-Socketdateien für die Named-Pipe-Kommunikation erstellt. Verwenden Sie sie, wenn ein Sandkasten oder Container die Socketerstellung im temporären Standardverzeichnis nicht zulässt. MTP erstellt und überprüft das Verzeichnis und schlägt mit einem Fehler fehl, wenn das Verzeichnis nicht beschreibbar ist oder der resultierende Socketpfad zu lang ist.

Die Variable hat keine Auswirkungen auf Windows, wobei benannte Pipes keine Dateisystempfade verwenden. Außerdem wird keine Pipe verschoben, die von einem anderen Prozess wie dem .NET SDK erstellt wird.

Prototyp für die Fristaufhebung

Warnung

EXPERIMENTAL/PROTOTYP: Die Aufhebung von Fristen ist ein Prototyp in der Vorschau von MTP 2.4. Seine Variablen und sein Verhalten können geändert oder entfernt werden.

Legen Sie TESTINGPLATFORM_DEADLINE auf den vom Deadline-Erzeuger gelieferten Zeitpunkt der vollständigen harten Stornierung fest. Verwenden Sie einen ISO 8601 UTC-Wert. Ziehen Sie MTPs Ränder nicht vom Wert ab.

MTP fordert einen ordnungsgemäßen Stopp vor dem Stichtag an. TESTINGPLATFORM_DEADLINE_STOP_MARGIN legt fest, wie früh, und ist standardmäßig auf 60 Sekunden eingestellt. Ein Test-Framework, das kein ordnungsgemäßes Beenden unterstützt, ignoriert diese Anfrage.

Als Fallback startet TESTINGPLATFORM_DEADLINE_DUMP_MARGIN vor Ablauf der Frist eine aktive HangDump-Erweiterung. Der Spielraum ist standardmäßig auf 30 Sekunden eingestellt. HangDump erfasst die Prozessstruktur und beendet dann den Testhost. Ohne Stichtag startet MTP keinen Stichtags-Timer.

Der Fristfestlegende bleibt für die harte Stornierung zum angegebenen Zeitpunkt verantwortlich.

Umgebungsvariable TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER

Wenn 1 gesetzt ist, wird der Testprozess beim Start angehalten und wartet, bis ein Debugger verbunden ist, bevor er fortfährt. Entspricht der --debug Befehlszeilenoption. Wird auf Browserplattformen nicht unterstützt.

Hinweis

Diese Umgebungsvariable ist ab Version 1.6.0 in MTP verfügbar.

Umgebungsvariable TESTINGPLATFORM_LAUNCH_ATTACH_DEBUGGER

Wenn die Einstellung auf 1 festgelegt ist, ruft der Testprozess beim Start Debugger.Launch() auf, wodurch das System aufgefordert wird, einen Just-in-Time-Debugger zu starten und ihn an den Prozess anzuhängen. Verwenden Sie diese Variable, um Startzeitprobleme (z. B. Servermodus-Handshake) zu debuggen, die auftreten, bevor Sie manuell anfügen können. Auf Nicht-Windows-Plattformen hängt das Verhalten vom konfigurierten JIT-Debugger ab.

Hinweis

Diese Umgebungsvariable ist ab Version 1.6.0 in MTP verfügbar.

Hinweis

Diagnosebezogene Umgebungsvariablen haben Vorrang vor den entsprechenden --diagnostic-* Befehlszeilenargumenten.

Siehe auch

  • Last updated on