Util（常用工具函数）

Util 是一个包含各种常用工具函数的对象，它能帮助我们在自动化脚本中完成一些常见的操作。比如，它可以用来等待一段时间、启动或关闭进程、操作剪贴板，或者处理文件等。

你可以通过以下方式引入 Util 对象：

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

from leanproAuto import 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

API介绍

delay(milliseconds)

等待指定的时间后继续执行。

参数:

• milliseconds: number类型，表示需要等待的时间（毫秒）。

返回值:

• 不返回任何值。

使用示例:

// 等待1秒后执行下一步
await Util.delay(1000);

# 等待1秒后执行下一步
Util.delay(1000)

launchProcess(exePath, args, options)

启动指定的可执行文件，可选地传递参数和启动选项。

参数:

• exePath: string类型，可执行文件的路径。
• 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类。

使用示例:

// 启动计算器
await Util.launchProcess('C:/Windows/System32/calc.exe');

// 启动记事本并打开指定文件
await Util.launchProcess('C:/Windows/System32/notepad.exe', ['C:/path/to/your/file.txt']);

// 启动自定义应用程序并设置工作目录
await Util.launchProcess('C:/path/to/your/app.exe', [], { cwd: 'C:/path/to/your/app_directory' });

// 启动应用程序并设置环境变量
await Util.launchProcess('C:/path/to/your/app.exe', [], { env: { MY_ENV_VAR: 'value' } });

// 启动应用程序并在独立的shell中运行
await Util.launchProcess('C:/path/to/your/app.exe', [], { shell: true });

# 启动计算器
Util.launchProcess('C:/Windows/System32/calc.exe')

# 启动记事本并打开指定文件
Util.launchProcess('C:/Windows/System32/notepad.exe', ['C:/path/to/your/file.txt'])

# 启动自定义应用程序并设置工作目录
Util.launchProcess('C:/path/to/your/app.exe', [], { 'cwd': 'C:/path/to/your/app_directory' })

# 启动应用程序并设置环境变量
Util.launchProcess('C:/path/to/your/app.exe', [], { 'env': { 'MY_ENV_VAR': 'value' } })

# 启动应用程序并在独立的shell中运行
Util.launchProcess('C:/path/to/your/app.exe', [], { 'shell': True })

stopProcess(proc)

停止指定的子进程。

参数:

• proc: ChildProcess对象，表示要终止的进程，通常由launchProcess()方法返回。

返回值:

• 返回 boolean，表示进程是否成功停止。

使用示例:

const proc = await Util.launchProcess('C:/Windows/System32/calc.exe');
Util.stopProcess(proc);

proc = Util.launchProcess('C:/Windows/System32/calc.exe')
Util.stopProcess(proc)

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

loadPlugin(pidOrNameOrProcess, plugins)

向指定的进程加载插件。某些自动化操作需要被测应用加载特定的插件才能正常工作（例如，Qt自动化需要加载qt插件）。如果你是通过CukeTest启动应用的，工具会根据当前的自动化类型自动加载所需的插件。

但在某些特殊情况下，你可能需要手动加载插件：

• 应用自动重启：如果应用在运行过程中自动重启，重启后的应用可能不会加载任何插件。
• 插件加载失败：由于被测应用的启动方式不同，插件可能会加载失败。如果CukeTest多次尝试自动加载插件仍未成功，你可以手动加载插件。

参数:

• pidOrNameOrProcess: 支持三种类型：
  • ChildProcess：通过Util.launchProcess()方法启动应用后返回的对象。
  • number：进程的PID（进程号）。如果目标进程可能有多个实例，建议使用PID来确保插件加载到正确的进程。
  • string：进程的名称。
• plugins: string | string[]类型，需要加载的插件名称。插件列表可在启动应用对话框中查看。

返回值:

• 不返回任何值。

使用示例:

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

// 启动一个Windows应用程序（例如拨号器）
let proc = Util.launchProcess("C:/Windows/System32/dialer.exe");

// 方式1：通过ChildProcess对象加载插件
await Util.loadPlugin(proc, 'guitext');

// 方式2：通过进程名称加载插件
await Util.loadPlugin("dialer.exe", 'guitext');

// 方式3：通过进程PID加载插件（假设PID为42532）
await Util.loadPlugin(42532, 'guitext');

# 启动一个Windows应用程序（例如拨号器）
proc = Util.launchProcess("C:/Windows/System32/dialer.exe")

# 方式1：通过ChildProcess对象加载插件
Util.loadPlugin(proc, 'guitext')

# 方式2：通过进程名称加载插件
Util.loadPlugin("dialer.exe", 'guitext')

# 方式3：通过进程PID加载插件（假设PID为42532）
Util.loadPlugin(42532, 'guitext')

takeScreenshot(filePath, monitor)

已过时：建议使用Screen对象的capture()和captureToFile()方法替代。

截取屏幕截图，保存为PNG文件并返回Base64编码的字符串。截图可直接作为图片插入到测试报告中，用法请参考报告附件。

参数:

• filePath: （可选）string类型，保存截图的路径，应以.png后缀结尾。
• monitor: （可选）number类型，指定需要截图的屏幕编号，0表示所有显示器，1表示第一个显示器，默认值为0。

返回值:

• 返回截图的Base64编码字符串。

loadCsvFile(filePath)

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

参数:

• filePath: string类型，要读取的CSV文件的路径。

返回值:

• 返回 Array<object> 类型，CSV文件中的数据。

使用示例:

假设有一个内容如下的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

使用以下代码读取：

let data = await Util.loadCsvFile('data.csv');
console.log(data);

[
  { "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, filePath)

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

参数:

• rows: Array<object> 类型，需要保存的数据数组。每个对象的key为列名，value为单元格中的内容。
• filePath: string类型，CSV文件的保存路径。

返回值:

• 返回 boolean 表示是否保存成功。

使用示例:

const rows = [{ name: 'Alice', age: 30 }];
await Util.saveToCsvFile(rows, 'data.csv');

copyDir(source, target)

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

参数:

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

返回值:

• 无

使用示例:

await Util.copyDir('source_folder', 'target_folder');

Util.copyDir('source_folder', 'target_folder')

runJavaScript(source)

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

参数:

• source: string类型，JavaScript代码字符串。

返回值:

• 返回 Promise<any>，表示代码的执行结果。

使用示例:

const result = await Util.runJavaScript('2 + 2');
assert.equal(result, 2);

result = Util.runJavaScript('2 + 2')
assert result == 2

runPython(source, options)

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

参数:

• source: string类型，Python代码字符串。
• options: （可选）object，可选的运行参数。

返回值:

• 返回 Promise<any>，表示代码的执行结果。

使用示例:

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

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

剪贴板操作

以下是两个简单的方法，用于读取和设置剪贴板的内容。

getClipboard()

获取剪贴板的内容。

参数:

• 无

返回值:

• 返回 Promise<string> 剪贴板中的文本内容。

使用示例:

const clipboardText = await Util.getClipboard();
console.log('剪贴板内容:', clipboardText);

clipboardText = Util.getClipboard()
print('剪贴板内容:', clipboardText)

setClipboard(text)

将文本设置到剪贴板。

参数:

• text: string类型，设置到剪贴板的文本内容。

返回值:

• 无

使用示例:

await Util.setClipboard('Hello World');
console.log('已设置剪贴板内容为: Hello World');

Util.setClipboard('Hello World')
print('已设置剪贴板内容为: Hello World')