Opciones de configuración de Microsoft.Testing.Platform (MTP)

MTP admite el uso de archivos de configuración y variables de entorno para configurar el comportamiento de la plataforma de prueba. En este artículo se describen las opciones de configuración que puede usar para configurar la plataforma de prueba.

testconfig.json

La plataforma de prueba usa un archivo de configuración denominado [appname].testconfig.json para configurar el comportamiento de la plataforma de prueba. El archivo testconfig.json es un archivo JSON que contiene opciones de configuración para la plataforma de prueba.

El archivo testconfig.json tiene la siguiente estructura:

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

La plataforma detectará y cargará automáticamente el archivo [appname].testconfig.json ubicado en el directorio de salida del proyecto de prueba (cerca del ejecutable).

Al usar Microsoft.Testing.Platform.MSBuild, simplemente puede crear un archivo testconfig.json cuyo nombre se cambiará automáticamente a [appname].testconfig.json y se moverá al directorio de salida del proyecto de prueba.

A partir de MTP 1.5, puede usar el argumento --config-file de la línea de comandos para especificar la ruta de acceso a la testconfig.json. Este archivo tiene prioridad sobre el archivo [appname].testconfig.json .

Nota:

El archivo [appname].testconfig.json se sobrescribirá en compilaciones posteriores.

Uso de una testconfig.json centralizada

Si desea un único testconfig.json compartido entre varios proyectos de prueba, puede colocarlo en una ubicación central y pasarlo a través de --config-file. Cuando MSBuild está disponible (por ejemplo, dotnet test o dotnet run), puede usar la TestingPlatformCommandLineArguments propiedad MSBuild para pasar automáticamente el argumento. Agregarlo a directory.Build.props en la raíz del repositorio garantiza que todos los proyectos de prueba usen la misma configuración:

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

Prioridad de configuración

Cuando se puede especificar la misma configuración de varias maneras, MTP la resuelve en el orden siguiente (la primera coincidencia gana):

  1. Argumentos de línea de comandos (por ejemplo, --results-directory)
  2. Variables de entorno
  3. configuración de testconfig.json
  4. Valores predeterminados integrados

Opciones de plataforma

La platformOptions sección del archivo testconfig.json configura el comportamiento principal de la plataforma de prueba. En la tabla siguiente se enumeran todas las opciones de plataforma admitidas:

Entrada Predeterminado Descripción
resultDirectory TestResults Directorio donde se colocan los resultados de la prueba. Puede ser una ruta de acceso relativa (resuelta desde el directorio de trabajo actual) o una ruta de acceso absoluta. La --results-directory opción de línea de comandos tiene prioridad.
exitProcessOnUnhandledException false Cuando se establece en true, el proceso host de prueba finaliza inmediatamente cuando se producen excepciones no controladas, en lugar de permitir un cierre ordenado. La TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION variable de entorno (valores 1 o 0) tiene prioridad.

Nota:

Existen opciones internas adicionales de la plataforma para escenarios avanzados (como tiempos de espera de canalizaciones con nombre para controladores de host de pruebas). Estas opciones están pensadas para el uso de la infraestructura y no se tratan aquí.

Ejemplo:

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

Variables de entorno en testconfig.json

Nota:

Disponible en MTP a partir de la versión 2.3.0.

La sección environmentVariables establece las variables de entorno del proceso de prueba antes de iniciarse. Use valores de cadena para cada variable.

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

Opciones de la CLI en testconfig.json

Antes de MTP 2.3.0, las funciones de extensión como volcado de memoria por error, volcado de memoria por bloqueo, reintento, informes TRX y cobertura de código no se pueden configurar a través de testconfig.json. Estas características se configuran exclusivamente a través de argumentos de línea de comandos.

A partir de MTP 2.3.0, MTP puede leer las opciones de la CLI desde testconfig.json mediante IConfiguration. Este soporte admite opciones de ampliación, por lo que puedes usar entradas JSON con opciones que no quieras pasar en la línea de comandos en cada ejecución. Los argumentos de la línea de comandos siguen teniendo prioridad.

