dotnet test

  • Artikel

Dieser Artikel gilt für: ✔️ .NET Core 3.1 SDK und höher

Name

dotnet test: .NET-Testtreiber, der verwendet wird, um Komponententests auszuführen.

Übersicht

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--blame]
    [--blame-crash]
    [--blame-crash-dump-type <DUMP_TYPE>]
    [--blame-crash-collect-always]
    [--blame-hang]
    [--blame-hang-dump-type <DUMP_TYPE>]
    [--blame-hang-timeout <TIMESPAN>]
    [-c|--configuration <CONFIGURATION>]
    [--collect <DATA_COLLECTOR_NAME>]
    [-d|--diag <LOG_FILE>]
    [-f|--framework <FRAMEWORK>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>]
    [-t|--list-tests]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

Beschreibung

Der Befehl dotnet test wird zum Ausführen von Komponententests in einer bestimmten Projektmappe verwendet. Mit dem Befehl dotnet test wird die Projektmappe erstellt und für jedes Testprojekt in der Projektmappe eine Testhostanwendung ausgeführt. Der Testhost führt Tests im angegebenen Projekt mithilfe eines Testframeworks aus, z. B. MSTest, NUnit oder xUnit, und meldet den Erfolg oder Fehler jedes Tests. Wenn alle Tests erfolgreich sind, gibt der Test Runner 0 (null) als Exitcode zurück. Wenn jedoch ein Test fehlschlägt, wird 1 zurückgegeben.

Bei Projekten mit mehreren Zielen werden Tests für jedes Zielframework ausgeführt. Der Testhost und das Komponententest-Framework werden als NuGet-Pakete gepackt und als gewöhnliche Abhängigkeiten für das Projekt wiederhergestellt. Ab .NET 9 SDK werden diese Tests standardmäßig parallel ausgeführt. Um die parallele Ausführung zu deaktivieren, legen Sie die TestTfmsInParallel MSBuild-Eigenschaft auf false. Weitere Informationen finden Sie unter Ausführen von Tests parallel und der Beispielbefehlszeile weiter unten in diesem Artikel.

In Testprojekten wird der Testlauf mittels eines normalen <PackageReference>-Elements angegeben, wie in der folgenden Beispielprojektdatei gezeigt wird:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="xunit" Version="2.7.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.8" />
  </ItemGroup>

</Project>

Wobei Microsoft.NET.Test.Sdk der Testhost und xunit das Testframework ist. Und xunit.runner.visualstudio ist ein Testadapter, der es dem xUnit-Framework ermöglicht, mit dem Testhost zu arbeiten.

Implizite Wiederherstellung

Sie müssen dotnet restore nicht ausführen, da der Befehl implizit von allen Befehlen ausgeführt wird, die eine Wiederherstellung erfordern. Zu diesen zählen z. B. dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish und dotnet pack. Verwenden Sie die Option --no-restore, um die implizite Wiederherstellung zu deaktivieren.

In bestimmten Fällen eignet sich der dotnet restore-Befehl dennoch. Dies ist etwa bei Szenarios der Fall, in denen die explizite Wiederherstellung sinnvoll ist. Beispiele hierfür sind Continuous Integration-Builds in Azure DevOps Services oder Buildsysteme, die den Zeitpunkt für die Wiederherstellung explizit steuern müssen.

Informationen zum Verwalten von NuGet-Feeds finden Sie in der dotnet restoreDokumentation.

Workload manifest downloads

Wenn Sie diesen Befehl ausführen, wird im Hintergrund ein asynchroner Download initiiert, der Ankündigungsmanifeste für Workloads herunterlädt. Wenn der Download noch ausgeführt wird, wenn der Befehl abgeschlossen ist, wird der Download angehalten. Weitere Informationen finden Sie unter Ankündigungsmanifeste.

