WexLogger

WexLogger fournit une API cohérente pour la journalisation qui couvre le code natif, le code managé et le script. Il permet également de passer de l’exécution de tests unitaires dans une invite de commandes à des tests d'endurance.

Journalisation via l’infrastructure de vérification

Most logging within a test case should be performed via the Verify framework. Cela garantit que les tests sont créés de manière plus claire, plus séquentielle et lisible par l’homme. Toutefois, dans certains cas, les auteurs de tests constatent qu’ils ont besoin d’un contrôle plus précis sur ce qui est écrit dans les journaux : par conséquent, la nécessité de l’API WexLogger.

Journalisation dans TAEF

Pour les cas de test s’exécutant dans TAEF, il n’existe aucune initialisation d’enregistreur d’événements nécessaire par l’auteur du test. Vous pouvez commencer immédiatement à utiliser l’API de logging exposée dans le langage dans lequel vous créez vos tests.

Dans le code C++ natif, il se présente comme suit :

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

Dans le code managé, il se présente comme suit :

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

Dans JScript, il se présente comme suit :

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

Enregistrement en dehors de TAEF

La majorité du temps, l’initialisation et l’achèvement de la journalisation seront effectuées par TAEF, de sorte que WexLogger sera prêt à être utilisé pour la durée du cas de test, comme indiqué ci-dessus, et se terminera correctement. However, if a client would like to use the WexLogger outside TAEF, they will be responsible for manually calling LogController::InitializeLogging() and LogController::FinalizeLogging(). Cette exigence existe uniquement pour le code natif et managé ; les scripts n’ont pas cette exigence supplémentaire. Pour plus d’informations sur l’API LogController, consultez le tableau Des méthodes LogController statiques ci-dessous.

Reportez-vous à la section Génération de journaux WTT pour plus d’informations sur la façon de générer des journaux WTT en dehors de TAEF.

WexLogger API

Voici la liste des méthodes de journal C++ natives disponibles.

Il existe des versions équivalentes disponibles pour le code managé et le 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. Il existe des versions équivalentes disponibles pour le code managé et le script.

Voici la liste des méthodes LogController C++ natives disponibles :

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.

Voici la liste des méthodes RemoteLogContoller natives C++ disponibles :

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

Voici la liste des méthodes de journal managées disponibles.

Voici la liste des méthodes LogContoller gérées disponibles :

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.

Voici la liste des méthodes RemoteLogContoller gérées disponibles :

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

Journalisation à distance à partir de processus fils

WexLogger offre la possibilité pour un ou plusieurs processus enfants de se reconnecter à un processus parent unique, ce qui entraîne la génération de résultats de test consolidés dans un fichier journal unique.

Les processus enfants peuvent fonctionner sur le même ordinateur que le processus parent ou s'opérer à distance sur un autre ordinateur. Pour que la journalisation à distance fonctionne, il incombe au client WexLogger d’ajouter des exclusions de pare-feu TCP pour tous les processus enfants sur l’ordinateur distant. Toutefois, si les processus enfants s’exécutent sur le même ordinateur que le parent, aucune modification de pare-feu n’est nécessaire.

