Critical Sections

Applies to TestComplete 15.62, last modified on March 19, 2024
The Network Suite functionality is deprecated. We don’t recommend using it for distributed testing. Consider using a CI/CD system for managing distributed tests. See Migrating Distributed Tests to CI/CD Systems for details. In case you need to run web tests on multiple environments in parallel, you can also try using your project’s Execution Plan.

This topic explains how to use critical section to synchronize projects that participate in distributed testing.

What Are Critical Sections?

Often when performing distributed testing, more than one test project uses the same resource simultaneously. For instance, a project that modifies records in a database can be run on several computers at the same time. However, sometimes this is not a good practice (if several projects write to the same file, this may cause loss of results or other unexpected and undesired behavior). To avoid shared access violations, you can restrict other projects’ access to an important resource while the current project uses it.

In TestComplete, when a project needs exclusive access to a resource, its keyword test or script should enter a critical section. A critical section is a specific marked part of a test which can only be performed by one project at a time. That is, while a project’s test works within the critical section, the resources (files, objects, programs, etc.) it works with are accessible to it alone. Other projects that need these resources (actually their keyword tests or scripts that requested the same critical section) will have to wait until this project leaves the given critical section.

Using Critical Sections

The first project that enters a critical section will get access to it. The state of this project changes to Running in CS: Section_Name (where Section_Name is the name of the corresponding critical section). The other projects that try to enter the same critical section are put in a queue in the order they requested this critical section. Their state changes to Waiting for CS: Section_Name. You can check the project state on the Run State page or from tests by using the Task.State property.

When the exclusive access is no longer needed, the project should leave the critical section. Now, other projects will be able to access this critical section. The first project in the queue will get access to it. If there are no projects in the queue, access to the critical section will be granted to the first project that requests it.

You can specify how long each project should wait for access to the requested critical section. This way you can break critical section requests by timeout.

You can use critical sections to synchronize the changes of different critical resources (such as project and project suite variables, files, databases, etc.) between several projects. One of the most typical uses of critical sections in TestComplete is solving conflicts between different projects that may simultaneously try to change values of the same network suite variables. To avoid these conflicts, you can simply put test operations that set the values of these variables within a critical section. This way you prevent other projects from changing the variables when one project is already working with them.

Below is a description of how you can create critical sections in scripts and keyword tests.

In Scripts

To create critical sections in script tests, use the EnterCriticalSection and LeaveCriticalSection methods of the NetworkSuite program object:

NetworkSuite.EnterCriticalSection("CriticalSectionName")
...
NetworkSuite.LeaveCriticalSection("CriticalSectionName")

The EnterCriticalSection method is used to enter a critical section. To make a project leave a critical section, use the LeaveCriticalSection method. When calling these methods, you need to specify the unique name of the critical section you want to enter or leave it as the methods’ parameters. Note that you must use the same name of the critical section in each project.

The following example demonstrates how you can create a critical section in scripts. In this code, the value of the FilesCount network suite variable is changed within the ChangeVar critical section.

JavaScript, JScript

// Occupy a critical section
NetworkSuite.EnterCriticalSection("ChangeVar");

// Changing the value of the network suite variable within a critical section
NetworkSuite.Variables.FilesCount = NetworkSuite.Variables.FilesCount + 1;

// Release the critical section
NetworkSuite.LeaveCriticalSection("ChangeVar");

Python

# Occupy a critical section
NetworkSuite.EnterCriticalSection("ChangeVar")

# Changing the value of the network suite variable within a critical section
NetworkSuite.Variables.FilesCount = NetworkSuite.Variables.FilesCount + 1

# Release the critical section
NetworkSuite.LeaveCriticalSection("ChangeVar")

VBScript

' Occupy a critical section
NetworkSuite.EnterCriticalSection("ChangeVar")

' Changing the value of the network suite variable within a critical section
NetworkSuite.Variables.FilesCount = NetworkSuite.Variables.FilesCount + 1

' Release the critical section
NetworkSuite.LeaveCriticalSection("ChangeVar")

DelphiScript

// Occupy a critical section
NetworkSuite.EnterCriticalSection('ChangeVar');

// Changing the value of the network suite variable within a critical section
NetworkSuite.Variables.FilesCount := NetworkSuite.Variables.FilesCount + 1;

// Release the critical section
NetworkSuite.LeaveCriticalSection('ChangeVar');

C++Script, C#Script

// Occupy a critical section
NetworkSuite["EnterCriticalSection"]("ChangeVar");

// Changing the value of the network suite variable within a critical section
NetworkSuite["Variables"]["FilesCount"] = NetworkSuite["Variables"]["FilesCount"] + 1;

// Release the critical section
NetworkSuite["LeaveCriticalSection"]("ChangeVar");

In Keyword Tests

From keyword tests, you can call the NetworkSuite.EnterCriticalSection and NetworkSuite.LeaveCriticalSection methods using the Run Code Snippet or Call Object Method operation. For instance, when using the Run Code Snippet operation, specify the code line that calls the desired method (see above) and click OK. The following image demonstrates how you can call the NetworkSuite.EnterCriticalSection method using the Run Code Snippet operation in a VBScript test project:

To mark a piece of a keyword test as a critical section, simply add the keyword test operations calling the NetworkSuite.EnterCriticalSection and NetworkSuite.LeaveCriticalSection methods to the test, correspondingly before and after a set of keyword test operations to be included into the section. The following image illustrates how to change a value of a keyword test variable within a critical section in keyword tests:

See Also

Synchronizing Projects in Network Suites
Synchronizing Projects - Overview
Distributed Testing
Projects Participating in Distributed Testing

Highlight search results