Argumente

  • PROJECT | SOLUTION | DIRECTORY | DLL | EXE

    • Der Pfad zum Testprojekt.
    • Der Pfad zur Projektmappe.
    • Der Pfad zu einem Verzeichnis, das ein Projekt oder eine Projektmappe enthält.
    • Der Pfad zur DLL-Datei eines Testprojekts.
    • Pfad zur .exe-Datei eines Testprojekts.

    Wenn hier nichts angegeben wird, ist der Effekt der gleiche wie bei der Verwendung des DIRECTORY-Arguments zum Angeben des aktuellen Verzeichnisses.

Tastatur

Warnung

Breaking Changes bei Optionen:

  • Ab .NET 7: Schalter -a für Alias --arch anstatt --test-adapter-path
  • Ab .NET 7: Schalter -r für Alias --runtime anstatt --results-directory

  • --test-adapter-path <ADAPTER_PATH>

    Der Pfad zu einem Verzeichnis, das nach zusätzlichen Testadaptern durchsucht werden soll. Nur DLL-Dateien mit dem Suffix .TestAdapter.dll werden untersucht. Wenn nichts angegeben ist, wird das Verzeichnis der Test-DLL durchsucht.

    Kurzform -a in .NET SDK-Versionen vor 7 verfügbar.

  • --arch <ARCHITECTURE>

    Legt die Zielarchitektur fest. Dies ist eine Kurzsyntax zum Setzen des Runtimebezeichners (RID), wobei der angegebene Wert mit dem Standard-RID kombiniert wird. Auf einem win-x64 Rechner wird beispielsweise durch die Angabe von --arch x86 der RID auf win-x86 gesetzt. Wenn Sie diese Option verwenden, dürfen Sie Option -r|--runtime nicht verwenden. Verfügbar seit .NET 6 Preview 7.

  • --blame

    Führt die Tests im blame-Modus aus. Diese Option hilft beim Isolieren von fehlerhaften Tests, die den Absturz des Testhosts verursachen. Wenn ein Absturz erkannt wird, wird in TestResults/<Guid>/<Guid>_Sequence.xml eine Sequenzdatei erstellt, die die Reihenfolge der Tests erfasst, die vor dem Absturz ausgeführt wurden.

    Diese Option erstellt kein Speicherabbild und ist nicht hilfreich, wenn der Test hängt.

  • --blame-crash (verfügbar ab .NET 5.0 SDK)

    Führt die Tests im Modus „Verantwortung zuweisen“ aus und erfasst ein Absturzabbild, wenn der Testhost unerwartet beendet wird. Diese Option hängt von der verwendeten Version von .NET, dem Fehlertyp und Betriebssystem ab.

    Für Ausnahmen in verwaltetem Code wird ab NET 5.0 automatisch ein Absturzabbild erfasst. Es wird ein Absturzabbild für den Testhost oder jegliche untergeordneten Prozesse generiert, die ebenfalls unter .NET 5.0 liefen und abgestürzt sind. Abstürze in nativem Code generieren keine Absturzabbild. Diese Option funktioniert unter Windows, macOS und Linux.

    Absturzabbilder in nativem Code oder bei Verwendung von .NET Core 3.1 oder früheren Versionen können unter Windows nur mithilfe von Procdump erfasst werden. Ein Verzeichnis, das procdump.exe und procdump64.exe enthält, muss in der PATH- oder PROCDUMP_PATH-Umgebungsvariablen enthalten sein. Tools herunterladen. Impliziert --blame.

    Um ein Absturzabbild aus einer nativen Anwendung zu erfassen, die unter .NET 5.0 oder höher läuft, kann die Verwendung von Procdump erzwungen werden, indem die Umgebungsvariable VSTEST_DUMP_FORCEPROCDUMP auf 1 festgelegt wird.

  • --blame-crash-dump-type <DUMP_TYPE> (verfügbar ab .NET 5.0 SDK)

    Der Typ des zu erfassenden Absturzspeicherabbilds. Unterstützte Speicherabbildtypen sind full (Standard) und mini. Impliziert --blame-crash.

  • --blame-crash-collect-always (verfügbar ab .NET 5.0 SDK)

    Erfasst ein Absturzabbild bei einer erwarteten und einer unerwarteten Beendigung des Testhosts.

  • --blame-hang (verfügbar ab .NET 5.0 SDK)

    Hiermit werden Tests im Modus „Verantwortung zuweisen“ ausgeführt, und ein Blockadeabbild wird erfasst, wenn der Test länger als angegeben dauert.

  • --blame-hang-dump-type <DUMP_TYPE> (verfügbar ab .NET 5.0 SDK)

    Der Typ des zu erfassenden Absturzspeicherabbilds. Möglich sind full, mini oder none. Wenn none angegeben wird, wird der Testhost bei einem Timeout beendet, es wird jedoch kein Abbild erfasst. Impliziert --blame-hang.

  • --blame-hang-timeout <TIMESPAN> (verfügbar ab .NET 5.0 SDK)

    Testspezifisches Timeout, nach dem ein Blockadeabbild ausgelöst und der Testhostprozess und alle dessen untergeordneten Prozesse gesichert und beendet werden. Der Timeoutwert wird in einem der folgenden Formate angegeben:

    • 1.5h, 1.5hour, 1.5hours
    • 90m, 90min, 90minute, 90minutes
    • 5400s, 5400sec, 5400second, 5400seconds
    • 5400000ms, 5400000mil, 5400000millisecond, 5400000milliseconds

    Wenn keine Einheit verwendet wird (z. B. 5.400.000), wird angenommen, dass der Wert in Millisekunden angegeben wird. Bei Verwendung in Verbindung mit datenorientierten Tests hängt das Timeoutverhalten vom verwendeten Testadapter ab. Für xUnit, NUnit und MSTest 2.2.4+ wird das Timeout nach jedem Testfall erneuert. Für MSTest vor Version 2.2.4 wird das Timeout für alle Testfälle verwendet. Diese Option wird unter Windows mit netcoreapp2.1 oder höher, unter Linux mit netcoreapp3.1 oder höher und unter macOS mit net5.0 oder höher unterstützt. Impliziert --blame und --blame-hang.

  • -c|--configuration <CONFIGURATION>

    Legt die Buildkonfiguration fest. Der Standardwert für die meisten Projekte ist Debug, aber Sie können die Buildkonfigurationseinstellungen in Ihrem Projekt überschreiben.

  • --collect <DATA_COLLECTOR_NAME>

    Aktiviert den Datensammler für den Testlauf. Weitere Informationen finden Sie unter Monitor and analyze test run (Überwachen und Analysieren eines Testlaufs).

    Sie können beispielsweise die Code Coverage mithilfe der Option --collect "Code Coverage" erfassen. Weitere Informationen finden Sie unter Verwenden von Code Coverage, Anpassen der Code Coverage-Analyse und GitHub-Issue dotnet/docs#34479.

    Zum Erfassen der Code Coverage können Sie mithilfe der Option --collect "XPlat Code Coverage" auch Coverlet verwenden.

  • -d|--diag <LOG_FILE>

    Aktiviert den Diagnosemodus für die Testplattform und schreibt Diagnosemeldungen in die angegebene Datei sowie in benachbarte Dateien. Der Prozess, der die Meldungen protokolliert, bestimmt, welche Dateien erstellt werden, z. B. *.host_<date>.txt für das Testhostprotokoll und *.datacollector_<date>.txt für das Datensammlerprotokoll.

  • -e|--environment <NAME="VALUE">

    Legt den Wert einer Umgebungsvariable fest. Erstellt die Variable, wenn sie nicht vorhanden ist, und überschreibt die Variable, wenn sie vorhanden ist. Die Verwendung dieser Option erzwingt die Ausführung der Tests in einem isolierten Prozess. Die Option kann mehrmals angegeben werden, um mehrere Variablen bereitzustellen.

  • -f|--framework <FRAMEWORK>

    Der Zielframeworkmoniker (Target Framework Moniker, TFM) des Zielframeworks, für das Tests ausgeführt werden sollen. Das Zielframework muss auch in der Projektdatei angegeben werden.

  • --filter <EXPRESSION>

    Filtert Tests im aktuellen Projekt mithilfe des angegebenen Ausdrucks. Es werden nur Tests ausgeführt, die mit dem Filterausdruck übereinstimmen. Weitere Informationen finden Sie im Abschnitt Details zu Filteroptionen. Weitere Informationen und Beispiele zur Verwendung von selektiven Komponententestfiltern finden Sie unter Ausführen von selektiven Komponententests.

  • -?|-h|--help

    Gibt eine Beschreibung zur Verwendung des Befehls aus.

  • --interactive

    Ermöglicht dem Befehl, anzuhalten und auf Benutzereingaben oder Aktionen zu warten. Beispielsweise, um die Authentifizierung abzuschließen. Verfügbar seit .NET Core 3.0 SDK.

  • -l|--logger <LOGGER>

    Gibt eine Protokollierung für Testergebnisse und optionale Schalter für die Protokollierung an. Geben Sie diesen Parameter mehrmals an, um mehrere Protokollierungen zu ermöglichen. Weitere Informationen finden Sie unter Berichten von Testergebnissen, Schalter für Protokollierungen sowie in den Beispielen weiter unten in diesem Artikel.

    So übergeben Sie Befehlszeilenschalter an die Protokollierung:

    • Verwenden Sie den vollständigen Namen des Schalters, nicht die Kurzform (z. B. verbosity anstatt v).
    • Lassen Sie führende Minuszeichen weg.
    • Ersetzen Sie den Leerraum zwischen den einzelnen Schaltern durch ein Semikolon: ;.
    • Wenn der Schalter einen Wert aufweist, ersetzen Sie den Doppelpunkt zwischen dem Schalter und seinem Wert durch ein Gleichheitszeichen: =.

    Beispielsweise wird -v:detailed --consoleLoggerParameters:ErrorsOnly zu verbosity=detailed;consoleLoggerParameters=ErrorsOnly.

  • --no-build

    Erstellt das Projekt nicht vor der Ausführung. Zudem wird das Flag --no-restore implizit festgelegt.

  • --nologo

    Führen Sie Tests aus, ohne das Microsoft TestPlatform-Banner anzuzeigen. Verfügbar seit .NET Core 3.0 SDK.

  • --no-restore

    Führt keine implizite Wiederherstellung aus, wenn der Befehl ausgeführt wird.

  • -o|--output <OUTPUT_DIRECTORY>

    Verzeichnis, in dem die auszuführenden Binärdateien zu finden sind. Wenn nicht angegeben, ist der Standardpfad ./bin/<configuration>/<framework>/. Bei Projekten mit mehreren Zielframeworks (über die TargetFrameworks-Eigenschaft) müssen Sie auch --framework definieren, wenn Sie diese Option angeben. dotnet test führt Tests immer über das Ausgabeverzeichnis aus. Sie können AppDomain.BaseDirectory verwenden, um die Testobjekte im Ausgabeverzeichnis zu verarbeiten.

    • .NET 7.0.200 SDK und höher

      Wenn Sie beim Ausführen dieses Befehls in einer Projektmappe die --output-Option angeben, gibt die CLI aufgrund der unklaren Semantik des Ausgabepfads eine Warnung (einen Fehler in 7.0.200) aus. Die --output-Option ist unzulässig, da alle Ausgaben aller erstellten Projekte in das angegebene Verzeichnis kopiert werden, das nicht mit Projekten mit mehreren Zielen kompatibel ist, sowie Projekten mit unterschiedlichen Versionen von direkten und transitiven Abhängigkeiten. Weitere Informationen finden Sie unter Option --output auf Projektmappenebene ist für buildbezogene Befehle nicht mehr gültig.

  • --os <OS>

    Gibt das Zielbetriebssystem an. Dies ist eine Kompaktsyntax zum Festlegen des Runtimebezeichners (RID), wobei der angegebene Wert mit der Standard-RID kombiniert wird. Auf einem win-x64 Rechner wird beispielsweise durch die Angabe von --os linux der RID auf linux-x64 gesetzt. Wenn Sie diese Option verwenden, dürfen Sie Option -r|--runtime nicht verwenden. Verfügbar seit .NET 6.

  • --results-directory <RESULTS_DIR>

    Das Verzeichnis, in dem die Testergebnisse gespeichert werden. Wenn das Verzeichnis noch nicht vorhanden ist, wird es erstellt. Der Standardwert ist TestResults in dem Verzeichnis, das die Projektdatei enthält.

    Kurzform -r in .NET SDK-Versionen vor 7 verfügbar.

  • -r|--runtime <RUNTIME_IDENTIFIER>

    Die Zielruntime, für die Tests ausgeführt werden sollen.

    Kurzform -r ab .NET SDK 7 verfügbar.

  • -s|--settings <SETTINGS_FILE>

    Die .runsettings-Datei, die zum Ausführen der Tests verwendet wird. Das TargetPlatform-Element (x86|x64) hat keine Auswirkung auf dotnet test. Installieren Sie die x86-Version von .NET Core, um x86-Tests auszuführen. Die Bitanzahl der Datei dotnet.exe, die sich in diesem Pfad befindet, wird zum Ausführen von Tests verwendet. Weitere Informationen finden Sie in den folgenden Ressourcen:

  • -t|--list-tests

    Hiermit werden die gefundenen Tests aufgelistet, anstatt sie auszuführen.

  • -v|--verbosity <LEVEL>

    Legt den Ausführlichkeitsgrad für den Befehl fest. Zulässige Werte sind q[uiet], m[inimal], n[ormal], d[etailed] und diag[nostic]. Der Standardwert ist minimal. Weitere Informationen finden Sie unter LoggerVerbosity.

  • args

    Gibt zusätzliche Argumente an, die an den Adapter übergeben werden sollen. Trennt mehrere Argumente durch Leerzeichen.

    Die Liste der möglichen Argumente hängt vom angegebenen Verhalten ab:

    • Wenn Sie ein Projekt, eine Projektmappe oder ein Verzeichnis angeben oder dieses Argument weglassen, wird der Aufruf an msbuild weitergeleitet. In diesem Fall finden Sie die verfügbaren Argumente in der dotnet msbuild-Dokumentation.
    • Wenn Sie eine .dll- oder eine .exe-Datei angeben, wird der Aufruf an vstest weitergeleitet. In diesem Fall finden Sie die verfügbaren Argumente in der dotnet vstest-Dokumentation.

  • RunSettings-Argumente

