WexLogger

O WexLogger fornece uma API consistente para registro em log que abrange código nativo, código gerenciado e script. Também é escalável, desde a execução de testes de unidade em um prompt de comando até testes de esforço de longa duração.

Log através do Verify Framework

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 por humanos. No entanto, em alguns casos, os autores do teste descobrirão que precisam de um controle mais granular em torno do que é gravado nos logs: daí a necessidade da API WexLogger.

Registo em TAEF

Para casos de teste em execução no TAEF, não há inicialização do registrador necessária pelo autor do teste. Você pode começar imediatamente a usar a API de log que está 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, terá a seguinte aparência:

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

Exploração madeireira fora do TAEF

Na maioria das vezes, a inicialização e a conclusão do registro serão realizadas pelo TAEF, de modo que o WexLogger estará pronto para uso durante a duração do caso de teste, como mencionado acima, e terminará 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(). Este requisito existe apenas para código nativo e gerenciado; Os scripts não têm esse requisito adicional. Consulte a tabela Static LogController Methods abaixo para obter mais informações sobre a API LogController.

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

WexLogger API

Aqui está a lista de métodos C++ Log nativos 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 C++ LogController nativos 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 C++ RemoteLogContoller 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 gerenciados RemoteLogContoller disponíveis:

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

Registro remoto de processos filho

O WexLogger fornece a capacidade de um ou mais processos filho efetuarem login novamente em um processo pai único, resultando na geração de resultados de teste consolidados em um único arquivo de log.

Os processos filho podem ser executados na mesma máquina que o processo pai ou remotamente noutra máquina. Para que o registo de máquina remota funcione, cabe ao cliente WexLogger adicionar exclusões de firewall TCP para todos os subprocessos na máquina remota. No entanto, se os processos filho estiverem sendo executados na mesma máquina que o pai, nenhuma modificação de firewall será necessária.

As seguintes etapas 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 nomeado no prompt de comando que 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.

   Passar a processar em formato arbitrário (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. Inicie o processo filho 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 o processo da criança, 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. Registos, entre outros; 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 "Criação de 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.

Geração de logs 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 estiver a operar no laboratório com o cliente wtt instalado, os logs wtt serão automaticamente gerados para si. Isso se deve 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 wtt será ativado automaticamente.

• Se estiver a executar aplicações dentro do TAEF fora de um ambiente de laboratório, introduza /enablewttlogging na linha de comandos no seu caso de teste. Example:

  te my.test.dll /enablewttlogging
  

• Se você estiver consumindo WexLogger fora da estrutura TAEF e não estiver executando 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 o texto padrão do dispositivo WttLogger especificando um dos seguintes comandos:

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

/WttDeviceStringSuffix:<valor a ser anexado à cadeia de caracteres do dispositivo>
Acrescenta o valor especificado ao padrão WttDeviceString usado por WexLogger quando ele inicializa WttLogger. Ignorado se '/WttDeviceString' também for especificado.

A tabela a seguir relaciona como o WexLogger TestResults mapeia 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

No caso de um erro ser registrado, você pode habilitar o WexLogger para incluir 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 toda vez que Log::Error() for chamado.

Nota: Se você estiver consumindo 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 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 conjunto 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 com .NET 4.0

Wex.Logger.Interop é compilado como um binário NetFx 2/3/3.5, para que possa ser carregado em ambos os 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>

Tratamento de erros e exceções de código gerenciado

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 parecer:

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 que você aborte a execução do teste antes que ele comece. Os autores de casos de teste nunca precisarão se preocupar em capturar essas exceções - elas devem ser esperadas/tratadas apenas durante a inicialização/conclusão do WexLogger.