Qt自动化模块介绍

在CukeTest中，与跨平台Qt相关的自动化对象都位于leanpro.qt模块中。该模块主要包含以下两个类：

1. QtModel：用于加载模型文件，只需将模型文件拖放到代码中即可自动加载。
2. QtAuto：提供与执行Qt自动化相关的库。

QtAuto

对象定义如下：

class QtAuto {
    static defaultTimeout: number;
    static getApplication(appName: string): IQApplication;
    static launchQtProcess(exePath: string | string[], ...args: string[]): ChildProcess;
    static launchQtProcessAsync(exePath: string | string[], ...args: string[]): Promise<ChildProcess> 
    static launchQtProcessAsync(exePaths: string, args: string[], options: SpawnOptions): ChildProcess;
    static winHookProcess(pidOrNameOrProcess: number | string | object): Promise<void>
    static loadModel(modelPath: string): IQtModel;
}

class QtAuto(QtContainer):
	def launchQtProcessAsync(exePaths: Union[str, List[str]]) -> "ChildProcess"
	def winHookProcess(pidOrNameOrProcess: Union[str, int, TypedDict]) -> None
	def loadModel(modelPath: str) -> "QtModel"

从leanpro.qt模块中引用，引用可以写作如下:

const { QtAuto } = require('leanpro.qt');

from leanproAuto import QtAuto

loadModel(modelPath): IQtModel

从模型文件中加载模型，模型中提供了各种控件的自动化API。

• modelPath: string类型，模型文件的路径。
• 返回值: IQtModel类型，模型类，包含了各类Qt对象操作API。

例如从leanpro.qt模块中引用，用于引用可以写作如下:

const { QtAuto } = require('leanpro.qt');
let model = QtAuto.loadModel(__dirname + '/Model1.tmodel');

from leanproAuto import QtAuto
model = QtAuto.loadModel(__dirname + '/Model1.tmodel')

直接将模型文件从CukeTest的文件管理器视图中拖拽到代码编辑器中可以自动生成以上模型代码。

QtAuto包含了用于以下几个方面:

Qt自动化的超时时间

在Qt自动化中，每个操作都有一个超时时间。如果操作的执行时间超过了设定的超时时间，将会触发错误，存在以下几种情况：

1. 当操作执行时间超过超时时间时，将会报超时错误。
2. 如果在超时时间内，控件没有变为可见状态，将会报"对象未找到"的错误。

Qt对象操作的默认超时时间为5秒。也可以通过以下属性进行设置：

defaultTimeout: number

该属性获取当前的超时时间设置，单位为毫秒（ms）。默认值为5000（即5秒）。你也可以将其赋予一个新值，以修改所有Qt操作的超时时间。例如，将其设置为10000将会使得任何Qt操作运行超过10秒才会抛出错误。

操作Qt应用

用于启动Qt应用，以及获取Qt应用的信息。

launchQtProcessAsync(exePath, args, options): Promise<ChildProcess>

使用高级选项启动一个Qt应用，通常用于启动被测应用，适合当被测应用对环境变量、工作目录等条件有要求时使用。需要和启动普通应用的launchProcess()方法做区分，因为launchQtProcess()方法会自动加载Qt Agent，而只有加载了Qt Agent才能够执行Qt自动化。

并且支持以字符串数组形式传入多个应用路径，CukeTest会逐个路径尝试直到找到有效路径。可以用于不同平台间被测应用路径不同的情况。