Les étapes suivantes sont nécessaires pour configurer chaque connexion de journalisation à distance :

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. Communiquez les données de connexion avec le processus enfant en le définissant dans son bloc d’environnement ou en le transmettant en tant qu’argument à l’invite de commandes. For example:

   Passez-le en tant qu’argument nommé à l’invite de commandes que comprend WexLogger :
   /wexlogger_connectiondata=[connection data]

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

   Passez comme variable d’environnement nommée que WexLogger comprend :
   [YourAppName_cmd]=/wexlogger_connectiondata=[connection data]

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

   Transmettre dans le processus sous un format arbitraire (un autre paramètre de commande, une variable d'environnement, 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. Lancer le processus enfant avec les données de connexion

4. Appelez RemoteLogController ::InitializeLogging([données de connexion créées à l’étape 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. Attendre la finalisation du processus enfant, 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. Journal, etc ; toutes les traces seront renvoyées au processus parent.

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

Détermination du résultat du test

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.

Dans l’infrastructure TAEF, ce comportement peut être substitué en étiquetant votre test avec un résultat de test par défaut différent. Pour plus d’informations, consultez le document « Création de tests 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.

Génération des 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.

• Si vous travaillez dans le laboratoire, avec le client wtt installé, les fichiers journal wtt seront générés automatiquement pour vous. Cela est dû au fait que WexLogger recherche l’existence de deux variables d’environnement qui doivent exister uniquement dans un environnement lab : « WttTaskGuid » et « WTTRunWorkingDir ». Si ces deux éléments existent, la journalisation wtt est automatiquement activée.

• Si vous exécutez TAEF en dehors d’un environnement de laboratoire, passez /enablewttlogging à la ligne de commande pour votre cas de test. Example:

  te my.test.dll /enablewttlogging
  

• Si vous utilisez WexLogger en dehors de l’infrastructure TAEF et que vous n’exécutez pas dans un environnement lab, vous devez définir la <variable d’environnement YOUR_PROCESS_NAME>_CMD pour contenir cette option avant d’appeler LogController ::InitializeLogging(). Example:

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

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

• Si vous souhaitez ajouter un fichier journal wtt existant au lieu de le remplacer, spécifiez également l’option /appendwttlogging en plus 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();
  

Il est également possible de remplacer complètement ou d’ajouter à la chaîne du périphérique WttLogger par défaut en spécifiant l’une des options de commande suivantes :

/WttDeviceString :<nouvelle chaîne de périphérique>
Remplace complètement le WttDeviceString utilisé par WexLogger quand il initialise WttLogger.

/WttDeviceStringSuffix :<value à ajouter à la chaîne d’appareil>
Ajoute la valeur spécifiée au WttDeviceString par défaut utilisé par WexLogger lorsqu’il initialise WttLogger. Ignoré si '/WttDeviceString' est également spécifié.

Le tableau suivant répertorie comment les TestResults de WexLogger correspondent aux résultats de 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.

Données d’erreur supplémentaires

En cas de journalisation d’une erreur, vous pouvez activer WexLogger pour inclure un ou plusieurs des éléments suivants en plus de l’erreur elle-même :

• MiniDump
• ScreenCapture
• StackTrace

te my.test.dll /minidumponerror

te my.test.dll /screencaptureonerror /stacktraceonerror

Une ou plusieurs de ces options étant activées, vous recevrez une sortie supplémentaire chaque fois que Log ::Error() est appelé.

Remarque : Si vous utilisez WexLogger en dehors de l’infrastructure TAEF, vous devez définir la <variable d’environnement YOUR_PROCESS_NAME>_CMD pour contenir ces options avant d’appeler LogController ::InitializeLogging(). Example:

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

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

Gestion des erreurs 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);

Une utilisation courante de la fonction WexLoggerErrorCallback consiste à écrire les messages d’erreur dans la console (si votre harnais de test est une application 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.

Compatibilité de .NET 4.0

Wex.Logger.Interop est compilé en tant que binaire NetFx 2/3/3.5, afin qu’il puisse être chargé dans les processus NetFx 2/3/3.5 et NetFx 4. Cela permet à TAEF d’exécuter tous les assemblys managés au-dessus de 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. Le fichier config doit contenir les éléments suivants :

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

Gestion des erreurs et des exceptions du code managé

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

Voici un exemple de ce à quoi votre gestionnaire d’événements pourrait ressembler :

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. Cela fournit des informations détaillées sur l’erreur et vous permet également d’abandonner la série de tests avant de commencer. Les auteurs de cas de test n’auront jamais besoin de s’inquiéter de la capture de ces exceptions. Ces exceptions doivent être attendues et gérées seulement lors de l'initialisation ou du l'achèvement de WexLogger.