mte

Provides the Multi-threaded Execution (MTE) framework for automated test orchestration in Total Control.

The mte module enables parallel and configurable execution of test scripts across one or more Android devices,
leveraging .tpf configuration files and JavaScript-based test cases. It is ideal for scenarios such as regression testing,
multi-device validation, and scalable automation.

Core Features:

Create and manage test runs via the Testrun class.
Parallel execution across multiple devices (runDTest) or configuration variants (runCTest).
Real-time test state tracking, including messages, status, and device binding.
Static control interfaces for external status updates, result queries, and test termination.
Dynamic test data injection through .tpf config files or external data payloads.

Usage Overview:

Prepare a .tpf file with test sections (Testname, device, username, etc.).
Write a test script (.js) that accesses parameters via Testrun.getContext().
Instantiate a Testrun, or call runDTest / runCTest for concurrent execution.
Monitor status via .getStatus() or Testrun.getStatus(name), and control execution via .stop() or Testrun.stop(name).

Execution APIs:

new Testrun(name, configFile, scriptFile, configName[, data[, extConfig[], autoStart]]): Single test execution.
runDTest(name, configFile, scriptFile, configName, devices[]): Same script/config run across multiple devices.
runCTest(name, configFile, scriptFile, baseConfig, configs[]): Same script run with multiple config variants.

Classes

Testrun

getContext(idopt) → {object}

Get the runtime context object of the specified test run.
This static method allows access to configuration parameters loaded from .tpf
for a given Testrun, outside the test script itself.

Example

// With MTE, different apps can be launched on different devices based on config.
// 'mte.tpf' configuration content:

Testname weixin
deviceSN:'CUIVAEPR99999999'
appname:'com.tencent.mm'
username:'14016031'
password:'password001'
End

Testname qq
deviceSN:'KVSGFELFE6AY7LYL'
appname:'com.tencent.mobileqq'
username:'45178763'
password:'password002'
End

// Example script: 'mtesample.js'
define("requireVersion","1.5.0.2865");
define("version","6.5.0.2886");
define("verbose",0);
define("resolution","1080*1920");

print("RUN TEST BEGIN ...");
var { Testrun } = require('./mte');
print("Device SN is: " + Testrun.getContext().get("deviceSN"));
print("APP to be started: " + Testrun.getContext().get("appname"));
print("Username is: " + Testrun.getContext().get("username"));
print("Password is: " + Testrun.getContext().get("password"));

var device = Device.searchObject(tcConst.DevSerial, Testrun.getContext().get("deviceSN"));
if (!device) {
  print(lastError());
} else {
  device.runApp(Testrun.getContext().get("appname"));
}

print("RUN TEST END!");

// Caller usage example:
var { Testrun } = require('./mte');

// Start test for the 'weixin' config section in mte.tpf
var testrunObj1 = new Testrun('Hello', 'mte.tpf', 'mtesample.js', 'weixin');
// Will launch WeChat on the phone with SN 'CUIVAEPR99999999'

// Start test for the 'qq' config section in mte.tpf
var testrunObj2 = new Testrun('Hello2', 'mte.tpf', 'mtesample.js', 'qq');
// Will launch QQ on the phone with SN 'KVSGFELFE6AY7LYL'

Parameters:

string \| number	`id`	<optional>	The test run ID. If not provided, uses the latest Testrun ID.

Returns:

object

Returns the context object (configuration data) of the specified test run.

getDevice(idopt) → {Device|null}

Retrieves the device object associated with a specific Testrun execution.

This static method returns the execution device assigned in the .tpf configuration file
for a running or completed Testrun. It can be used outside the script to query the target device’s properties,
such as its serial number (SN).

Example

// The configuration file 'facebook.tpf':

 Testname login
 device:'MOBILE-01'
 username:'tester001'
 password:'abc123'
 info:'Login test user'
 End

// The test script 'Testenv.js':
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require('./mte');
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get("device"));
print("Device username is: " + Testrun.getContext().get("username"));
print("Device password is: " + Testrun.getContext().get("password"));
print("Device message is: " + Testrun.getContext().get("info"));
print("RUN TEST END!");

// Caller example using static getDevice():
var { Testrun } = require('./mte');

let testrunObj;
try {
  testrunObj = new Testrun("Hello", "facebook.tpf", "Testenv.js", "login");
} catch (e) {
  print("Error: " + e);
  print(lastError());
}

