Util（常用工具函数）

提供在自动化脚本中常用的工具函数。可以通过引入leanpro.common中的Util对象来使用这些工具函数：

const { Util } = require('leanpro.common');

from leanproAuto import Util

Util提供以下方法：

以下是Util类的定义：

class Util {
    static delay(milliseconds: number): Promise<void>;
    static launchProcess(exePath: string, ...args: string[]): ChildProcess; 
    static launchProcess(exePaths: string, args: string[], options?: SpawnOptions): ChildProcess;
    static stopProcess(proc: ChildProcess): boolean;
    static loadPlugin(proc: ChildProcess | number | string, plugins: string | string[]): Promise<void>;
    static takeScreenshot(filePath: string = null, monitor: number = 0): string | void;
    static loadCsvFile(filePath: string): Promise<RowCsv[]>;
    static saveToCsvFile(rows: RowCsv[], filePath: string): boolean;
    static getClipboard(): Promise<string>;
    static setClipboard(text: string): Promise<void>;
    static copyDir(source: string, target: string): Promise<void>;
    static runJavaScript(source: string): Promise<any>;
    static runPython(source: string, options?: object): Promise<any>;
}

class Util:
    def copyDir(source: str, target: str) -> None
    def delay(milliseconds: int) -> None
    def launchProcess(exePath: str, *args: List[str]) -> "ChildProcess"
    def stopProcess(proc: ChildProcess) -> bool
    def loadPlugin(pidOrName: Union[str, int], plugins: Union[str, List[str]]) -> None
    def getClipboard() -> str
    def setClipboard(text: str) -> None
    def reportStep(stepTitle: str) -> None
    def runJavaScript(source: str) -> Any
    def runPython(source: str, *options: Optional[Dict]) -> Any

常用方法和示例

delay(milliseconds): Promise<void>

延时等待一段时间。参数为等待的毫秒数。

• milliseconds: number类型，等待时间，单位为毫秒。
• 返回值: 不返回任何值的异步方法。

示例：

下面的代码打开计算器应用，等待一秒后，确保它初始化成功后，开始点击操作。

async function run() {
    let calcPath = 'c:/windows/system32/calc.exe';
    await Util.launchProcess(calcPath);
    await Util.delay(1000); // 等待进程初始化
    await model.getButton("Two").click();
}

run();

def run():
    calcPath = 'c:/windows/system32/calc.exe'
    Util.launchProcess(calcPath)
    Util.delay(1000) # 等待进程初始化
    model.getButton("Two").click()

run()

launchProcess(exePath: string, ...args: string[]): ChildProcess;

启动一个进程，通常用来启动被测应用。第一个参数为目标应用的路径。如果在Windows系统中使用，注意路径中的反斜杠需要转义（将\改为\\）。

• exePath: string类型，可执行文件的路径，通常以.exe结尾。如果在Windows系统中使用，注意路径中的反斜杠需要转义。
• args: （可选）string[]类型，启动进程时使用的参数，用法类似child_process.spawn()。
• 返回值: ChildProcess类型的对象，用于记录启动的进程信息，之后可以用于stopProcess()方法关闭进程。更多关于ChildProcess类的说明可以查看child_process类。

launchProcess(exePaths: string, args?: string[], options?: SpawnOptions): ChildProcess;

使用高级选项启动进程，当被测应用对环境变量、工作目录等条件有要求时，可以使用该方法代替上面的调用。

• exePaths: string类型，可执行文件的路径，通常以.exe结尾。
• args: （可选）string[]类型，启动进程时使用的参数，用法类似child_process.spawn()。

• options: （可选）SpawnOptions类型，控制进程运行的更多参数，例如环境变量、工作目录等。

  • 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）。

• 返回值: ChildProcess类型的对象，用于记录启动的进程信息，之后可以用于stopProcess()方法关闭进程。更多关于ChildProcess类的说明可以查看child_process类。

stopProcess(proc: ChildProcess): boolean;

停止某个进程。将launchProcess()方法的返回值传递给proc，可停止该进程。

• proc: ChildProcess类型，进程信息，通常由launchProcess()方法返回，无法直接创建对象。
• 返回值: boolean类型，执行结果。如果停止进程成功，返回true；否则返回false。

示例：

async function run() {
    let notepadPath = 'c:/windows/notepad.exe';
    let proc = await Util.launchProcess(notepadPath);
    // 执行一些其他操作...
    Util.stopProcess(proc);
}

run();

def run():
    notepadPath = 'c:/windows/notepad.exe'
    proc = Util.launchProcess(notepadPath)
    # 执行一些其他操作...
    Util.stopProcess(proc)

run()

注意：有些应用是多进程的。界面端窗体是由主进程打开的。这种情况下，停止主进程不会关闭应用程序界面。Windows 10中的计算器应用即属于这种情况。

loadPlugin(pidOrNameOrProcess: ChildProcess | number | string, plugins: string | string[]): Promise<void>

用于向已启动的应用加载插件。某些自动化操作要求被测应用必须加载插件（例如，Qt自动化需要加载qt插件）。如果通过CukeTest启动应用，系统会根据当前的自动化类型自动加载所需插件。

在以下特殊情况下，可能需要手动加载插件：

• 应用重启：重启后的应用将不带任何插件。
• 启动被测应用时插件加载失败：由于被测应用的启动方式各不相同，插件加载可能失败。在多次自动重试后仍未成功时，可以手动加载插件。

