WexLogger

WexLogger proporciona una API coherente para el registro que abarca código nativo, código administrado y script. También es capaz de escalar desde la ejecución de pruebas unitarias en la línea de comandos hasta pruebas de estrés intensivas y prolongadas.

Registro a través del marco de verificación

Most logging within a test case should be performed via the Verify framework. Esto garantizará que las pruebas se creen de manera más clara, legible y secuencial para los humanos. Sin embargo, en ciertos casos, los autores de pruebas descubren que necesitan un control más detallado sobre lo que se escribe en los registros; de ahí la necesidad de la API WexLogger.

Registro dentro de TAEF

En el caso de los casos de prueba que se ejecutan en TAEF, el autor de la prueba no necesita ninguna inicialización del registrador. Puede empezar inmediatamente a usar la API de logs que se expone al lenguaje en el que está escribiendo sus pruebas.

En el código nativo de C++, tendrá este aspecto:

using namespace WEX::Logging;
using namespace WEX::Common;
Log::Comment(L"Rendering to the BufferView");
Log::Comment(L"Render succeeded");

Log::Comment(String().Format(L"Look, a number! %d", aNumber));

#define LOG_OUTPUT(fmt, ...) Log::Comment(String().Format(fmt, __VA_ARGS__))
LOG_OUTPUT(L"Look, a number! %d", aNumber);

En el código administrado, tendrá este aspecto:

using WEX.Logging.Interop;
Log.Comment("Rendering to the BufferView");
Log.Comment("Render succeeded");

En JScript, tendrá este aspecto:

var log = new ActiveXObject("WEX.Logger.Log");
log.Comment("Rendering to the BufferView");
log.Comment("Render succeeded");

Registro fuera de TAEF

La mayor parte del tiempo, la inicialización del registro y la finalización serán realizadas por TAEF, por lo que WexLogger estará listo para usarse durante la duración del caso de prueba como se indicó anteriormente y finalizará correctamente. However, if a client would like to use the WexLogger outside TAEF, they will be responsible for manually calling LogController::InitializeLogging() and LogController::FinalizeLogging(). Este requisito solo existe para código nativo y administrado; Los scripts no tienen este requisito adicional. Consulte la tabla Métodos logController estáticos a continuación para obtener más información sobre la API de LogController.

Consulte la sección Generación de registros WTT para obtener información sobre cómo generar registros WTT fuera de TAEF.

WexLogger API

Esta es la lista de métodos nativos de registro de C++ disponibles.

Hay versiones equivalentes disponibles para el código administrado y el script.

Note: "Context" is an extra string that you can optionally provide with a WexLogger API call to provide more context or detail. For example, you may choose to always pass in "ImageComparator" as your context when making any WexLogger API calls from your ImageComparator class methods.

Here are the possible valid values for the native C++ TestResults::Result enumeration. Hay versiones equivalentes disponibles para el código administrado y el script.

Esta es la lista de métodos logController nativos de C++ disponibles:

Note: See the C++ Error Handling section below for more information on the WexLoggerErrorCallback mechanism and how to use it outside the TAEF framework.

Note: It is only necessary to call InitializeLogging/FinalizeLogging when using the WexLogger outside the TAEF framework, as TAEF already handles logging initialization/completion.

Note: It is not necessary to initialize/complete logging functionality when using the WexLogger from script.

Esta es la lista de métodos remoteLogContoller nativos de C++ disponibles:

Note: See the Remote Logging From Child Processes section below for more information on remote logging.

Esta es la lista de métodos de registro administrados disponibles.

Esta es la lista de métodos logContoller administrados disponibles:

Note: See the Managed Code Error and Exception section below for more information on how to handle errors and exceptions when using the managed layer of the WexLogger outside the TAEF framework.

Note: It is only necessary to call InitializeLogging/FinalizeLogging when using the WexLogger outside the TAEF framework, as TAEF already handles logging initialization/completion.

Note: It is not necessary to initialize/complete logging functionality when using the WexLogger from script.

Esta es la lista de métodos RemoteLogContoller administrados disponibles:

Note: See the Remote Logging From Child Processes section below for more information on remote logging.

Registro remoto desde procesos secundarios

WexLogger proporciona la capacidad de que uno o varios procesos secundarios vuelvan a iniciar sesión en un único proceso primario, lo que da lugar a la generación de resultados de pruebas consolidados dentro de un único archivo de registro.

Los procesos secundarios se pueden ejecutar en la misma máquina que el proceso primario o de forma remota en otra máquina. Para que el registro de máquinas remotas funcione, es responsabilidad del cliente WexLogger agregar exclusiones de firewall TCP para todos los procesos secundarios de la máquina remota. Sin embargo, si los procesos secundarios se ejecutan en la misma máquina que el proceso principal, no es necesario realizar ningún cambio en el firewall.

Los pasos siguientes son necesarios para configurar cada conexión de registro remoto:

Parent Process