// Read runtime parameters via getContext()
print("Device name is: " + testrunObj.getContext().get("device"));
print("Device username is: " + testrunObj.getContext().get("username"));

// Retrieve device object from the static method
var device = Testrun.getDevice();
if (device) {
  print("Device SN is: " + device.SN);
}

Parameters:

string \| number	`id`	<optional>	The ID of the Testrun. If not provided, returns the device from the most recently executed Testrun.

Returns:

Device | null

A Device object associated with the specified Testrun, or null if not found.

getMessage(name) → {string}

Retrieves the status or custom message of a Testrun instance by its name.

This is a static method used to get the status message for a previously created
Testrun by name. Internally it calls Testrun.getStatus(name).

The returned message typically reflects the current state, such as:
"1:Running", "0:Stopped", or a custom string set using setStatus() or setMessage().

Example

// Example configuration file: facebook.tpf

 Testname login
 device:'MOBILE-01'
 username:'tester001'
 password:'abc123'
 info:'Login test user'
 End

// Example script file: Testenv.js
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require('./mte');
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get("device"));
print("Device username is: " + Testrun.getContext().get("username"));
print("Device password is: " + Testrun.getContext().get("password"));
print("Device message is: " + Testrun.getContext().get("info"));
print("RUN TEST END!");


// Example
// Usage in controller script
var { Testrun } = require('./mte');

let testrunObj;
try {
  testrunObj = new Testrun("Hello", "facebook.tpf", "Testenv.js", "login");
} catch (e) {
  print("Error: " + e);
  print(lastError());
}

// Query message by test name
var msg = Testrun.getMessage("Hello");
print("Testrun message: " + msg);  // Example output: "1:Running" or "Login started"

Parameters:

string	`name`	The name of the Testrun instance.

Returns:

string

The current message or status of the test run.

getStatus(name) → {string}

Get the status message of a specific Testrun instance by its name.

This static method is used to query the current execution status of a Testrun
that was created and started earlier. It is commonly used in multi-threaded or
batch testing scenarios where Testrun objects are tracked by name.

If the Testrun instance is found, it returns a string such as "1:Running",
"0:Stopped" or a custom message set by Testrun.setStatus() or Testrun.setMessage().
If not found, it returns an error message like "No Testrun is called Hello".

Example

// Sample .tpf config file (facebook.tpf):

Testname login
device:'MOBILE-01'
username:'tester001'
password:'abc123'
info:'Login test user'
End

// Sample test script (Testenv.js):
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require('./mte');
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get("device"));
print("Device username is: " + Testrun.getContext().get("username"));
print("Device password is: " + Testrun.getContext().get("password"));
print("Device message is: " + Testrun.getContext().get("info"));
print("RUN TEST END!");


// Example
// Usage in controller script
var { Testrun } = require('./mte');

let testrunObj;
try {
  testrunObj = new Testrun("Hello", "facebook.tpf", "Testenv.js", "login");
} catch (e) {
  print("Error: " + e);
  print(lastError());
}

// Query the status of the Testrun by name
var status = Testrun.getStatus("Hello");
print("Current status: " + status);  // Example: "1:Running" or "0:Stopped"

Parameters:

string	`name`	The name of the Testrun instance to query.

Returns:

string

The current status message of the specified Testrun.

setMessage(name, msg)

Set the message string for a running Testrun by name.

This static method functions the same as Testrun.setStatus() and is typically used to record
user-defined test status, custom messages, or intermediate results. The value is stored inside
the Testrun object and can be retrieved via Testrun.getMessage(name) or
testrunObj.getMessage().

Example

// Sample .tpf file: 'facebook.tpf'
//
// Testname login
// device:'MOBILE-01'
// username:'tester001'
// password:'abc123'
// info:'Login test user'
// End

// Test script: 'Testenv.js'
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require('./mte');
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get("device"));
print("Device username is: " + Testrun.getContext().get("username"));
print("Device password is: " + Testrun.getContext().get("password"));
print("Device message is: " + Testrun.getContext().get("info"));
print("RUN TEST END!");


//Example
var { Testrun } = require('./mte');

// In main controller script:
let testrunObj;
try {
  testrunObj = new Testrun("Hello", "facebook.tpf", "Testenv.js", "login");
} catch (e) {
  print("Error: " + e);
  print(lastError());
}