• exePath: string或string[]类型，应用的路径，如果传入字符串数组类型string[]，则会逐个路径尝试直到找到有效路径后启动。
• args: （可选）string[]类型，运行应用时的参数，比如cuketest --runjs test.js这条命令中，后面两个就是参数，写作args传参的形式为["--runjs", "test.js"]。
• options: （可选）QtSpawnOptions类型（扩展自SpawnOptions类型(/windows/win_shared_api.md#spawn-options)），控制进程运行的更多参数，为一个对象，可以在里面指定环境变量、工作目录等选项。
  • cwd: string类型，子进程的工作目录，默认值为运行的项目目录，即process.cwd()的值。
  • env: Object类型。环境键值对。默认值：process.env，即CukeTest运行时的环境变量。
  • detached boolean类型。子进程独立于其父进程运行（摆脱父进程控制运行）。
  • shell boolean或string类型。如果为true，则在shell内运行命令。在 Unix 上使用'/bin/sh'，在 Windows 上使用 process.env.ComSpec。可以将不同的 shell 指定为字符串。默认值：false（无shell）。
  • launchTimeout: （仅限Qt启动方法）number类型，准备插件的超时时间，以秒为单位，默认值为：10。

launchQtProcessAsync(exePath, ...args): ChildProcess

启动一个Qt应用，通常用于启动被测应用。等待进程加载好Qt Agent后再返回。

并且支持以字符串数组形式传入多个应用路径，CukeTest会逐个路径尝试直到找到有效路径。可以用于不同平台间被测应用路径不同的情况。

• exePath: string或string[]类型，应用的路径，如果传入字符串数组类型string[]，则会逐个路径尝试直到找到有效路径后启动。
• args: （可选）...string[]类型，运行应用时的参数，比如cuketest --runjs test.js这条命令中，后面两个就是参数，写作args传参的形式为launchQtProcessAsync(exePath,"--runjs", "test.js")。

launchQtProcess(exePath, ...args): ChildProcess

启动一个Qt应用，通常用于启动被测应用。相比于launchQtProcessAsync()，这个启动方法并不会等待进程加载好Qt Agent后再返回（因为是同步方法），因此对于Qt自动化来说并不是安全方法，不推荐使用。

并且支持以字符串数组形式传入多个应用路径，CukeTest会逐个路径尝试直到找到有效路径。可以用于不同平台间被测应用路径不同的情况。

• exePath: string或string[]类型，应用的路径，如果传入字符串数组类型string[]，则会逐个路径尝试直到找到有效路径后启动。
• args: （可选）string[]类型，运行应用时的参数，比如cuketest --runjs test.js这条命令中，后面两个就是参数，写作args传参的形式为launchQtProcess(exePath,"--runjs", "test.js")。

getApplication(appName): IQApplication

获取目标应用的自动化对象，可以用于自动化操作。

• appName: string类型，Qt应用的名称。

winHookProcess(pidOrNameOrProcess): Promise<void>

用于在Windows平台下的已打开Qt应用中加载Qt Agent。在Linux和Mac平台下，该方法为空操作。

当自动化脚本运行时，如果Qt应用已经打开，或者Qt应用不是由自动化脚本直接启动的情况下，需要调用winHookProcess来加载Qt Agent。

该方法的使用方式如下：

await QtAuto.winHookProcess(pidOrNameOrProcess);

QtAuto.winHookProcess(pidOrNameOrProcess);

• pidOrNameOrProcess: 可以是number 、 string 或 ChildProcess类型
  1. 如果是number类型，表示Qt应用的进程ID（PID）。
  2. 如果是string类型，表示进程的可执行文件名，如"fetchmore.exe"。
  3. 也可以是ChildProcess对象，例如由Util.launchProcess返回的对象。

下面是一个简单示例：

const aut = Util.launchProcess("C:/Program Files/LeanPro/CukeTest/bin/standarddialogs.exe");
await Util.delay(3000);
await QtAuto.winHookProcess(aut); // 1. 可以传入进程对象
await QtAuto.winHookProcess("standarddialogs.exe"); // 2. 可以传入进程名
await modelQt.getApplication("standarddialogs").exists(10);

Util.launchProcess("C:/Program Files/LeanPro/CukeTest/bin/standarddialogs.exe")
Util.delay(3000)
QtAuto.winHookProcess("standarddialogs.exe")
modelQt.getApplication("standarddialogs").exists(10)

通过上述用法，你可以在Windows平台下使用QtAuto.winHookProcess()方法加载Qt Agent，以实现自动化脚本对已打开的Qt应用的操作。