1. Call RemoteLogController::GenerateConnectionData() to generate the connection data that must be used by both processes to initiate a logging connection.

   Note: Be sure to check the return value of this call.

       NoThrowString connectionData;
       Throw::IfFailed(RemoteLogController::GenerateConnectionData(connectionData));
   
   

2. Comunique los datos de conexión con el proceso secundario estableciéndolos en su bloque de entorno o pasándolos como argumento en la línea de comandos. For example:

   Páselo como argumento nombrado en la línea de comandos que WexLogger pueda entender:
   /wexlogger_connectiondata=[connection data]

   Note: If this option is used, then step 1 in the Child Process section below is not necessary.

   Pase como una variable de entorno con nombre que WexLogger comprende:
   [YourAppName_cmd]=/wexlogger_connectiondata=[connection data]

   Note: If this option is used, then step 1 in the Child Process section below is not necessary.

   Pasar al proceso en un formato arbitrario (algún otro parámetro de comando, variable de entorno, etc.)
   Note: If this option is used, then step 1 in the Child Process section below is necessary.

   Note: As a convenience, the value "/wexlogger_connectiondata=" is defined as a constant in both the native and managed RemoteLogControllers:

   • WEX::Logging::c_szWexLoggerRemoteConnectionData, in LogController.h

   • RemoteLogController.WexLoggerRemoteConnectionData, in Wex.Logger.Interop.dll

3. Inicio del proceso secundario con los datos de conexión

4. Llame a RemoteLogController::InitializeLogging([datos de conexión creados en el paso 1])). This call must be made after the child process is launched, since it will time out if the child does not call LogController::InitializeLogging() in a timely manner.

   Note: Be sure to check the return value of this call.

   // ...launch child process with connection data...
   Throw::IfFailed(RemoteLogController::InitializeLogging(connectionData));
   

5. Espere al proceso hijo, etc.

Child Process

1. If the connection data was not passed to the child process as a named argument at the command prompt that WexLogger understands (see step 2 above), then you must set an environment variable as such:

   [YourAppName_cmd]=/wexlogger_connectiondata=[connection data]

   For example:

   // App name is mytestapp.exe
   ::SetEnvironmentVariable(L"mytestapp_cmd", String(c_szWexLoggerRemoteConnectionData).Append(connectionData));
   

2. Call LogController::InitializeLogging() to initialize logging for this process. Internally, this will leverage the environment variable set in step 1 above (or in step 2 of the Parent Process section) to initiate a logging connection back to the parent process.

3. Registro, etc. todos los seguimientos se devolverán al proceso primario.

4. Call LogController::FinalizeLogging() to finish logging for this process.

Determinar el resultado de la prueba

Although there is a method provided to explicitly state the intended outcome of a test case (Log::Result()), there is no need for a test case to use this method in most cases.

For example, if a test case does not explicitly call Log::Result(), and does not log an error (via Log::Error()), by default it is considered a passing test case; if it does log an error, it is a failing test case.

However, if a test case does explicitly call Log::Result(TestResults::TestPassed), but also does log an error within the test case, the test will still be counted as a failure since an error occurred within the test.

Dentro del marco de TAEF, este comportamiento se puede invalidar etiquetando la prueba con un resultado de prueba predeterminado diferente. Puede encontrar más información sobre esto en el documento "Creación de pruebas DE TAEF".

This behavior can also be overridden by explicitly calling Log::StartGroup() for your own test groups/test cases, with a default test result of your choice.

Generación de registros WTT

Three methods exist to generate WTT logs via the WexLogger. All of them require that WttLog.dll is present in the run directory, or in your path.

• Si está ejecutando en el laboratorio, con el cliente wtt instalado, los registros de wtt se generarán automáticamente. Esto se debe al hecho de que WexLogger busca la existencia de dos variables de entorno que solo deben existir en un entorno de laboratorio: "WttTaskGuid" y "WTTRunWorkingDir". Si existen ambas, el registro de wtt se habilita automáticamente.

• Si se ejecuta dentro de TAEF fuera de un entorno de laboratorio, pase el comando /enablewttlogging al símbolo del sistema para su caso de prueba. Example:

  te my.test.dll /enablewttlogging
  

• Si usa WexLogger fuera del marco de TAEF y no se ejecuta en un entorno de laboratorio, debe establecer la <variable de entorno YOUR_PROCESS_NAME>_CMD para que contenga esta opción antes de llamar a LogController::InitializeLogging().. Example:

  Environment.SetEnvironmentVariable("<YOUR_PROCESS_NAME>_CMD", "/enablewttlogging");
  LogController.InitializeLogging();
  

  Environment.SetEnvironmentVariable("consoleapplication4_cmd", "/enablewttlogging");
  LogController.InitializeLogging();
  

• Si desea anexar a un archivo de registro wtt existente en lugar de sobrescribirlo, especifique también la opción /appendwttlogging además de /enablewttlogging.

  te my.test.dll /enablewttlogging /appendwttlogging
  

  Environment.SetEnvironmentVariable("<YOUR_PROCESS_NAME>_CMD", "/enablewttlogging /appendwttlogging");
  LogController.InitializeLogging();
  

  Environment.SetEnvironmentVariable("consoleapplication4_cmd", "/enablewttlogging /appendwttlogging");
  LogController.InitializeLogging();
  