// Set a message externally
Testrun.setMessage("Hello", "bbbbbbbbbbbbb");

// Retrieve it later
print("Message: " + Testrun.getMessage("Hello"));  // Output: bbbbbbbbbbbbb

Parameters:

string	`name`	The name of the Testrun instance.
string	`msg`	The custom message to store (e.g., `"step-3 passed"`, `"login failed"`).

setStatus(name, message)

Set the current status string for a running Testrun by name.

This static method is used to assign a custom status message to a specific Testrun instance
identified by its name. The updated status can be later retrieved via Testrun.getStatus(name)
or testrunObj.getStatus() if you hold the object reference.

Note: that all non-object interfaces must be executed in the called js script.

Example

// Sample configuration file: 'facebook.tpf'

Testname login
device:'MOBILE-01'
username:'tester001'
password:'abc123'
info:'Login test user'
End

// Sample test script: 'Testenv.js'
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require('./mte');
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get("device"));
print("Device username is: " + Testrun.getContext().get("username"));
print("Device password is: " + Testrun.getContext().get("password"));
print("Device message is: " + Testrun.getContext().get("info"));
print("RUN TEST END!");


//Example
var { Testrun } = require('./mte');
// In the controller script, start a Testrun and assign a status
let testrunObj;
try {
  testrunObj = new Testrun("Hello", "facebook.tpf", "Testenv.js", "login");
} catch (e) {
  print("Error: " + e);
  print(lastError());
}

// Update the status externally using the static API
Testrun.setStatus("Hello", "bbbbbbbbbbbbb");

// Later, retrieve the status:
var status = Testrun.getStatus("Hello");
print("Updated status: " + status); // Output: bbbbbbbbbbbbb

Parameters:

string	`name`	The name of the Testrun instance to update.
string	`message`	The status message to assign (e.g., `"Running"`, `"Passed"`, `"Error code 003"`).

stop(name) → {boolean}

Stops the currently running Testrun by its name.

This static method terminates the test script associated with the provided Testrun name.
If the task is found and stopped successfully, it returns true. If the task is not found
or already stopped, it returns false and logs an error via lastError().

Example

Configuration file: facebook.tpf

Testname login
device:'MOBILE-01'
username:'tester001'
password:'abc123'
info:'Login test'
End

// Script file: Testenv.js
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require('./mte');
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get("device"));
print("Device username is: " + Testrun.getContext().get("username"));
print("Device password is: " + Testrun.getContext().get("password"));
print("Device message is: " + Testrun.getContext().get("info"));
print("RUN TEST END!");

// Example
// Usage in controller script
var { Testrun } = require('./mte');

let testrunObj;
try {
  testrunObj = new Testrun("Hello", "facebook.tpf", "Testenv.js", "login");
} catch (e) {
  print("Error: " + e);
  print(lastError());
}

// Attempt to stop the Testrun by name
Testrun.stop("Hello");  // First stop
print("AAAAAAAA");

// Attempting to stop again (likely already stopped)
Testrun.stop("Hello");  // Will trigger error: "Test Hello is not found!"
print("BBBBBBBBB");

Parameters:

string	`name`	The name of the Testrun instance to stop.

Returns:

boolean

Returns true if the task was successfully stopped, false otherwise.

(inner) runCTest(TestrunName, configFileName, jsScriptFilename, configName, configNameArr) → {Array}

Execute the specified script on a single device in a multi-threaded manner.

The scenario for executing runCTest is as follows:
The user needs to execute the same script with different parameters at the same time.
In this case, the user can configure these parameters in different configNames of the same configuration file. Then put these different configNames in an array. When executing the script, each configName parameter in the array is combined with the corresponding parameter of the second parameter configFileName as a predefined parameter of the script runtime. Please refer to the examples below for details.

Example

var { runCTest } = require("sigma/mte");
var configs = ['login1', 'login2', 'login3'];

// Run test script 'Testenv.js' on each config from 'facebook.tpf' using the base name 'Hello'
var objArr = runCTest('Hello', 'facebook.tpf', 'Testenv.js', 'sendMessage', configs);

// Allow some time for the threads to start
delay(1000);

