WexLogger

O WexLogger fornece uma API consistente para registro em log que abrange código nativo, código gerenciado e script. Ele também escalona da execução de Testes Unitários em um prompt de comando até os testes de estresse de longa duração.

Fazer logon por meio da Estrutura de Verificação

Most logging within a test case should be performed via the Verify framework. Isso garantirá que os testes sejam criados de forma mais clara, sequencial e legível para humanos. No entanto, em alguns casos, os autores de teste descobrirão que precisam de um controle mais granular em torno do que é gravado nos logs: daí a necessidade da API wexLogger.

Registro em log no TAEF

Para casos de teste em execução no TAEF, não há nenhuma inicialização de logger necessária pelo autor do teste. Você pode começar imediatamente a usar a API de Log exposta ao idioma no qual você está criando seus testes.

No código C++ nativo, ele terá esta aparência:

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);

No código gerenciado, ele terá esta aparência:

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

No JScript, ele terá esta aparência:

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

Registro fora do TAEF

Na maioria das vezes, a inicialização e a conclusão do registro serão realizadas pelo TAEF, de forma que o WexLogger estará pronto para uso durante toda a duração do caso de teste, conforme indicado acima, e irá finalizar corretamente. However, if a client would like to use the WexLogger outside TAEF, they will be responsible for manually calling LogController::InitializeLogging() and LogController::FinalizeLogging(). Esse requisito existe apenas para código nativo e gerenciado; os scripts não têm esse requisito adicional. Consulte a tabela Métodos LogController Estáticos abaixo para obter mais informações sobre a API LogController.

Consulte a seção Gerando Logs do WTT para obter informações sobre como gerar logs WTT fora do TAEF.

WexLogger API

Aqui está a lista de métodos nativos do Log do C++ disponíveis.

Há versões equivalentes disponíveis para código gerenciado e 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. Há versões equivalentes disponíveis para código gerenciado e script.

Aqui está a lista de métodos nativos do LogController C++ disponíveis:

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.

Aqui está a lista de métodos RemoteLogContoller C++ nativos disponíveis:

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

Aqui está a lista de métodos de log gerenciados disponíveis.

Aqui está a lista de métodos LogContoller gerenciados disponíveis:

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.

Aqui está a lista de métodos RemoteLogContoller gerenciados disponíveis:

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

Registro de log remoto de processos filhos

O WexLogger fornece a capacidade de um ou mais processos filho registrarem informações para um único processo pai, resultando na geração de resultados de teste consolidados em um único arquivo de log.

Os processos filho podem ser executados no mesmo computador que o processo pai ou remotamente em um computador diferente. Para que o registro em log de máquina remota funcione, cabe ao cliente WexLogger adicionar exclusões de firewall TCP para todos os processos filho no computador remoto. No entanto, se os processos filho estiverem em execução no mesmo computador que o pai, nenhuma modificação de firewall será necessária.

As etapas a seguir são necessárias para configurar cada conexão de log 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 os dados de conexão com o processo filho definindo-os em seu bloco de ambiente ou passando-os como um argumento no prompt de comando. For example:

   Passe como um argumento com nome no prompt de comando do qual o WexLogger entende:
   /wexlogger_connectiondata=[connection data]

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

   Passe como uma variável de ambiente nomeada que o WexLogger entende:
   [YourAppName_cmd]=/wexlogger_connectiondata=[connection data]

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

   Passe para o processo em um formato arbitrário (algum outro parâmetro de comando, variável de ambiente 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. Iniciar o subprocesso com os dados de conexão

4. Chame RemoteLogController::InitializeLogging([dados de conexão criados na etapa 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. Aguarde a finalização do processo filho, entre outros.

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. Log etc; todos os rastreamentos serão enviados de volta para o processo pai.

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

Determinando o resultado do teste

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 da estrutura TAEF, esse comportamento pode ser substituído marcando seu teste com um resultado de teste padrão diferente. Mais informações sobre isso podem ser encontradas no documento "Criando testes 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.

Gerando logs do 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.

• Se você estiver executando no laboratório, com o cliente wtt instalado, os logs do wtt serão gerados automaticamente para você. Isso ocorre devido ao fato de que o WexLogger procura a existência de duas variáveis de ambiente que só devem existir em um ambiente de laboratório: 'WttTaskGuid' e 'WTTRunWorkingDir'. Se ambos existirem, o registro de log wtt será habilitado automaticamente.

• Se estiver executando o TAEF fora de um ambiente de laboratório, execute o comando /enablewttlogging no prompt de comando para o caso de teste. Example:

  te my.test.dll /enablewttlogging
  

• Se você estiver consumindo o WexLogger fora da estrutura TAEF e não estiver em execução em um ambiente de laboratório, deverá definir a <variável de ambiente YOUR_PROCESS_NAME>_CMD para conter essa opção antes de chamar LogController::InitializeLogging(). Example:

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

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

• Se você quiser acrescentar a um arquivo de log wtt existente em vez de substituí-lo, especifique também a opção /appendwttlogging além 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();
  

Também é possível substituir completamente ou acrescentar à cadeia de caracteres padrão do dispositivo WttLogger especificando uma das seguintes opções de comando:

/WttDeviceString:<nova cadeia de dispositivo>
Substitui completamente o WttDeviceString usado pelo WexLogger quando inicializa o WttLogger.

/WttDeviceStringSuffix:<valor a ser adicionado à string do dispositivo>
Acrescenta o valor especificado ao WttDeviceString padrão usado pelo WexLogger quando inicializa o WttLogger. Ignorado se '/WttDeviceString' também for especificado.

A tabela a seguir lista como os TestResults do WexLogger são mapeados para os resultados do 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.

Dados de erro adicionais

Caso um erro seja registrado, você poderá permitir que o WexLogger inclua um ou mais dos seguintes itens, além do erro em si:

• MiniDump
• ScreenCapture
• StackTrace

te my.test.dll /minidumponerror

te my.test.dll /screencaptureonerror /stacktraceonerror

Com uma ou mais dessas opções habilitadas, você receberá uma saída extra sempre que Log::Error() for chamado.

Observação: se você estiver consumindo o WexLogger fora da estrutura TAEF, deverá definir a <variável de ambiente YOUR_PROCESS_NAME>_CMD para conter essas opções antes de chamar LogController::InitializeLogging(). Example:

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

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

Tratamento de erros do 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);

Um uso comum para a função WexLoggerErrorCallback seria gravar as mensagens de erro no console (se o seu cinto de teste for um aplicativo de console). 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.

Compatibilidade do .NET 4.0

Wex.Logger.Interop é compilado como um binário NetFx 2/3/3.5, de modo que ele possa ser carregado nos processos NetFx 2/3/3.5 e NetFx 4. Isso permite que o TAEF execute todos os assemblies gerenciados acima do 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. O arquivo de configuração deve conter o seguinte:

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

Erro de código gerenciado e tratamento de exceções

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);

Aqui está um exemplo de como seu manipulador de eventos pode ser:

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. Isso fornece informações detalhadas sobre o erro e também permite anular a execução do teste antes de começar. Os autores de casos de teste nunca precisarão se preocupar em capturar essas exceções – elas devem ser esperadas/tratadas somente durante a inicialização/conclusão do WexLogger.