También es posible sobrescribir o agregar completamente a la cadena del dispositivo predeterminado WttLogger especificando una de las siguientes opciones de comando:

/WttDeviceString:<cadena de dispositivo nueva>
Invalida completamente el WttDeviceString usado por WexLogger cuando inicializa WttLogger.

/WttDeviceStringSuffix:<valor para añadir a la cadena del dispositivo>
Anexa el valor especificado al WttDeviceString predeterminado usado por WexLogger cuando inicializa WttLogger. Se omite si también se especifica '/WttDeviceString'.

En la tabla siguiente se muestra cómo los TestResults de WexLogger se asignan a los resultados de WttLogger.

Logger Dependencies

The native C++ logger (Wex.Logger.dll) is dependent upon Wex.Common.dll and Wex.Communication.dll.

The managed logger (Wex.Logger.Interop.dll) is dependent upon Wex.Logger.dll, Wex.Common.dll and Wex.Communication.dll.

Additionally, WttLog.dll is required when Wtt Logging is enabled.

Datos de error adicionales

En caso de que se registre un error, puede habilitar WexLogger para incluir uno o varios de los siguientes elementos además del propio error:

• MiniDump
• ScreenCapture
• StackTrace

te my.test.dll /minidumponerror

te my.test.dll /screencaptureonerror /stacktraceonerror

Con una o varias de estas opciones habilitadas, recibirá una salida adicional cada vez que se llame a Log::Error().

Nota: Si usa WexLogger fuera del marco de TAEF, debe establecer la <variable de entorno YOUR_PROCESS_NAME>_CMD para que contenga estas opciones antes de llamar a LogController::InitializeLogging().. Example:

Environment.SetEnvironmentVariable("<YOUR_PROCESS_NAME>_CMD", "/screencaptureonerror /minidumponerror /stacktraceonerror");
LogController.InitializeLogging();

Environment.SetEnvironmentVariable("consoleapplication4_cmd", "/screencaptureonerror /minidumponerror /stacktraceonerror");
LogController.InitializeLogging();

Control de errores de C++

In order to shield test case authors from the burden of checking return values for each Log API call, the WexLogger reports unexpected error conditions via the use of an optional callback mechanism; a WexLoggerErrorCallback function. Upon initializaiton of the WexLogger (via LogController::InitializeLogging()), clients may choose to specify a WexLoggerErrorCallback function to call if unexpected error conditions occur within the WexLogger. The WexLoggerErrorCallback function must use the following signature:

void __stdcall MyLoggerErrorCallback(const unsigned short* pszMessage, HRESULT hr);

Un uso común de la función WexLoggerErrorCallback sería escribir los mensajes de error en la consola (si el arnés de prueba es una aplicación de consola). For example, the TAEF framework is a client of the WexLogger, and implements a WexLoggerErrorCallback which writes red text to the console when WexLogger errors occur.

Compatibilidad con .NET 4.0

Wex.Logger.Interop se compila como un binario de NetFx 2/3/3.5, de modo que se pueda cargar en procesos de NetFx 2/3/3.5 y NetFx 4. Esto permite a TAEF ejecutar todos los ensamblados administrados por encima de NetFx 2. If you're using Wex.Logger outside TAEF, then you need to add a config file for your exe to configure the NetFx 4 runtime to load NetFx 2/3/3.5 binaries into it's process. El archivo de configuración debe contener lo siguiente:

<configuration> 
    <startup useLegacyV2RuntimeActivationPolicy="true">
        <supportedRuntime version="v4.0"/>
    </startup>
</configuration>

Manejo de errores y excepciones en código gestionado

In order to shield test case authors from the burden of checking return values for each Log API call, the managed layer of the WexLogger reports unexpected error conditions via the use of the LoggerController.WexLoggerError event. You may subscribe to this event at any time by implementing your own WexLoggerErrorEventHandler and using the following familiar syntax for C# event subscription:

LogController.WexLoggerError += new WexLoggerEventHandler(My_WexLoggerErrorHandler);

Este es un ejemplo del aspecto que podría tener el controlador de eventos:

static void LogController_WexLoggerError(object sender, WexLoggerErrorEventArgs e)
{
    ConsoleColor originalColor = Console.ForegroundColor;
    Console.ForegroundColor = ConsoleColor.Red;
    Console.WriteLine("LogController_WexLoggerError: " + e.Message);
    Console.ForegroundColor = originalColor;
}

Additionally, the LogController::InitializeLogging() and LogController::FinalizeLogging() methods themselves throw WexLoggerException in the event of failure. Esto proporciona información detallada sobre el error y también permite anular la ejecución de pruebas antes de comenzar. Los autores de casos de prueba nunca tendrán que preocuparse de detectar estas excepciones: solo se deben esperar o controlar durante la inicialización o finalización de WexLogger.