dotnet test

Artículo
03/27/2024

Este artículo se aplica a: ✔️ SDK de .NET Core 3.1 y versiones posteriores

NOMBRE

dotnet test: controlador de prueba de .NET usado para ejecutar pruebas unitarias.

Sinopsis

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [--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

Descripción

El comando dotnet test se usa para ejecutar pruebas unitarias en una solución determinada. El dotnet test comando compila la solución y ejecuta una aplicación host de prueba para cada proyecto de prueba de la solución mediante VSTest. El host de prueba ejecuta las pruebas en el proyecto especificado mediante un marco de pruebas (por ejemplo, MSTest, NUnit o xUnit) e informa del éxito o el error de cada prueba. Si todas las pruebas son correctas, el ejecutor de pruebas devuelve 0 como un código de salida; en caso contrario, si se produce algún error en una prueba, devuelve 1.

Nota:

dotnet test originalmente se diseñó para admitir solo VSTestproyectos de prueba basados en . Las versiones recientes de los marcos de pruebas agregan compatibilidad con Microsoft.Testing.Platform. Esta plataforma de prueba alternativa es más ligera y rápida que VSTest y admite dotnet test con diferentes opciones de línea de comandos. Para obtener más información, consulte Microsoft.Testing.Platform.

En el caso de los proyectos con varios destinos, las pruebas se ejecutan para cada plataforma de destino. El host de pruebas y el marco de pruebas unitarias se empaquetan como paquetes NuGet y se restauran como dependencias ordinarias para el proyecto. A partir del SDK de .NET 9, estas pruebas se ejecutan en paralelo de forma predeterminada. Para deshabilitar la ejecución en paralelo, establezca la TestTfmsInParallel propiedad MSBuild en false. Para obtener más información, vea Ejecutar pruebas en paralelo y la línea de comandos de ejemplo más adelante en este artículo.

Los proyectos de prueba especifican el ejecutor de pruebas usando un elemento <PackageReference> ordinario, como se puede ver en este archivo de proyecto de ejemplo:

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
    <PackageReference Include="xunit" Version="2.8.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" />
  </ItemGroup>

</Project>

Donde Microsoft.NET.Test.Sdk es el host de prueba y xunit es el marco de pruebas. Y xunit.runner.visualstudio es un adaptador de prueba, que permite que el marco xUnit funcione con el host de prueba.

Restauración implícita

No es necesario ejecutar dotnet restore porque lo ejecutan implícitamente todos los comandos que necesitan que se produzca una restauración, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish y dotnet pack. Para deshabilitar la restauración implícita, use la opción --no-restore.

El comando dotnet restore sigue siendo válido en algunos escenarios donde tiene sentido realizar una restauración explícita, como las compilaciones de integración continua en Azure DevOps Services o en los sistemas de compilación que necesitan controlar explícitamente cuándo se produce la restauración.

Para obtener información sobre cómo administrar fuentes de NuGet, vea la documentación de dotnet restore.

Descargas de manifiestos de cargas de trabajo

Cuando se ejecuta, este comando inicia una descarga asincrónica en segundo plano de manifiestos de publicidad de cargas de trabajo. Si la descarga no ha terminado cuando finaliza el comando, se detiene. Para obtener más información, vea Manifiestos de publicidad.

Argumentos

PROJECT | SOLUTION | DIRECTORY | DLL | EXE
- Ruta de acceso al proyecto de prueba.
- Ruta de acceso a la solución.
- Ruta de acceso a un directorio que contiene un proyecto o una solución.
- Ruta de acceso a un archivo .dll del proyecto de prueba.
- Ruta de acceso al archivo .exe de un proyecto de prueba
Si no se especifica, el efecto es el mismo que si se usa el argumento DIRECTORY para especificar el directorio actual.

Opciones

Advertencia

Cambios importantes en las opciones:

A partir de .NET 7: cambie -a al alias --arch en lugar de --test-adapter-path.
A partir de .NET 7: cambie -r al alias --runtime en lugar de --results-directory.

Advertencia

Al usar Microsoft.Testing.Platform, consulte la integración de pruebas de dotnet para conocer las opciones admitidas. Como regla general, se admiten todas las opciones no relacionadas con las pruebas, mientras que cada opción relacionada con pruebas no se admite tal como está.

--test-adapter-path <ADAPTER_PATH>

Ruta de acceso a un directorio en el que se van hacer búsquedas de adaptadores de prueba adicionales. Solo se inspeccionan los archivos .dll con el sufijo .TestAdapter.dll. Si no se especifica, la búsqueda se realiza en el directorio del archivo .dll de la prueba.

Forma abreviada -a disponible en versiones del SDK de .NET anteriores a la 7.

--arch <ARCHITECTURE>

Especifica la arquitectura de destino. Se trata de una sintaxis abreviada para establecer el identificador del entorno de ejecución (RID), donde el valor proporcionado se combina con el RID predeterminado. Por ejemplo, en un equipo win-x64, al especificar --arch x86 se establece el RID en win-x86. Si usa esta opción, no use la opción -r|--runtime. Disponible a partir de .NET 6 (versión preliminar 7).

--artifacts-path <ARTIFACTS_DIR>

Todos los archivos de salida de compilación del comando ejecutado se incluirán en subcarpetas en la ruta de acceso especificada, separadas por el proyecto. Para obtener más información, consulte Diseño de salida de artefactos. Disponible a partir del SDK de .NET 8.

--blame

Ejecuta las pruebas en el modo de culpabilidad. Esta opción es útil para aislar las pruebas problemáticas que hacen que el host de prueba se bloquee. Cuando se detecta un bloqueo, crea un archivo de secuencia en TestResults/<Guid>/<Guid>_Sequence.xml que captura el orden de las pruebas ejecutadas antes del bloqueo.

Esta opción no crea un volcado de memoria y no es útil cuando la prueba está bloqueada.
--blame-crash (Disponible a partir del SDK de .NET 5.0)

Ejecuta las pruebas en modo de culpa y recopila un volcado de memoria cuando el host de prueba se cierra de forma inesperada. Esta opción depende de la versión de .NET que se use, del tipo de error y del sistema operativo.

En el caso de las excepciones en el código administrado, se recopilará automáticamente un volcado de memoria en .NET 5.0 y versiones posteriores. Generará un volcado de memoria para el host de prueba o cualquier proceso secundario que también se haya ejecutado en .NET 5.0 y se haya bloqueado. Los bloqueos en código nativo no generarán volcado de memoria. Esta opción funciona en Windows, macOS y Linux.

Los volcados de memoria en código nativo o cuando se usa .NET Core 3.1 o versiones anteriores solo se pueden recopilar en Windows, mediante Procdump. Un directorio que contenga procdump.exe y procdump64.exe debe estar en la variable de entorno PATH o PROCDUMP_PATH. Descargue las herramientas. Implica --blame.

Para recopilar un volcado de memoria de una aplicación nativa que se ejecuta en .NET 5.0 o una versión posterior, se puede establecer la variable de entorno VSTEST_DUMP_FORCEPROCDUMP en 1 para forzar el uso de Procdump.
--blame-crash-dump-type <DUMP_TYPE> (Disponible a partir del SDK de .NET 5.0)

El tipo de volcado de memoria que se va a recopilar. Los tipos de volcado admitidos son full (valor predeterminado) y mini. Implica --blame-crash.
--blame-crash-collect-always (Disponible a partir del SDK de .NET 5.0)

Recopila un volcado de memoria en la salida de host de prueba esperada e inesperada.
--blame-hang (Disponible a partir del SDK de .NET 5.0)

Ejecute las pruebas en modo de culpa y recopile un volcado de bloqueo cuando una prueba supere el tiempo de espera especificado.
--blame-hang-dump-type <DUMP_TYPE> (Disponible a partir del SDK de .NET 5.0)

El tipo de volcado de memoria que se va a recopilar. Debe ser full, mini o none. Cuando se especifica none, el host de prueba finaliza en el tiempo de espera, pero no se recopila ningún volcado. Implica --blame-hang.
--blame-hang-timeout <TIMESPAN> (Disponible a partir del SDK de .NET 5.0)

Tiempo de espera por prueba, después del cual se desencadena un volcado de bloqueo y se genera un volcado de memoria del proceso de host de prueba y todos sus procesos secundarios y se finalizan. El valor de tiempo de espera se especifica en uno de los siguientes formatos:
- 1.5h, 1.5hour, 1.5hours
- 90m, 90min, 90minute, 90minutes
- 5400s, 5400sec, 5400second, 5400seconds
- 5400000ms, 5400000mil, 5400000millisecond, 5400000milliseconds
Cuando no se usa ninguna unidad (por ejemplo, 5 400 000), se supone que el valor está en milisegundos. Cuando se usa junto con las pruebas basadas en datos, el comportamiento de tiempo de espera depende del adaptador de prueba usado. Para xUnit, NUnit. y MSTest 2.2.4+, el tiempo de espera se renueva después de cada caso de prueba. En MSTest, antes de la versión 2.2.4, el tiempo de espera se usa en todos los casos de prueba. Esta opción se admite en Windows con netcoreapp2.1 y versiones posteriores, en Linux con netcoreapp3.1 y versiones posteriores y en macOS con net5.0 o versiones posteriores. Implica --blame y --blame-hang.

-c|--configuration <CONFIGURATION>

Define la configuración de compilación. El valor predeterminado para la mayoría de los proyectos es Debug, pero puede invalidar los valores de configuración de compilación en el proyecto.

--collect <DATA_COLLECTOR_NAME>

Habilita el recopilador de datos para la ejecución de pruebas. Para obtener más información, consulte Monitor and analyze test run (Supervisar y analizar ejecuciones de pruebas).

Por ejemplo, puede recopilar la cobertura de código mediante la opción --collect "Code Coverage". Para más información, consulte Uso de la cobertura de código, Personalización del análisis de cobertura de código y el problema de GitHub dotnet/docs#34479.

Para recopilar la cobertura de código, también puede usar Coverlet mediante la opción --collect "XPlat Code Coverage".
-d|--diag <LOG_FILE>

Habilita el modo de diagnóstico de la plataforma de prueba y escribe mensajes de diagnóstico en el archivo especificado y en los archivos que hay junto a él. El proceso que registra los mensajes determina qué archivos se crean, como *.host_<date>.txt para el registro del host de prueba y *.datacollector_<date>.txt para el registro del recopilador de datos.
-e|--environment <NAME="VALUE">

Establece el valor de una variable de entorno. Crea la variable si no existe, la invalida si existe. El uso de esta opción obligará a que las pruebas se ejecuten en un proceso aislado. La opción se puede especificar varias veces para proporcionar varias variables.
-f|--framework <FRAMEWORK>

Moniker de la plataforma de destino (TFM) del marco de destino para el que ejecutarán pruebas La plataforma de destino también debe especificarse en el archivo del proyecto.
--filter <EXPRESSION>

Filtra las pruebas del proyecto actual con la expresión dada. Solo se ejecutan las pruebas que coinciden con la expresión de filtro. Para más información, consulte la sección Detalles de la opción de filtro. Para obtener más información y ejemplos sobre cómo usar el filtrado de pruebas unitarias selectivas, vea Ejecución de pruebas unitarias selectivas.

-?|-h|--help

Imprime una descripción de cómo usar el comando.

--interactive

Permite que el comando se detenga y espere una entrada o una acción del usuario. Por ejemplo, para completar la autenticación. Disponible desde el SDK de .NET Core 3.0.

-l|--logger <LOGGER>

Especifica un registrador para los resultados de la prueba y, opcionalmente, cambia para el registrador. Especifique este parámetro varias veces para habilitar varios registradores. Para obtener más información, vea Informes de resultados de pruebas, Modificadores para registradores y los ejemplos que hay más adelante en este artículo.

Para pasar conmutadores de línea de comandos al registrador, haga lo siguiente:
- Use el nombre completo del modificador, no la forma abreviada (por ejemplo, verbosity en lugar de v).
- Omita los guiones iniciales.
- Reemplace el espacio que separa cada modificador por un punto y coma ;.
- Si el modificador tiene un valor, reemplace el separador de dos puntos entre ese modificador y su valor por el signo igual =.
Por ejemplo, -v:detailed --consoleLoggerParameters:ErrorsOnly se convertiría en verbosity=detailed;consoleLoggerParameters=ErrorsOnly.
--no-build

No compila el proyecto de prueba antes de ejecutarlo. También establece la marca --no-restore de forma implícita.
--nologo

Ejecuta pruebas sin mostrar la pancarta de Microsoft TestPlatform. Disponible desde el SDK de .NET Core 3.0.
--no-restore

No ejecuta una restauración implícita al ejecutar el comando.
-o|--output <OUTPUT_DIRECTORY>

Directorio donde se encuentran los archivos binarios que se ejecutarán. Si no se especifica la ruta de acceso predeterminada es ./bin/<configuration>/<framework>/. En el caso de los proyectos con varias plataformas de destino (a través de la propiedad TargetFrameworks), también debe definir --framework al especificar esta opción. dotnet test siempre ejecuta las pruebas desde el directorio de salida. Puede usar AppDomain.BaseDirectory para consumir recursos de prueba en el directorio de salida.
- SDK de .NET 7.0.200 y versiones posteriores
  
  Si especifica la opción --output al ejecutar este comando en una solución, la CLI emitirá una advertencia (un error en la versión 7.0.200) debido a la semántica poco clara de la ruta de acceso de salida. No se permite la opción --output porque todas las salidas de todos los proyectos compilados se copiarían en el directorio especificado, que no es compatible con proyectos de varios destinos, así como con proyectos que tienen diferentes versiones de dependencias directas y transitivas. Para más información, consulte la opción Nivel de solución: la opción --output ya no es válida para los comandos relacionados con la compilación.

--os <OS>

Especifica el sistema operativo (SO) de destino. Se trata de una sintaxis abreviada para establecer el identificador del entorno de ejecución (RID), donde el valor proporcionado se combina con el RID predeterminado. Por ejemplo, en un equipo win-x64, al especificar --os linux se establece el RID en linux-x64. Si usa esta opción, no use la opción -r|--runtime. Disponible a partir de .NET 6.

--results-directory <RESULTS_DIR>

El directorio donde se guardarán los resultados de pruebas. Si el directorio especificado no existe, se crea. El valor predeterminado es TestResults en el directorio que contiene el archivo del proyecto.

Forma abreviada -r disponible en versiones del SDK de .NET anteriores a la 7.
-r|--runtime <RUNTIME_IDENTIFIER>

Runtime de destino que probar.

Forma abreviada -r disponible a partir del SDK de NET 7.
-s|--settings <SETTINGS_FILE>

El archivo .runsettings que se usará para ejecutar las pruebas. El elemento TargetPlatform (x86|x64) no tiene ningún efecto en dotnet test. Para ejecutar pruebas destinadas a x86, instale la versión x86 de .NET Core. El valor de bits de dotnet.exe que se encuentra en la ruta de acceso es lo que se usará para ejecutar las pruebas. Para obtener más información, vea los siguientes recursos:
- Configuración de pruebas unitarias con un archivo .runsettings.
- Configuración de una serie de pruebas
-t|--list-tests

Enumera las pruebas detectadas en vez de ejecutar las pruebas.

-v|--verbosity <LEVEL>

Establece el nivel de detalle del comando. Los valores permitidos son q[uiet], m[inimal], n[ormal], d[etailed] y diag[nostic]. De manera predeterminada, es minimal. Para obtener más información, vea LoggerVerbosity.

args

Especifica argumentos adicionales para pasar al adaptador. Use un espacio para separar varios argumentos.

La lista de argumentos posibles depende del comportamiento especificado:
- Cuando se especifica un proyecto, una solución o un directorio, o si se omite este argumento, la llamada se reenvía a msbuild. En ese caso, los argumentos disponibles se pueden encontrar en la documentación de dotnet msbuild.
- Cuando se especifica un archivo .dll o .exe, la llamada se reenvía a vstest. En ese caso, los argumentos disponibles se pueden encontrar en la documentación de dotnet vstest.
Argumentos de RunSettings

Los argumentos RunSettings insertados se pasan como los últimos argumentos en la línea de comandos después de "-- " (fíjese en el espacio después de --). Los argumentos RunSettings insertados se especifican como pares de [name]=[value]. Se usa un espacio para separar varios pares de [name]=[value].

Ejemplo: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

Para obtener más información, vea Paso de argumentos de RunSettings a través de la línea de comandos.

Ejemplos

Ejecución de las pruebas en el proyecto en el directorio actual:
```
dotnet test
```

Ejecute las pruebas en el proyecto test1:

dotnet test ~/projects/test1/test1.csproj

Ejecute las pruebas mediante el ensamblado test1.dll:
```
dotnet test ~/projects/test1/bin/debug/test1.dll
```
Ejecute las pruebas del proyecto en el directorio actual y genere un archivo de resultados de prueba en formato trx:
```
dotnet test --logger trx
```
Ejecute las pruebas del proyecto en el directorio actual y genere un archivo de cobertura de código (después de instalar la integración de recopiladores de Coverlet):
```
dotnet test --collect:"XPlat Code Coverage"
```
Ejecute las pruebas en el proyecto en el directorio actual y genere un archivo de cobertura de código (solo en Windows):
```
dotnet test --collect "Code Coverage"
```
Ejecute las pruebas del proyecto en el directorio actual y regístrese con el nivel de detalle pormenorizado en la consola:
```
dotnet test --logger "console;verbosity=detailed"
```
Ejecute las pruebas del proyecto en el directorio actual y use el registrador trx para testResults.trx en la carpeta TestResults:
```
dotnet test --logger "trx;logfilename=testResults.trx"
```
Dado que se especifica el nombre del archivo de registro, se usa el mismo nombre para cada marco de destino si el proyecto tiene varios destinos. La salida de cada marco de destino sobrescribe la salida de las plataformas de destino anteriores. El archivo se crea en la carpeta TestResults de la carpeta del proyecto de prueba, ya que las rutas de acceso relativas lo son a esa carpeta. En el ejemplo siguiente se muestra cómo generar un archivo independiente para cada marco de destino.
Ejecute las pruebas del proyecto en el directorio actual y use el registrador trx en los archivos de la carpeta TestResults, con nombres de archivo únicos para cada marco de destino:
```
dotnet test --logger:"trx;LogFilePrefix=testResults"
```
Ejecute las pruebas del proyecto en el directorio actual y use el registrador html para testResults.html en la carpeta TestResults:
```
dotnet test --logger "html;logfilename=testResults.html"
```
Ejecute las pruebas del proyecto en el directorio actual e informe de las pruebas que estaban en curso cuando se bloqueó el host de prueba:
```
dotnet test --blame
```
Ejecute las pruebas del proyecto test1 proporcionando el argumento (registro binario) -bl a msbuild:
```
dotnet test ~/projects/test1/test1.csproj -bl
```
Ejecute las pruebas del proyecto test1 y establezca la propiedad DefineConstantsMSBuild en DEV:
```
dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
```
Ejecute las pruebas del proyecto test1 y establezca la propiedad TestTfmsInParallelMSBuild en false:
```
dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
```

--filter <EXPRESSION>

<Expression> tiene el formato <property><operator><value>[|&<Expression>].

<property> es un atributo del tipo Test Case. Las siguientes son las propiedades admitidas por los marcos de pruebas unitarias populares:

Marco de prueba	Propiedades admitidas
MSTest	FullyQualifiedName NOMBRE ClassName Prioridad TestCategory
xUnit	FullyQualifiedName DisplayName Category
NUnit	FullyQualifiedName Nombre Category Prioridad

<operator> describe la relación entre la propiedad y el valor:

Operador	Función
`=`	Coincidencia exacta
`!=`	Coincidencia no exacta
`~`	Contiene
`!~`	No contiene

<value> es una cadena. Todas las búsquedas distinguen mayúsculas de minúsculas.

Una expresión sin <operator> automáticamente se considera un contains en la propiedad FullyQualifiedName (por ejemplo, dotnet test --filter xyz es lo mismo que dotnet test --filter FullyQualifiedName~xyz).

Las expresiones se pueden combinar con operadores condicionales:

Operador	Función
`\|`	o
`&`	AND

Si usa operadores condicionales (por ejemplo, (Name~TestMethod1) | (Name~TestMethod2)), puede incluir las expresiones entre paréntesis.

Para obtener más información y ejemplos sobre cómo usar el filtrado de pruebas unitarias selectivas, vea Ejecución de pruebas unitarias selectivas.

Compartir a través de