Using Folders

Applies to TestComplete 14.72, last modified on April 22, 2021

By default, TestComplete maintains a plain log structure. However, you can organize related messages into several folders within the script or keyword test log. For instance, you can divide the test into several logical tests and post messages of each test to a special folder. Below is a description of how you can do this in scripts and keyword tests.

Working With Log Folders From Scripts

To create a folder, call the Log.CreateFolder or Log.AppendFolder method. They create a folder node and return the integer identifier of the new folder. This identifier can be passed to methods that post messages to the log to specify the folder to which the message will be added. The folder identifier is specified by the FolderId parameter of these methods. This parameter is optional. By default, it is -1 and TestComplete posts messages to either the log root, or to the folder which is “active” at the moment.

The AppendFolder and CreateFolder methods are similar. The difference between them is that AppendFolder creates a new folder and activates it (that is, all subsequent calls to the Message, Error, Event and other methods will post messages to this folder).

CreateFolder creates a folder node, but does not make it active, so the subsequent messages are not posted to this new folder. TestComplete continues posting them to the current active folder until this folder is changed. To make the new folder active, call the Log.PushLogFolder method. TestComplete does use a stack mechanism to control the active folder. After a folder became active, TestComplete posts all messages, images and files to that folder until the folder is removed from the stack or until it is replaced with another folder. By specifying a folder in the FolderId parameter in a call to the Message, Error or other similar method, you can override the “active” folder for that method call.

Note that you do not need to call PushLogFolder after AppendFolder since the latter automatically activates the newly created folder. You can consider this method as a combination of CreateFolder and PushLogFolder.

To activate the folder that was active before the last call to PushLogFolder or AppendFolder, use Log.PopLogFolder.

The following code demonstrates how you can create a two-level hierarchy of messages with the Log object’s methods from your script:

JavaScript, JScript

function Test()
{
  var Folder1, Folder2;

  Log.Message("Message A");

  // Creates a folder and activates it
  Folder1 = Log.CreateFolder("Folder1");
  Log.PushLogFolder(Folder1);

  // Posts messages to the new folder
  Log.Message("Message B");

  // Creates one more folder
  Folder2 = Log.CreateFolder("Folder 2", "", pmNormal, Log.CreateNewAttributes(), Folder1);

  // The following messages will be posted to Folder 1,
  // because Folder 2 was not activated
  Log.Message("Message C");
  Log.Message("Message D");

  // Activates Folder2 and posts messages to it
  Log.PushLogFolder(Folder2);
  Log.Message("Message E");

  // Restores the active folder (Folder1) and posts messages to it
  Log.PopLogFolder();
  Log.Message("Message F");
}

Python

def Test():  
  Log.Message("Message A")

  # Creates a folder and activates it
  Folder1 = Log.CreateFolder("Folder1")
  Log.PushLogFolder(Folder1)

  # Posts messages to the new folder
  Log.Message("Message B")

  # Creates one more folder
  Folder2 = Log.CreateFolder("Folder 2", "", pmNormal, Log.CreateNewAttributes(), Folder1)

  # The following messages will be posted to Folder 1,
  # because Folder 2 was not activated
  Log.Message("Message C")
  Log.Message("Message D")

  # Activates Folder2 and posts messages to it 
  Log.PushLogFolder(Folder2)
  Log.Message("Message E")

  # Restores the active folder (Folder1) and posts messages to it 
  Log.PopLogFolder()
  Log.Message("Message F")

VBScript

Sub Test
  Dim Folder1, Folder2

  Log.Message("Message A")

  ' Creates a folder and activates it
  Folder1 = Log.CreateFolder("Folder1")
  Log.PushLogFolder(Folder1)

  ' Posts messages to the new folder
  Log.Message("Message B")

  ' Creates one more folder
  Folder2 = Log.CreateFolder("Folder 2", , , , Folder1)

  ' The following messages will be posted to Folder 1,
  ' because Folder 2 was not activated
  Log.Message("Message C")
  Log.Message("Message D")

  ' Activates Folder2 and posts messages to it
  Log.PushLogFolder(Folder2)
  Log.Message("Message E")

  ' Restores the active folder (Folder1) and posts messages to it
  Log.PopLogFolder
  Log.Message("Message F")
End Sub

DelphiScript

var
  Folder1, Folder2;