Inline-RunSettings werden als die letzten Argumente auf der Befehlszeile nach „-- “ (beachten Sie das Leerzeichen hinter „--“) übergeben. Inline-RunSettings werden als [name]=[value]-Paare angegeben. Ein Leerzeichen wird verwendet, um mehrere [name]=[value]-Paare voneinander zu trennen.

Ein Beispiel: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

Weitere Informationen finden Sie unter Übergeben von RunSettings-Argumenten über die Befehlszeile.

Beispiele

  • Führen Sie die Tests im Projekt im aktuellen Verzeichnis durch:

    dotnet test

  • Führen Sie die Tests im Projekt test1 durch:

    dotnet test ~/projects/test1/test1.csproj

  • Führen Sie die Tests mit der Assembly test1.dll aus:

    dotnet test ~/projects/test1/bin/debug/test1.dll

  • Mit dem folgenden Befehl führen Sie die Tests im aktuellen Verzeichnis aus und generieren eine Testergebnisdatei im TRX-Format:

    dotnet test --logger trx

  • Führen Sie die Tests im Projekt im aktuellen Verzeichnis aus, und generieren Sie eine Code-Coverage-Datei (nach der Installation der Integration von Coverlet-Collectors):

    dotnet test --collect:"XPlat Code Coverage"

  • Führen Sie die Tests im Projekt im aktuellen Verzeichnis aus, und generieren Sie eine Code Coverage-Datei (nur Windows):

    dotnet test --collect "Code Coverage"

  • Mit dem folgenden Befehl führen Sie die Tests im aktuellen Verzeichnis aus und erstellen ein ausführliches Protokoll in der Konsole:

    dotnet test --logger "console;verbosity=detailed"

  • Führen Sie die Tests im Projekt im aktuellen Verzeichnis aus, und protokollieren Sie die Ergebnisse mit der trx-Protokollierung in testResults.trx im Ordner TestResults:

    dotnet test --logger "trx;logfilename=testResults.trx"

    Da der Name der Protokolldatei angegeben ist, wird dieser Name bei Projekten mit mehreren Zielen für jedes Zielframework verwendet. Die Ausgabe für jedes Zielframework überschreibt die Ausgabe für vorherige Zielframeworks. Die Datei wird im Ordner TestResults im Testprojektordner erstellt, da relative Pfade sich auf diesen Ordner beziehen. Das folgende Beispiel zeigt, wie Sie eine separate Datei für jedes Zielframework erstellen.

  • Führen Sie die Tests im Projekt im aktuellen Verzeichnis aus, und protokollieren Sie die Ergebnisse mit der trx-Protokollierung im Ordner TestResults. Verwenden Sie dabei Dateinamen, die für jedes Zielframework eindeutig sind:

    dotnet test --logger:"trx;LogFilePrefix=testResults"

  • Führen Sie die Tests im Projekt im aktuellen Verzeichnis aus, und protokollieren Sie die Ergebnisse mit der html-Protokollierung in testResults.html im Ordner TestResults:

    dotnet test --logger "html;logfilename=testResults.html"

  • Mit dem folgenden Befehl führen Sie die Tests in dem Projekt im aktuellen Verzeichnis aus und melden Tests, die während des Absturzes des Testhosts in Arbeit waren:

    dotnet test --blame

  • Führen Sie die Tests im Projekt test1 aus, und stellen Sie das Argument -bl (Binärprotokoll) für msbuild bereit:

    dotnet test ~/projects/test1/test1.csproj -bl

  • Führen Sie die Tests im Projekt test1 aus, und legen Sie die MSBuild-Eigenschaft DefineConstants auf DEV fest:

    dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"

  • Führen Sie die Tests im Projekt test1 aus, und legen Sie die MSBuild-Eigenschaft TestTfmsInParallel auf false fest:

    dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false

