WexLogger

De WexLogger biedt een consistente API voor logboekregistratie die systeemeigen code, beheerde code en script omvat. Het schaalt ook van het uitvoeren van eenheidstests in een opdrachtprompt tot langlopende stresstests.

Logboekregistratie via het Verify Framework

Most logging within a test case should be performed via the Verify framework. Dit zorgt ervoor dat tests worden gemaakt op een duidelijkere, meer sequentiële en door mensen leesbare manier. In sommige gevallen zullen testauteurs echter merken dat ze gedetailleerdere controle nodig hebben over wat er naar de logboeken wordt geschreven: vandaar de behoefte aan de WexLogger-API.

Logboekbeheer in TAEF

Voor testcases die worden uitgevoerd in TAEF, is er geen loggerinitialisatie door de testauteur vereist. U kunt direct beginnen met het gebruik van de logboek-API die beschikbaar is voor de taal waarin u uw tests ontwerpt.

In systeemeigen C++-code ziet deze er als volgt uit:

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

In beheerde code ziet deze er als volgt uit:

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

In JScript ziet deze er als volgt uit:

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

Logboekregistratie buiten TAEF

De meeste tijd wordt de initialisatie en afronding van logboekregistratie uitgevoerd door TAEF, zodat de WexLogger gedurende de volledige duur van de testcase klaar is voor gebruik en correct wordt afgerond. However, if a client would like to use the WexLogger outside TAEF, they will be responsible for manually calling LogController::InitializeLogging() and LogController::FinalizeLogging(). Deze vereiste bestaat alleen voor systeemeigen en beheerde code; scripts hebben deze aanvullende vereiste niet. Zie de tabel Static LogController Methods hieronder voor meer informatie over de LogController-API.

Raadpleeg de sectie WTT-logboeken genereren voor informatie over het genereren van WTT-logboeken buiten TAEF.

WexLogger API

Hier volgt de lijst met systeemeigen C++-logboekmethoden die beschikbaar zijn.

Er zijn gelijkwaardige versies beschikbaar voor beheerde code en scripts.

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. Er zijn gelijkwaardige versies beschikbaar voor beheerde code en scripts.

Hier volgt de lijst met systeemeigen C++ LogController-methoden die beschikbaar zijn:

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.

Hier volgt de lijst met systeemeigen C++ RemoteLogContoller-methoden die beschikbaar zijn:

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

Hier volgt de lijst met beheerde logboekmethoden die beschikbaar zijn.

Hier volgt de lijst met beheerde LogContoller-methoden die beschikbaar zijn:

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.

Hier volgt de lijst met beheerde RemoteLogContoller-methoden die beschikbaar zijn:

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

Externe logboekregistratie van subprocessen

WexLogger biedt de mogelijkheid voor een of meer subprocessen om loggegevens terug te sturen naar één ouderproces, waardoor geconsolideerde testresultaten worden gegenereerd in één logbestand.

De childprocessen kunnen draaien op dezelfde machine als het bovenliggende proces of op een andere machine. Logboekregistratie op afstand werkt alleen als de WexLogger-client TCP-firewalluitsluitingen toevoegt voor alle onderliggende processen op de externe computer. Als de kindprocessen echter worden uitgevoerd op dezelfde computer als de ouder, zijn er geen firewallwijzigingen nodig.

De volgende stappen zijn nodig om elke externe logboekregistratieverbinding in te stellen:

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. Communiceer de verbindingsgegevens met het onderliggende proces door deze in te stellen in het omgevingsblok of door deze door te geven als argument bij de opdrachtprompt. For example:

   Geef als een benoemd argument door aan de opdrachtprompt, die door WexLogger begrepen wordt:
   /wexlogger_connectiondata=[connection data]

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

   Geef door als een benoemde omgevingsvariabele die WexLogger begrijpt:
   [YourAppName_cmd]=/wexlogger_connectiondata=[connection data]

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

   Voer de gegevens in een willekeurig formaat in (een andere opdrachtparameter, omgevingsvariabele, enzovoort)
   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. Start het subproces met de verbindingsgegevens

