Squish的C++ API

本节介绍了 Squish 提供的 C++ API，以实现与 AUT 的更紧密集成，并解决偶尔出现的一些特定问题。

记录提示：影响和控制事件记录器

记录提示允许在测试工程师记录测试脚本时影响 Squish 的事件记录器。使用记录提示，应用程序可以在特定的位置向测试脚本中插入注释或函数调用。

通过 RecordHint 类实现记录提示功能。该类由 Squish 提供，并在 Squish 的 include 目录中的 recordhint.h 文件中定义。公开的 API 以内联形式实现在此文件中，因此应用程序只需要包含该文件本身——不需要链接到额外的库。

为了了解如何在实践中使用 RecordHint 类，我们将审查一个示例。

假设我们有一个应用程序，它定义了一个名为 myfunc 的函数，我们还将它包装，以便测试脚本可以访问它。当用户在应用程序中点击特定的按钮时，我们希望测试脚本调用 myfunc。为此，我们将在处理按钮点击的位置添加以下 C++ 代码

Squish::RecordHint myfunc_comment(Squish::RecordHint::Comment,
        "Call myfunc");
myfunc_comment.send();
Squish::RecordHint myfunc_caller(Squish::RecordHint::Function,
        "myfunc");
myfunc_caller.send();

现在，在录制脚本并点击按钮时，测试脚本中会生成两行额外的代码，如下面的代码片段所示

def main():
    ...
    clickButton("....")
    # Call myfunc
    myfunc()

function main()
{
    ...
    clickButton("....");
    // Call myfunc
    myfunc();
}

sub main
{
    ...
    clickButton("....");
    # Call myfunc
    myfunc();
}

# encoding: UTF-8
require 'squish'
include Squish

def main
    # ...
    clickButton("....")
    # Call myfunc
    myfunc()
    # ...
end

proc main {} {
    ...
    invoke clickButton "...."
    # Call myfunc
    invoke myfunc
}

这个小示例展示了何时以及如何使用记录提示。完整的 API 在 recordhint.h 文件中；在 Squish 命名空间内查找 RecordHint 类。

使用 Qt 内置钩子

在大多数情况下，Squish 无需任何特殊准备即可挂钩到 AUT。但是，由于操作系统的技术限制，在某些情况下，Squish 无法使用预加载程序。这适用于 Android、iOS 以及许多嵌入式系统。Squish 的内置钩子解决了这个问题。

需要将内置钩子添加到 AUT 的构建步骤中。所需的步骤因 AUT 所使用的构建系统而略有不同。最后，必须从应用程序代码中调用以下函数中的一个。将解释 cmake 和 qmake 的配置选项。

• Squish::allowAttaching(<tcp_port_number>) - AUT 需在 Squish 外部启动。它将在指定的端口上监听连接。这是注册可附加 AUT 的端口号。例如，在 Android 和 iOS 中使用此方法。
• Squish::installBuiltinHook() - 当使用静态链接的 Qt 时，允许通过 Squish 正常启动 AUT，例如，当动态预加载不起作用时。

在桌面操作系统上还需要额外的设置来启用内置钩子，这将在 强制内置钩子 中说明。如果没有这个设置，Squish 可能会尝试两次挂钩 AUT，一次是通过内置钩子，一次是通过动态挂钩。一次只能使用一种挂钩方法。

使用 cmake 的 Qt 内置钩子

对于 Qt 6 或更高版本，Squish 附带一个名为 SquishQtBuiltinHook 的 cmake 模块，该模块将 Qt 内置钩子集成到 Qt 应用程序构建中。

将以下语句添加到您的Qt项目中的CMakeLists.txt文件中，以将其转换为Squish的可附加AUT。

# Look for Squish, optional and allowed to fail
find_package(SquishQtBuiltinHook)
# Add Squish to application target if found
if(SquishQtBuiltinHook_FOUND)
    squish_qt_add_builtin_hook(<cmake_app_target> ATTACH_PORT <tcp_port_number>)
endif()