用法：

• pidOrNameOrProcess: 支持三种类型：ChildProcess（Util.launchProcess()方法返回值）、number（进程号PID）、string（进程名）。
• plugins: string或string[]，插件名称或插件名称数组。插件列表可在启动应用对话框中查看。
• 返回值：不返回任何值的异步方法，请使用await。

示例：

let proc = Util.launchProcess("/your/qt/app/path");
await Util.loadPlugin(proc, 'qt');

proc = Util.launchProcess("/your/qt/app/path")
Util.loadPlugin(proc.pid, 'qt')

如果需要在已运行的Windows应用中使用Text识别技术，也可以通过loadPlugin()来加载guitext插件，如下：

let proc = Util.launchProcess("/your/qt/app/path");
await Util.loadPlugin(proc, 'guitext');

proc = Util.launchProcess("/your/qt/app/path")
Util.loadPlugin(proc.pid, 'guitext')

copyDir(source: string, target: string): Promise<void>

将源文件夹的内容复制到目标文件夹中，如果目标文件夹不存在，则会自动创建该目录。

• source: string类型，要复制的源文件夹路径。
• target: string类型，目标文件夹路径。

示例：

const { Util } = require('leanpro.common');

(async () => {
    const sourceDir = './model_files';
    const destDir = './test/model_copy_files';
    await Util.copyDir(sourceDir, destDir);
})();

from leanproAuto import Util

sourceDir = './model_files'
destDir = './test/model_copy_files'
Util.copyDir(sourceDir, destDir)

takeScreenshot(filePath: string = null, monitor: number = 0): string

截取整个屏幕图片，以png格式保存，并返回截图的base64编码。可以直接作为运行报告的报告附件。

• filePath：文件路径，应以.png后缀结尾。如果filePath为null，返回图片的base64编码。
• monitor：截取屏幕的编号，0表示所有显示器，1表示第一个显示器，默认值为0。
• 返回值: string类型，截图的base64编码。

旧版的截屏方法，现在建议使用Screen对象的capture()和captureToFile()方法，详见屏幕自动化对象。

loadCsvFile(filePath: string): Promise<RowCsv[]>

读取CSV文件并返回JSON对象数组，每个对象的key是列名，value是数据。

• filePath: string类型，要读取的CSV文件路径。
• 返回值: RowCsv类型，JSON对象的数组。

示例：假设有一个内容如下的data.csv文件：

first_name,last_name,company_name,state,zip
James,Butt,"Benton, John B Jr",LA,70116
Josephine,Darakjy,"Chanay, Jeffrey A Esq",MI,48116
Art,Venere,"Chemel, James L Cpa",NJ,8014

使用以下代码读取：

(async function() {
    let data = await Util.loadCsvFile('C:\\temp\\data.csv');
    console.log(data);
})();

会返回如下的JSON：

[
  { "first_name": "James", "last_name": "Butt", "company_name": "Benton, John B Jr", "state": "LA", "zip": "70116" },
  { "first_name": "Josephine", "last_name": "Darakjy", "company_name": "Chanay, Jeffrey A Esq", "state": "MI", "zip": "48116" },
  { "first_name": "Art", "last_name": "Venere", "company_name": "Chemel, James L Cpa", "state": "NJ", "zip": "8014" }
]

saveToCsvFile(rows: RowCsv[], filePath: string): boolean;

将JSON格式的数据保存为CSV文件。

• rows: RowCsv[]类型，行数据，每个对象的key为列名，value为单元格中的内容。
• filePath: string类型，保存的路径和文件名。

示例：将从上一步data.csv文件中读取的数据保存为data_bak.csv文件：

(async function() {
    let data = await Util.loadCsvFile('C:\\temp\\data.csv');
    Util.saveToCsvFile(data, "./data_bak.csv");
})();

运行结束后可以在根目录下看到新生成的data_bak.csv文件，内容与data.csv文件一致。

runJavaScript(source: string): Promise<any>

运行自定义JavaScript代码并返回执行结果。

• source: string类型，要执行的JavaScript代码。
• 返回值: any类型，异步返回执行结果。

示例：

let jsResult = await Util.runJavaScript('1 + 1');
assert.equal(jsResult, 2);

jsResult = Util.runJavaScript('1+1')
assert jsResult == 2

runPython(source: string, options?: object): Promise<any>

运行自定义Python代码并返回执行结果。

• source: string类型，要执行的Python代码。
• options: object类型，可选参数。
• 返回值: any类型，异步返回执行结果。

示例：

let pyResult = await Util.runPython('print("Hello World!")');
assert.equal(pyResult.replace("\r\n", ""), "Hello World!");

pyResult = Util.runPython('print("Hello World!")')
assert pyResult.replace("\r\n", "") == "Hello World!"

剪贴板操作

以下是两个方法——读取和设置剪贴板的内容。

getClipboard(): Promise<string>

获取当前剪贴板中的内容。

• 返回值: string，异步返回剪贴板中的文本。

setClipboard(text: string): Promise<void>

设置当前剪贴板中的内容。

• text: string，要写入剪贴板的文本。
• 返回值: 不返回任何值的异步方法。

示例：

(async function() {
    await Util.setClipboard('(🦄)');
    let text = await Util.getClipboard();
    console.log(text);
})();

Util.setClipboard('(🦄)')
text = Util.getClipboard()
print(text)