La configuración no instala ni registra una extensión. Cada aplicación de prueba debe hacer referencia al paquete que proporciona una opción de extensión, ya sea directamente o a través de una configuración o perfil del SDK de prueba. De lo contrario, la opción no se reconoce si se coloca en testconfig.json o en la línea de comandos.

Use el commandLineOptions objeto para las opciones activas. Omita -- al principio de cada clave. Use true para una opción de argumento cero y use false para deshabilitar una opción. Para un argumento, use una cadena o un número. Para argumentos repetidos o múltiples, use una matriz:

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

MTP considera una cadena o un escalar numérico como el primer argumento de una opción que acepta argumentos. Para pasar un argumento booleano, use una matriz como [true] o [false]. La matriz distingue el argumento de un valor de presencia booleano.

MTP valida entradas configuradas como entradas de línea de comandos. Las opciones desconocidas, los valores no válidos y los valores con la aridad incorrecta no se validan. Una opción de línea de comandos explícita invalida la entrada correspondiente commandLineOptions .

Las opciones exclusivas de arranque se ejecutan antes de que MTP cargue la configuración. No coloque config-file, , , diagnostic-output-directorydiagnostic-file-prefix, diagnostic-verbosity, o diagnostic-synchronous-writeenable-dynamic-extensions en commandLineOptions. diagnostic

Valores predeterminados de la opción de línea de comandos pasiva

Importante

commandLineOptionDefaults está disponible en la versión preliminar de MTP 2.4.

Se usa commandLineOptionDefaults para proporcionar un argumento solo cuando una característica habilitada solicita esa opción y no existe ningún valor de prioridad superior. Un valor predeterminado pasivo no habilita una opción, registra una extensión ni activa una característica. Omita la etiqueta -- inicial de cada clave.

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

MTP resuelve un valor de opción mediante la primera coincidencia en este orden de prioridad:

  • Valor explícito de la línea de comandos.
  • Una entrada commandLineOptions activa.
  • Entrada commandLineOptionDefaults de testconfig.json.
  • Valor predeterminado proporcionado por MSBuild.

Para un valor predeterminado proporcionado por MSBuild, agregue un TestingPlatformCommandLineOptionDefault elemento. El Include valor debe omitir guiones iniciales:

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

Para obtener una referencia completa de las opciones de línea de comandos, consulte Referencia de opciones de la CLI de MTP.

Prueba de la configuración específica del marco de trabajo

Los marcos de pruebas pueden definir sus propias secciones de configuración en el archivo testconfig.json . Consulte la documentación del marco de pruebas:

  • MSTest: Configurar MSTest: testconfig.json
  • xUnit.net v3: xUnit.net testconfig.json
  • NUnit: Consulte la documentación de NUnit para obtener la información más reciente sobre la compatibilidad con Microsoft.Testing.Platform.
  • TUnit: consulte la documentación de TUnit para obtener la información más reciente sobre la compatibilidad con Microsoft.Testing.Platform.

Ejemplo de testconfig.json

En el ejemplo siguiente se muestra un archivo testconfig.json que configura las opciones de plataforma y la configuración de MSTest:

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

Migración de .runsettings a testconfig.json

Si va a migrar desde un archivo .runsettings , la tabla siguiente asigna la configuración común a sus testconfig.json equivalentes o alternativas:

Configuración de .runsettings equivalente a testconfig.json Notas
RunConfiguration/ResultsDirectory platformOptions.resultDirectory
RunConfiguration/MaxCpuCount Sin equivalente El paralelismo de nivel de proceso se controla mediante dotnet test --max-parallel-test-modules o la opción MSBuild /m .
MSTest/* mstest.* Consulte Configuración de MSTest: testconfig.json.
xUnit/* xUnit.* Consulte xUnit.net testconfig.json.
LoggerRunSettings/Loggers Opciones de la CLI Use la opción de la extensión de informe instalada. Por ejemplo, --report-trx requiere Microsoft.Testing.Extensions.TrxReport. A partir de MTP 2.3.0, MTP puede leer las opciones de la CLI de testconfig.json. Consulte Informes de prueba.
DataCollectionRunSettings (culpa) Opciones de la CLI Usa --crashdump desde Microsoft.Testing.Extensions.CrashDump o --hangdump desde Microsoft.Testing.Extensions.HangDump. A partir de MTP 2.3.0, MTP puede leer las opciones de la CLI de testconfig.json. Consulta Volcados de memoria por error y bloqueo.
DataCollectionRunSettings (cobertura) Opciones de la CLI Usa --coverage desde Microsoft.Testing.Extensions.CodeCoverage. A partir de MTP 2.3.0, MTP puede leer las opciones de la CLI de testconfig.json. Consulte Cobertura de código.
TestRunParameters CLI de --test-parameter Use --test-parameter key=value en la línea de comandos.

Configuración de MSBuild

Importante

TestingPlatformEnvironmentVariable está disponible en la versión preliminar de MTP 2.4.

Para establecer una variable de entorno en el proceso de prueba que inicia InvokeTestingPlatform, agregue un elemento TestingPlatformEnvironmentVariable:

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

Los Value metadatos conservan los puntos y coma en lugar de dividirlos en elementos de MSBuild. Los valores declarados se superponen al entorno heredado por el proceso de MSBuild. Sin estos elementos, el proceso iniciado hereda el entorno sin cambios.

Variables de entorno

Las variables de entorno se pueden usar para proporcionar información de configuración en tiempo de ejecución.

Nota:

Las variables de entorno tienen prioridad sobre las opciones de configuración del archivo testconfig.json .

La variable de entorno TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION

Cuando se establece en 1, el proceso host de pruebas finaliza inmediatamente cuando se producen excepciones no controladas. Cuando se establece en 0, la plataforma permite un apagado ordenado. Esta configuración tiene prioridad sobre la platformOptions:exitProcessOnUnhandledException configuración.

La variable de entorno TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT

Anula el tiempo de espera predeterminado (300 segundos) utilizado para las conexiones de canalización con nombre entre el controlador del host de prueba y el host de prueba. El valor debe ser una TimeSpancadena compatible.

La variable de entorno TESTINGPLATFORM_UI_LANGUAGE

A partir de MTP 1.5, esta variable de entorno establece el idioma de la plataforma para mostrar mensajes y registros mediante un valor de configuración regional como en-us. Este lenguaje tiene prioridad sobre los lenguajes del SDK de Visual Studio y .NET. Los valores admitidos son los mismos que en Visual Studio. Para obtener más información, vea la sección sobre cómo cambiar el idioma del instalador en la documentación de instalación de Visual Studio.

La variable de entorno TESTINGPLATFORM_DIAGNOSTIC

Si se establece en 1, habilita el registro de diagnóstico.

La variable de entorno TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY

Define el nivel de verbosidad cuando se habilitan los diagnósticos. Los valores disponibles son Trace, Debug, Information, Warning, Erroro Critical.

La variable de entorno TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY

Directorio de salida de los registros de diagnóstico. Si no se especifica, el archivo se genera en el directorio TestResults predeterminado.

La variable de entorno TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX

Prefijo del nombre del archivo de registro. De forma predeterminada, MTP usa <asm>_<tfm>_<arch> y anexa una marca de tiempo. El nombre de archivo resultante es <asm>_<tfm>_<arch>_<timestamp>.diag. La variable coincide con la opción de --diagnostic-file-prefix línea de comandos.

Nota:

Este nombre de variable de entorno está disponible en MTP a partir de la versión 2.3.0. La variable de entorno heredada TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX sigue siendo compatible con versiones anteriores, pero está en desuso y podría quitarse en una versión principal futura. Cuando se establecen ambas variables, TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX tiene prioridad.

La variable de entorno TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE

Obliga al registrador de archivos integrado a escribir registros de forma sincrónica. Resulta útil para escenarios en los que no desea perder ninguna entrada de registro (si el proceso se bloquea). Esto ralentiza la ejecución de la prueba. Corresponde a la opción --diagnostic-synchronous-write de línea de comandos.

Nota:

Este nombre de variable de entorno está disponible en MTP a partir de la versión 2.3.0. La variable de entorno heredada TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE sigue siendo compatible con versiones anteriores, pero está en desuso y podría quitarse en una versión principal futura. Cuando se establecen ambas variables, TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE tiene prioridad.

La variable de entorno TESTINGPLATFORM_EXITCODE_IGNORE

Lista separada por punto y coma de códigos de salida que se omitirán. Cuando se omite un código de salida, el proceso devuelve 0 en su lugar. Por ejemplo, TESTINGPLATFORM_EXITCODE_IGNORE=2;8 ignora los fallos de las pruebas y los escenarios en los que no se ejecutó ninguna prueba.

La variable de entorno TESTINGPLATFORM_NOBANNER

Cuando se establece en 1 o true, se suprimen la pantalla de inicio, el aviso de copyright y la pantalla de telemetría. Equivalente a la opción --no-banner de línea de comandos. La DOTNET_NOLOGO variable de entorno tiene el mismo efecto.

La variable de entorno NO_COLOR

Cuando se establece en cualquier valor no vacío, suprime toda la salida de color ANSI. MTP respeta la NO_COLORconvención.

Nota:

Disponible en MTP a partir de la versión 2.3.0.

La variable de entorno DOTNET_NOLOGO

Cuando se establece en 1 o true, se suprimen la pantalla de inicio, el aviso de copyright y la pantalla de telemetría. Esta es la variable de entorno estándar de la CLI de .NET y MTP la respeta. Consulte también TESTINGPLATFORM_NOBANNER.

La variable de entorno TESTINGPLATFORM_PIPE_DIRECTORY

A partir de la versión 2.4.0 de MTP, esta variable anula la ruta del directorio en el que MTP crea los archivos de socket de dominio Unix para la comunicación mediante canalizacións con nombre. Úselo cuando un espacio aislado o contenedor no permita la creación de sockets en el directorio temporal predeterminado. MTP crea y comprueba el directorio y produce un error cuando el directorio no se puede escribir o la ruta de acceso del socket resultante es demasiado larga.

La variable no tiene ningún efecto en Windows, donde las canalizaciones con nombre no usan rutas de acceso del sistema de archivos. Tampoco reubica una canalización que crea otro proceso, como el SDK de .NET.

Prototipo de cancelación de plazo

Warning

EXPERIMENTAL/PROTOTIPO: La cancelación de la fecha límite es un prototipo en la versión preliminar de MTP 2.4. Sus variables y comportamiento pueden cambiar o quitarse.

Establece TESTINGPLATFORM_DEADLINE en el instante de cancelación definitiva proporcionado por el generador de plazos. Utilice un valor UTC de ISO 8601. No restes los márgenes de MTP del valor.

MTP solicita una parada ordenada antes de la fecha límite. TESTINGPLATFORM_DEADLINE_STOP_MARGIN controla con cuánta antelación y el valor predeterminado es de 60 segundos. Un marco de pruebas que no admite una detención ordenada ignora esta solicitud.

Como alternativa, TESTINGPLATFORM_DEADLINE_DUMP_MARGIN inicia una extensión activa de HangDump antes del plazo límite. El margen tiene como valor predeterminado 30 segundos. HangDump captura el árbol de procesos y, a continuación, elimina el host de prueba. Sin una fecha límite, MTP no inicia un temporizador de fecha límite.

El generador de plazos sigue siendo responsable de la cancelación definitiva en el instante proporcionado.

La variable de entorno TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER

Cuando se establece en 1, el proceso de prueba se detiene al iniciarse y espera a que se conecte un depurador antes de continuar. Equivalente a la opción --debug de línea de comandos. No se admite en plataformas de explorador.

Nota:

Esta variable de entorno está disponible en MTP a partir de la versión 1.6.0.

La variable de entorno TESTINGPLATFORM_LAUNCH_ATTACH_DEBUGGER

Cuando se establece en 1, el proceso de prueba llama a Debugger.Launch() al iniciarse, lo que hace que el sistema inicie un depurador just-in-time y lo conecte al proceso. Utiliza esta variable para depurar problemas en el momento del inicio (por ejemplo, el protocolo de enlace en modo servidor) que se producen antes de que puedas conectarte manualmente. En las plataformas que no son de Windows, el comportamiento depende del depurador JIT configurado.

Nota:

Esta variable de entorno está disponible en MTP a partir de la versión 1.6.0.

Nota:

Las variables de entorno relacionadas con el diagnóstico tienen prioridad sobre sus argumentos de línea de comandos correspondientes --diagnostic-* .

Consulte también

  • Last updated on