Details zu Filteroptionen

--filter <EXPRESSION>

<Expression> weist das Format <property><operator><value>[|&<Expression>] auf.

<property> ist ein Attribut von Test Case. Im Folgenden werden die Eigenschaften aufgeführt, die von gängigen Frameworks für Komponententests unterstützt werden:

Testframework Unterstützte Eigenschaften
MSTest
  • FullyQualifiedName
  • name
  • ClassName
  • Priorität
  • TestCategory
xUnit
  • FullyQualifiedName
  • DisplayName
  • Kategorie
NUnit
  • FullyQualifiedName
  • Name
  • Kategorie
  • Priority

<operator> beschreibt die Beziehung zwischen der Eigenschaft und dem Wert:

Operator Funktion
= Genaue Übereinstimmung
!= Keine genaue Übereinstimmung
~ Enthält
!~ Enthält nicht

<value> ist eine Zeichenfolge. Bei allen Suchvorgängen ist die Groß-/Kleinschreibung nicht relevant.

Ein Ausdruck ohne <operator> gilt automatisch als contains für die FullyQualifiedName-Eigenschaft (dotnet test --filter xyz ist beispielsweise identisch mit dotnet test --filter FullyQualifiedName~xyz).

Ausdrücke können mit bedingten Operatoren verknüpft werden:

Operator Funktion
| ODER
& UND

Sie können Ausdrücke in Klammern einschließen, wenn Sie bedingte Operatoren verwenden (z.B. (Name~TestMethod1) | (Name~TestMethod2)).

Weitere Informationen und Beispiele zur Verwendung von selektiven Komponententestfiltern finden Sie unter Ausführen von selektiven Komponententests.

Siehe auch