4. RemoteLogController aanroepen::InitializeLogging([verbindingsgegevens gemaakt in stap 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. Wacht op het child proces, enzovoort.

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. Logboek, enz; alle traceringen worden teruggestuurd naar het bovenliggende proces.

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

Testresultaat bepalen

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.

Binnen het TAEF-framework kan dit gedrag worden overschreven door uw test te taggen met een ander standaardtestresultaat. Meer informatie hierover vindt u in het document 'TaEF-tests ontwerpen'.

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-logboeken genereren

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.

• Als u in het lab werkt en de wtt-client is geïnstalleerd, worden wtt-logboeken automatisch voor u gegenereerd. Dit komt door het feit dat de WexLogger zoekt naar het bestaan van twee omgevingsvariabelen die alleen in een testomgeving moeten bestaan: 'WttTaskGuid' en 'WTTRunWorkingDir'. Als beide bestaan, wordt wtt-logboekregistratie automatisch ingeschakeld.

• Als u TAEF buiten een laboratoriumomgeving gebruikt, geef /enablewttlogging door aan de opdrachtprompt voor uw testcase. Example:

  te my.test.dll /enablewttlogging
  

• Als u WexLogger buiten het TAEF-raamwerk gebruikt en u niet in een laboratoriumomgeving werkt, moet u de omgevingsvariabele <YOUR_PROCESS_NAME>_CMD instellen om deze optie te bevatten voordat u LogController::InitializeLogging() aanroept. Example:

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

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

• Als u een bestaand wtt-logboekbestand wilt toevoegen in plaats van het te overschrijven, geeft u ook de optie /appendwttlogging op naast /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();
  

Het is ook mogelijk om de standaard-WttLogger-apparaattekenreeks volledig te overschrijven of toe te voegen door een van de volgende opdrachtopties op te geven:

/WttDeviceString:<nieuwe apparaattekenreeks>
Hiermee wordt de WttDeviceString die door WexLogger wordt gebruikt, volledig overschreven wanneer WttLogger wordt geïnitialiseerd.

/WttDeviceStringSuffix:<waarde om aan de apparaatreeks toe te voegen>
Voegt de opgegeven waarde toe aan de standaard WttDeviceString die door WexLogger wordt gebruikt wanneer WttLogger wordt geïnitialiseerd. Genegeerd als ook '/WttDeviceString' is opgegeven.

In de volgende tabel ziet u hoe WexLogger TestResults overeenkomen met WttLogger-resultaten:

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.

Aanvullende foutgegevens

Als er een fout wordt geregistreerd, kunt u Inschakelen dat WexLogger een of meer van de volgende items bevat, naast de fout zelf:

• MiniDump
• ScreenCapture
• StackTrace

te my.test.dll /minidumponerror

te my.test.dll /screencaptureonerror /stacktraceonerror

Als een of meer van deze opties zijn ingeschakeld, ontvangt u elke keer dat Log::Error() wordt aangeroepen extra uitvoer.

Opmerking: Als u WexLogger buiten het TAEF-framework gebruikt, moet u de <omgevingsvariabele YOUR_PROCESS_NAME> instellen_CMD om deze opties te bevatten voordat u LogController::InitializeLogging()aanroept. Example:

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

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

C++ Foutafhandeling

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

Een veelvoorkomend gebruik voor de WexLoggerErrorCallback-functie is het schrijven van de foutberichten naar de console (als uw testharnas een consoletoepassing is). 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.

Compatibiliteit met .NET 4.0

Wex.Logger.Interop wordt gecompileerd als een binair bestand van NetFx 2/3/3.5, zodat het kan worden geladen in zowel NetFx 2/3/3.5- als NetFx 4-processen. Hierdoor kan TAEF alle beheerde assembly's uitvoeren boven 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. Het configuratiebestand moet het volgende bevatten:

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

Fout- en uitzonderingsafhandeling van beheerde code

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

Hier volgt een voorbeeld van hoe uw gebeurtenis-handler eruit kan zien:

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. Dit biedt gedetailleerde informatie over de fout en stelt u ook in staat om de testuitvoering af te breken voordat deze begint. Auteurs van testcases hoeven zich nooit zorgen te maken over het vangen van deze uitzonderingen. Ze moeten alleen worden verwacht/verwerkt tijdens de initializaiton/voltooiing van WexLogger.