接下来，按照常规执行cmake（或Qt附带的cmake辅助程序qt-cmake），并设置SquishQtBuiltinHook_ROOT cmake变量，该变量为包含在应用程序中的Qt内置钩子的Squish安装前缀。对于交叉编译配置（Boot2Qt、Android、iOS、QNX），可能需要将路径追加到CMAKE_FIND_ROOT_PATH。

/home/user/Qt/6.5.0/gcc_64/bin/qt-cmake --fresh /path/to/application/sources -DSquishQtBuiltinHook_ROOT=/home/user/squish-7.1.1-qt65x-x86_64

SquishQtBuiltinHook cmake函数

只有一个可以调用的cmake函数。

squish_qt_add_builtin_hook(<target> [ATTACH_PORT <tcp_port_number>|BUILTIN|MANUAL] [EXTENSIONS <extname1> <extname2> ...])

第一个（必需）参数是要添加Qt内置钩子的构建目标。

添加Qt内置钩子有三种不同的模式，需要将其中之一作为参数传递。

• ATTACH_PORT <tcp端口号> - 等同于在应用程序启动期间调用Squish::allowAttaching(<tcp端口号>)。
• BUILTIN - 等同于在应用程序启动期间调用Squish::installBuiltinHook()。
• MANUAL - 将Squish包含目录添加到包含路径，并定义HAVE_SQUISH。应用程序代码必须在启动期间调用Squish::installBuiltinHook()或Squish::allowAttaching(<tcp端口号>)。

对于包含Squish的静态Qt构建，可以通过设置可选的EXTENSIONS关键字，后跟要与应用程序目标捆绑的Squish扩展名列表来控制扩展。如果未设置，要捆绑的扩展列表基于cmake应用程序目标的Qt依赖项列表。例如，如果目标依赖于Qt6::Quick，则Squish的QtQuick支持将自动选择。

使用qmake与Qt内置钩子

对于Qt 4或更高版本，Squish附带一个名为qtbuiltinhook.pri的qmake包含文件，该文件将Qt内置钩子集成到Qt应用程序构建中。

添加Qt内置钩子有三种不同的模式，由两个需要在包含qtbuiltinhook.pri之前设置的qmake变量控制。

• SQUISH_ATTACH_PORT = <tcp端口号> - 等同于在应用程序启动期间调用Squish::allowAttaching(<tcp端口号>)。此模式需要Qt >= 5.1。
• SQUISH_BUILTINHOOK = 1 - 等同于在应用程序启动期间调用Squish::installBuiltinHook()。此模式需要Qt >= 5.1。
• 未设置任一变量 - 将Squish包含目录添加到包含路径，并定义HAVE_SQUISH。应用程序代码必须在启动期间调用Squish::installBuiltinHook()或Squish::allowAttaching(<tcp端口号>)。

将以下语句添加到构建主应用程序目标的qmake项目文件中。这样做会将Qt应用程序转换为Squish的可附加AUT。

SQUISH_ATTACH_PORT = tcp_port_number
include(/path-to-squish/qtbuiltinhook.pri)

如果应该通过squishserver（仅在可以运行squishserver的平台上的平台上可用）启动应用程序，则添加以下语句

SQUISH_BUILTINHOOK = 1
include(/path-to-squish/qtbuiltinhook.pri)

必须在包含qtbuiltinhook.pri之前设置所有Squish钩子配置变量。该包含文件扩展了项目的SOURCE变量。因此，它需要插入到任何SOURCE =分配之后，例如在项目文件的底部。

接下来，按常规执行qmake以重新配置项目构建以包含Squish的Qt内置钩子，然后构建和部署项目。

对于静态Qt构建，需要显式配置包含Squish扩展，方法是将SQUISH_WRAPPER_EXTENSIONS qmake变量设置为一个应包含的Squish扩展名列表。

基于QtWidgets的应用程序示例

SQUISH_ATTACH_PORT = 4711
SQUISH_WRAPPER_EXTENSIONS = squishqgraphicsview squishqtabwidget
include(/home/user/squish-qt-6.2-static/qtbuiltinhook.pri)

基于QtQuick的应用程序示例

SQUISH_ATTACH_PORT = 4711
SQUISH_WRAPPER_EXTENSIONS = squishqtquick squishqtquicktypes
include(/home/user/squish-qt-6.2-static/qtbuiltinhook.pri)

