Using Folders

Working With Log Folders From Scripts

Working With Folders From Keyword Tests

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:

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

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

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:

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.

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.