WexLogger

WexLogger는 네이티브 코드, 관리 코드 및 스크립트에 걸쳐 있는 로깅을 위한 일관된 API를 제공합니다. 또한 명령 프롬프트에서 단위 테스트를 실행하는 것부터 장거리 스트레스 테스트까지 확장됩니다.

Verify Framework를 통한 로깅

Most logging within a test case should be performed via the Verify framework. 이렇게 하면 테스트가 더 명확하고 순차적이고 사람이 읽을 수 있는 방식으로 작성됩니다. 그러나 경우에 따라 테스트 작성자는 로그에 기록되는 내용에 대해 보다 세부적인 제어가 필요하므로 WexLogger API가 필요합니다.

TAEF 내에서 로깅

TAEF 내에서 실행되는 테스트 사례의 경우 테스트 작성자가 필요한 로거 초기화가 없습니다. 테스트를 작성하는 언어에 노출되는 로그 API 사용을 즉시 시작할 수 있습니다.

네이티브 C++ 코드에서는 다음과 같이 표시됩니다.

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

관리 코드에서는 다음과 같이 표시됩니다.

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

JScript에서는 다음과 같이 표시됩니다.

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

TAEF 외부 로깅

대부분의 시간, 로깅 초기화 및 완료는 TAEF에서 수행되므로 WexLogger는 위에서 설명한 대로 테스트 사례 기간 동안 사용할 준비가 되어 제대로 완료됩니다. However, if a client would like to use the WexLogger outside TAEF, they will be responsible for manually calling LogController::InitializeLogging() and LogController::FinalizeLogging(). 이 요구 사항은 네이티브 및 관리 코드에만 존재합니다. 스크립트에는 이 추가 요구 사항이 없습니다. LogController API에 대한 자세한 내용은 아래의 Static LogController 메서드 테이블을 참조하세요.

TAEF 외부에서 WTT 로그를 생성하는 방법에 대한 자세한 내용은 WTT 로그 생성 섹션을 참조하세요.

WexLogger API

다음은 사용할 수 있는 네이티브 C++ 로그 메서드 목록입니다.

관리 코드 및 스크립트에 사용할 수 있는 동일한 버전이 있습니다.

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. 관리 코드 및 스크립트에 사용할 수 있는 동일한 버전이 있습니다.

다음은 사용할 수 있는 네이티브 C++ LogController 메서드 목록입니다.

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.

다음은 사용할 수 있는 네이티브 C++ RemoteLogContoller 메서드 목록입니다.

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

다음은 사용 가능한 관리 로그 메서드 목록입니다.

다음은 사용 가능한 관리되는 LogContoller 메서드 목록입니다.

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.

다음은 사용 가능한 관리형 RemoteLogContoller 메서드 목록입니다.

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

자식 프로세스에서 원격 로깅

WexLogger는 하나 이상의 자식 프로세스가 단일 부모 프로세스에 다시 로그하는 기능을 제공하므로 단일 로그 파일 내에서 통합된 테스트 결과가 생성됩니다.

자식 프로세스는 부모 프로세스와 동일한 컴퓨터에서 실행되거나 다른 컴퓨터에서 원격으로 실행될 수 있습니다. 원격 머신 로깅이 작동하려면 WexLogger 클라이언트가 원격 컴퓨터의 모든 자식 프로세스에 대해 TCP 방화벽 제외를 추가해야 합니다. 그러나 자식 프로세스가 부모와 동일한 컴퓨터에서 실행되는 경우 방화벽 수정이 필요하지 않습니다.

각 원격 로깅 연결을 설정하려면 다음 단계가 필요합니다.

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. 연결 데이터를 환경 블록에서 설정하거나 명령 프롬프트에서 인수로 전달하여 자식 프로세스와 연결 데이터를 전달합니다. For example:

   WexLogger에서 이해하는 명령 프롬프트에서 명명된 인수로 전달합니다.
   /wexlogger_connectiondata=[connection data]

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

   WexLogger에서 이해하는 명명된 환경 변수로 전달합니다.
   [YourAppName_cmd]=/wexlogger_connectiondata=[connection data]

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

   임의의 형식(다른 명령 매개 변수, 환경 변수 등)으로 처리하도록 전달합니다.
   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. 연결 데이터를 사용하여 자식 프로세스 시작