begin
  Log.Message('Message A');

  // Creates a folder and activates it
  Folder1 := Log.CreateFolder('Folder 1');
  Log.PushLogFolder(Folder1);

  // Posts messages to the new folder
  Log.Message('Message B');

  // Creates one more folder
  Folder2 := Log.CreateFolder('Folder 2', '', pmNormal, Log.CreateNewAttributes, Folder1);

  // The following messages will be posted to Folder 1,
  // because Folder 2 was not activated
  Log.Message('Message C');
  Log.Message('Message D');

  // Activates Folder2 and posts messages to it
  Log.PushLogFolder(Folder2);
  Log.Message('Message E');

  // Restores the active folder (Folder1) and posts messages to it
  Log.PopLogFolder;
  Log.Message('Message F');
end;

C++Script, C#Script

function Test()
{
  var Folder1, Folder2;

  Log["Message"]("Message A");

  // Creates a folder and activates it
  Folder1 = Log["CreateFolder"]("Folder1");
  Log["PushLogFolder"](Folder1);

  // Posts messages to the new folder
  Log["Message"]("Message B");

  // Creates one more folder
  Folder2 = Log["CreateFolder"]("Folder 2", "", pmNormal, Log.CreateNewAttributes(), Folder1);

  // The following messages will be posted to Folder 1,
  // because Folder 2 was not activated
  Log["Message"]("Message C");
  Log["Message"]("Message D");

  // Activates Folder2 and posts messages to it
  Log["PushLogFolder"](Folder2);
  Log["Message"]("Message E");

  // Restores the active folder (Folder1) and posts messages to it
  Log["PopLogFolder"]();
  Log["Message"]("Message F");
}

After this code is executed, you will get the following hierarchy of messages:

Message A
Folder 1
  Message B
  Folder 2
    Message E
  Message C // These messages are not included in Folder 2,
  Message D // because it was activated after the messages had been posted
  Message F

Working With Folders From Keyword Tests

To create folders in your keyword tests you can use the Append Log Folder operation from the Logging category. This operation creates a folder in the test log and activates the folder so that subsequent operations post messages, files and images to the created folder.

To “close” the currently active folder and transfer the log messages to its parent folder, use the Pop Log Folder operation.

The following figure demonstrates how you can use the Append Log Folder and Pop Log Folder operations to create a three-level hierarchy of messages in the log:

Log folders hierarchy

Click the image to enlarge it.

After you execute this test, the test run’s log will be the same as the log in the picture.

Log folders hierarchy

Click the image to enlarge it.

The Append Log Folder operation also returns an integer identifier of the created folder, so your tests can post the messages to the folder after another folder is active. The entire procedure includes the following steps:

  • Add the Append Log Folder to your keyword test to create and activate a new folder.

  • Save the operation’s result to a variable. To do this, add the Set Variable Value operation right after the Append Log Folder operation. This operation belongs to the Statements category. TestComplete will display the Operation Parameters wizard.

  • On the first page of the wizard specify the desired variable. Click Next to continue.

  • On the next page, choose Last Operation Result from the Mode drop-down list and click Finish to add the operation to the test.

The test engine will store the folder identifier to the specified variable during the test run. You can then use this variable to specify the value of the FolderID parameter of the Log Message and Post Screenshot operations that are used to post messages and images to the test log. See Specifying Operation Parameters.

A possible alternative to the Append Log Folder and Pop Log Folder operations is to use the Call Object Method or Run Code Snippet operations to call the CreateFolder, AppendFolder, PushLogFolder and PopLogFolder methods of the Log object from your keyword tests (for information on using the methods, see above).

Using the Call Object Method operation is simple:

  • Add the operation to your keyword test. TestComplete will display the Operation Parameters wizard.

  • On the first page of the wizard, type Log to specify the object, whose method will be called, and press Next.

  • On the next page, choose the method to be called: CreateFolder, AppendFolder, PushLogFolder or PopLogFolder. Press Next to continue.

  • On the next page specify the method’s parameters and click Finish to add the operation to the test.

To post a message with the Run Code Snippet operation, add this operation to the test and then type the script code that calls the desired method, into the Operation Parameters wizard.

See Also

Posting Messages, Images and Files to the Log
CreateFolder Method
AppendFolder Method
PushLogFolder Method
PopLogFolder Method
Append Log Folder Operation
Pop Log Folder Operation
Call Object Method Operation
Run Code Snippet Operation

Highlight search results