WexLogger

WexLogger 提供了一個一致的日誌記錄 API，涵蓋本機代碼、託管代碼和腳本。 它也會從在命令提示字元中執行單元測試，一直擴展到長途壓力測試。

透過「驗證架構」記載

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

在 Managed 程式碼中，它看起來會像這樣：

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(). 此需求僅適用於原生和 Managed 程式碼;指令碼沒有這個額外的需求。 如需 LogController API 的詳細資訊，請參閱下面的靜態 LogController 方法 表格。

如需如何在 TAEF 外部產生 WTT 記錄的資訊，請參閱產生 WTT 記錄 一節。

WexLogger API

以下是可用的原生 C++ 日誌方法清單。

有對等版本可用於 Managed 程式碼和腳本。

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. 有對等版本可用於 Managed 程式碼和腳本。

以下是可用的原生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 環境變數設定<為包含此選項，才能呼叫 LogController：：InitializeLogging（） 。 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：<新的裝置字串>
完全覆寫 WexLogger 初始化 WttLogger 時所使用的 WttDeviceString。

/WttDeviceStringSuffix：<值附加至裝置字串>
將指定的值附加至 WexLogger 初始化 WttLogger 時所使用的預設 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環境變數設定<為包含這些選項，才能呼叫 LogController：：InitializeLogging（）。 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>

Managed 程式代碼錯誤和例外狀況處理

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 initializaiton/completion 期間才會預期/處理這些例外狀況。