4. RemoteLogController::InitializeLogging([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. 자식 프로세스 등을 기다립니다.

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. 로그 등 모든 추적은 부모 프로세스로 다시 전송됩니다.

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

테스트 결과 결정

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.

TAEF 프레임워크 내에서 해당 동작은 다른 기본 테스트 결과로 테스트에 태그를 지정하여 덮어쓸 수 있습니다. 이에 대한 자세한 내용은 "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.

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.

• wtt 클라이언트가 설치된 랩에서 실행하는 경우 wtt 로그가 자동으로 생성됩니다. 이는 WexLogger가 랩 환경에만 존재해야 하는 두 개의 환경 변수인 'WttTaskGuid'와 'WTTRunWorkingDir'의 존재를 찾기 때문입니다. 둘 다 있는 경우 wtt 로깅이 자동으로 사용하도록 설정됩니다.

• 랩 환경 외부에서 TAEF 내에서 실행되는 경우 명령 프롬프트에서 /enablewttlogging을 테스트 사례에 전달합니다. Example:

  te my.test.dll /enablewttlogging
  

• TAEF 프레임워크 외부에서 WexLogger를 사용하고 랩 환경에서 실행되지 않는 경우 <을 호출하기 전에 이 옵션을 포함하도록 YOUR_PROCESS_NAME>_CMD 환경 변수를 설정해야 합니다. Example:

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

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

• 덮어쓰지 않고 기존 wtt 로그 파일에 추가하려는 경우 /enablewttlogging 외에 /appendwttlogging 옵션도 지정합니다.

  te my.test.dll /enablewttlogging /appendwttlogging
  

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

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

다음 명령 옵션 중 하나를 지정하여 기본 WttLogger 디바이스 문자열을 완전히 재정의하거나 추가할 수도 있습니다.

/WttDeviceString:<새 디바이스 문자열>
WttLogger를 초기화할 때 WexLogger에서 사용하는 WttDeviceString을 완전히 덮어씁니다.

/WttDeviceStringSuffix:<장치 문자열에 추가할 값>
지정된 값을 WttLogger를 초기화할 때 WexLogger에서 사용하는 기본 WttDeviceString에 추가합니다. '/WttDeviceString'도 지정되면 무시됩니다.

다음 표에서는 WexLogger TestResults가 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.

추가 오류 데이터

오류가 기록되는 경우 오류 자체 외에도 다음 항목 중 하나 이상을 포함하도록 WexLogger를 사용하도록 설정할 수 있습니다.

• MiniDump
• ScreenCapture
• StackTrace

te my.test.dll /minidumponerror

te my.test.dll /screencaptureonerror /stacktraceonerror

이러한 옵션 중 하나 이상을 사용하도록 설정하면 Log::Error()가 호출될 때마다 추가 출력이 표시됩니다.

참고: TAEF 프레임워크 외부에서 WexLogger를 사용하는 경우 <을 호출하기 전에 이러한 옵션을 포함하도록 YOUR_PROCESS_NAME>_CMD 환경 변수를 설정해야 합니다. Example:

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

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

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

WexLoggerErrorCallback 함수의 일반적인 용도는 콘솔에 오류 메시지를 기록하는 것입니다(테스트 도구가 콘솔 애플리케이션인 경우). 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.

.NET 4.0 호환성

Wex.Logger.Interop는 NetFx 2/3/3.5 이진 파일로 컴파일되므로 NetFx 2/3/3.5 및 NetFx 4 프로세스 모두에 로드할 수 있습니다. 이를 통해 TAEF는 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. 구성 파일에는 다음이 포함되어야 합니다.

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

관리 코드 오류 및 예외 처리

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

이벤트 처리기의 예는 다음과 같습니다.

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. 이렇게 하면 오류에 대한 자세한 정보가 제공되고 테스트 실행이 시작되기 전에 중단될 수도 있습니다. 테스트 케이스 작성자는 이러한 예외를 처리해야 하는 것에 대해 걱정할 필요가 없습니다. WexLogger 초기화 및 완료 시에만 예상하고 처리해야 합니다.