通用Qt内置钩子说明

内置钩子可以被添加到任何构建系统中。这与在MANUAL模式下使用cmake模块的方式相同。需要对AUT进行两个修改

1. 将头文件qtbuiltinhook.h包含到应用程序代码中，该文件位于Squish的include目录中，在定义main函数的位置或者在创建QApplication对象的代码段。
2. 在创建QApplication对象后立即调用Squish::installBuiltinHook或Squish::allowAttaching函数。

示例

#include <QApplication>
#include "qtbuiltinhook.h"

int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    Squish::installBuiltinHook();
    // ...
    return app.exec();
}

这仅为您的程序在大多数不支持预加载机制的平台上可测试所必需的准备。在其他平台上留下此代码无关紧要，因为该函数足够智能，如果不需要，则不执行任何操作。

Squish::installBuiltinHook函数非常轻量，不会对程序性能产生影响。尽管如此，我们建议在程序的公开发布版本中移除它。这可以通过使用#ifdef来实现，为测试构建包含头文件和函数调用，而为发布构建排除它们。

详细说明

Squish::installBuiltinHook函数执行以下操作

• 如果未设置环境变量SQUISH_PREFIX，则不执行任何操作并立即返回。
• 否则，它将尝试从由SQUISH_PREFIX指定的目录中的lib（或bin）子目录加载Qt工具包支持库squishqtwrapper及其依赖项，并尝试在库中解析和调用初始化函数。如果找不到库或找到它但无法解析初始化函数，则不执行任何操作并返回。

Squish::installBuiltinHook函数在挂钩成功时返回true，即应用程序由Squish执行；否则，它返回false。

强制使用Qt内置钩子

内置钩子旨在用作在正常挂钩不起作用的平台上的后备机制。因此，如果您想在Squish支持非侵入式挂钩的平台使用内置钩子，Squish仍然默认使用非侵入式挂钩机制，尽管内置钩子包含在AUT中。

尽管如此，可以强制squishserver使用内置钩子而不是Squish的非侵入式挂钩机制。这可以通过设置squishserver配置选项来完成（请参阅配置squishserver）

squishserver --config setUsesBuiltinHook <aut> on

清除AUT钩子设置

要再次禁用注册AUT的内置钩子使用，请调用：squishserver --config setUsesBuiltinHook <aut> off

使用内置钩子附加到运行中的应用程序

还可以使用内置钩子机制附加到运行中的应用程序（有关附加到运行中的应用程序的更多详细信息，请参阅附加到运行中的应用程序）。

要使应用程序能够使用内置钩子附加，您必须在创建 QApplication 之后调用 Squish::allowAttaching 函数。此函数的参数是一个端口号，应用程序应监听该端口号以便 squishserver 连接。此函数在 qtbuiltinhook.h 中声明。

以下是将应用程序设置为可附加的标准模式

#include <QApplication>
#include "qtbuiltinhook.h"

int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    Squish::allowAttaching(11233);
    //...
    return app.exec();
}

• 包含 Squish 的 include 目录中的文件 qtbuiltinhook.h。
• 使应用程序监听端口号 11233。

使用 Squish 供提供的 start*aut 程序（位于 Squish 工具的 bin 目录）重新构建应用程序，以使其能够被 Squish 附加。现在，开始使用该程序启动 AUT。

startaut --uses-builtin-hook aut

这使 AUT 在指定端口上运行并监听，因此您现在可以从中测试脚本中附加到它。下一步是按照 注册可附加 AUT 中所述将 AUT 注册为可附加的 AUT。有关如何从测试脚本中附加到应用程序的详细信息，请参阅 从脚本附加。

但是，您可能需要创建或调整最多四个环境变量：SQUISH_PREFIX、LD_LIBRARY_PATH、DYLD_LIBRARY_PATH 和 PATH 以使 AUT 可附加。

如果通过网页下载并启动应用程序，则不能使用 startaut。在这种情况下，通过设置 SQUISH_PREFIX 环境变量以指向 Squish for Qt 目录来激活内置钩子。