WexLogger

WexLogger は、ネイティブ コード、マネージド コード、スクリプトにまたがるログ記録用の一貫した API を提供します。 また、コマンド プロンプトでの単体テストの実行から、長距離ストレス テストまで拡張できます。

Verify Framework を使用したログ記録

Most logging within a test case should be performed via the Verify framework. これにより、テストがより明確で、よりシーケンシャルで人間が判読できる方法で作成されます。 ただし、場合によっては、テスト作成者は、ログに書き込まれる内容をより細かく制御する必要があることがわかります。そのため、WexLogger API が必要になります。

TAEF 内のログ記録

TAEF 内で実行されているテスト ケースの場合、テスト作成者がロガーの初期化を行う必要はありません。 テストを作成する言語に公開されている Log 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 の詳細については、以下の静的 LogController メソッドの表を参照してください。

TAEF の外部で WTT ログを生成する方法については、「WTT ログ の生成」セクションを参照してください。

WexLogger API

使用可能なネイティブ C++ Log メソッドの一覧を次に示します。

マネージド コードとスクリプトで使用できる同等のバージョンがあります。

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 は、1 つ以上の子プロセスが単一の親プロセスにログを記録する機能を提供し、その結果、1 つのログ ファイル内に統合テスト結果が生成されます。

子プロセスは、親プロセスと同じコンピューター上で実行することも、別のコンピューターでリモートで実行することもできます。 リモート マシンのログ記録を機能させるには、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 がラボ環境にのみ存在する必要がある 2 つの環境変数 '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 を有効にして、エラー自体に加えて、次の項目を 1 つ以上含めることができます。

• MiniDump
• ScreenCapture
• StackTrace

te my.test.dll /minidumponerror

te my.test.dll /screencaptureonerror /stacktraceonerror

これらのオプションの 1 つ以上を有効にすると、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 の初期化/完了時にのみ、これらの例外を予期/処理する必要があります。