// Print status of each running test
for (let i = 0; i < objArr.length; i++) {
  print(objArr[i].name + " Status: " + objArr[i].getStatus());
}

// Stop all tests
delay(1000);
for (let i = 0; i < objArr.length; i++) {
  objArr[i].stop();
}

// Check final status after stopping
delay(1000);
for (let i = 0; i < objArr.length; i++) {
  print("Status: " + objArr[i].getStatus());
}

//  When the above statement is executed, three threads will be started simultaneously to execute the "Testenv.js" script. The predefined parameters for each thread are:
'login1' + 'sendMessage'
'login2' + 'sendMessage'
'login3' + 'sendMessage'

// The contents of the 'Testenv.js' script file are as follows:
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require("sigma/mte");
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get('device'));
print("Device username is: " + Testrun.getContext().get('username'));
print("Device password is: " + Testrun.getContext().get('password'));
print("Device message is: " + Testrun.getContext().get('info'));
print("RUN TEST END!");

Parameters:

string	`TestrunName`	Testrun name.
string	`configFileName`	The file name of the tpf configuration parameter file. Relative path, the tpf file must be in the same path as the js file specified by the third parameter.
string	`jsScriptFilename`	The js file to be executed, the relative path, will be found in the user-defined scriptPath, the path corresponding to the environment variable TCSCRIPTPATH, / this computer / document / Scripts / under the script file, if not, lastError () will prompt an error .
string	`configName`	Specify which configuration in the file corresponding to configFileName is used.
Array	`configNameArr`	This parameter specifies an additional configuration to execute the script separately.

Returns:

Array

Multiple Testrun objects are automatically created when runCTest is run. The return value is an array of these objects.

(inner) runDTest(TestrunName, configFileName, jsScriptFilename, configName, deviceArr) → {Array}

Executes the same configuration section of a .tpf file across multiple devices in parallel.

Each device in the provided devices array will run the same test script (.js) using the same configuration name from the .tpf file.
This function is useful when performing multi-device testing using a consistent configuration on each device.

Example

// Get all connected devices
var devices = Device.searchObject(tcConst.DevAll);

var { runDTest } = require("sigma/mte");
// Run the test script 'Testenv.js' on all devices using the 'login' configuration section from 'facebook.tpf'
var objArr = runDTest('Hello', 'facebook.tpf', 'Testenv.js', 'login', devices);

// Wait briefly for threads to start
delay(1000);

// Print the serial number of each tested device
for (let i = 0; i < objArr.length; i++) {
  print("Device SN is: " + objArr[i].getDevice().SN);
}

// Sample 'Testenv.js':
define("requireVersion", "1.5.0.2865");
define("version", "6.5.0.2886");
define("verbose", 0);
define("resolution", "1080*1920");

var { Testrun } = require("sigma/mte");
print("RUN TEST BEGIN ...");
print("Device name is: " + Testrun.getContext().get('device'));
print("Device username is: " + Testrun.getContext().get('username'));
print("Device password is: " + Testrun.getContext().get('password'));
print("Device message is: " + Testrun.getContext().get('info'));
print("RUN TEST END!");

Parameters:

string	`TestrunName`	The base name for each Testrun instance. A unique suffix will be added automatically.
string	`configFileName`	The `.tpf` configuration file name.
string	`jsScriptFilename`	The test script `.js` file to execute.
string	`configName`	The configuration section name in the `.tpf` file to be used for each device.
Array	`deviceArr`	An array of `Device` objects returned by `Device.searchObject(...)`.

Returns:

Array

Returns an array of Testrun objects, one per device.

Core Features:

Usage Overview:

Execution APIs:

Functions

Classes

getContext(idopt) → {object}

Example

Parameters:

Returns:

getDevice(idopt) → {Device|null}

Example

Parameters:

Returns:

getMessage(name) → {string}

Example

Parameters:

Returns:

getStatus(name) → {string}

Example

Parameters:

Returns:

setMessage(name, msg)

Example

Parameters:

setStatus(name, message)

Example

Parameters:

stop(name) → {boolean}

Example

Parameters:

Returns:

(inner) runCTest(TestrunName, configFileName, jsScriptFilename, configName, configNameArr) → {Array}

Example

Parameters:

Returns:

(inner) runDTest(TestrunName, configFileName, jsScriptFilename, configName, deviceArr) → {Array}

Example

Parameters:

Returns: